ultimate-research / ssbh_lib

Reading and writing SSBH file formats in Rust

ssbh_lib

Libraries and tools for working with the SSBH binary formats in Rust.

SSBH Formats

Click the links below to see the corresponding Rust source file with the file format's struct definitions. All SSBH formats start with the file magic HBSS and use the same representation for types like arrays and offsets.

Format	Supported Versions (major.minor)
Hlpb (.nuhlpb)	1.1
Matl (.numatb)	1.5, 1.6
Modl (.numdlb,.nusrcmdlb)	1.7
Mesh (.numshb)	1.8, 1.9, 1.10
Skel (.nusktb)	1.0
Anim (.nuanmb)	1.2, 2.0, 2.1
Nlst (.nulstb)	1.0
Nrpd (.nurpdb)	1.6
Nufx (.nufxlb)	1.0, 1.1
Shdr (.nushdb)	1.2

The ssbh_lib library also supports the non SSBH formats MeshEx (.numshexb) and Adj (.adjb).

If you find an SSBH format used in a game that isn't supported here, feel free to open a pull request to add it. The ssbh_lib types can also be used in your own project with the BinRead and SsbhWrite derives to support new SSBH formats without needing to modify ssbh_lib.

Projects

Project	Description	Crate	Documentation
ssbh_lib	A library to read and write SSBH formats
ssbh_data	A high level API for reading and writing SSBH data

For making quick edits to SSBH files in a text editor, use ssbh_lib_json. ssbh_data_json supports fewer formats than ssbh_lib_json but adds the ability to decode and edit the buffer data in Mesh or Anim files. Python bindings for ssbh_data are available with ssbh_data_py.

Tools

• ssbh_data_json - convert ssbh_data types to and from JSON
• ssbh_lib_json - convert ssbh_lib types to and from JSON
• ssbh_test - test read/write for a game dump

Building

With a recent version of Rust installed, run cargo build --release.

Credits

• SSBHLib - the original C# implementation for reading and writing SSBH files
• geometry_tools - vertex data and geometry bounding calculations
• binrw - binary parsing library and inspiration for porting the C# implementation to Rust
• glam - efficient vector and matrix math using SIMD
• see the Cargo.toml files for the remaining projects used