Crate ssbh_lib

source ·
Expand description

§ssbh_lib

ssbh_lib is a library for safe and efficient reading and writing of the SSBH binary formats used by Super Smash Bros Ultimate and some other games.

§Getting Started

The easiest way to access important items like Mesh is to import the prelude.

§Reading

If the file type isn’t known, try all available SSBH types.

use ssbh_lib::prelude::*;

let ssbh_file = SsbhFile::from_file("unknown_data.bin")?;
match ssbh_file.data {
    ssbh_lib::Ssbh::Hlpb(data) => println!("{:?}", data),
    ssbh_lib::Ssbh::Matl(data) => println!("{:?}", data),
    ssbh_lib::Ssbh::Modl(data) => println!("{:?}", data),
    ssbh_lib::Ssbh::Mesh(data) => println!("{:?}", data),
    ssbh_lib::Ssbh::Skel(data) => println!("{:?}", data),
    ssbh_lib::Ssbh::Anim(data) => println!("{:?}", data),
    ssbh_lib::Ssbh::Nlst(data) => println!("{:?}", data),
    ssbh_lib::Ssbh::Nrpd(data) => println!("{:?}", data),
    ssbh_lib::Ssbh::Nufx(data) => println!("{:?}", data),
    ssbh_lib::Ssbh::Shdr(data) => println!("{:?}", data),
}

In most cases, it’s possible to infer the type of file based on its extension.

let mesh = ssbh_lib::formats::mesh::Mesh::from_file("model.numshb")?;

See the documentation for Ssbh or any of the format types for additional reading methods.

§Writing

let mut writer = std::io::Cursor::new(Vec::new());
mesh.write(&mut writer)?;

For the best performance when writing directly to a file, it’s recommended to use the buffered write_to_file methods. Using other writers like std::io::BufWriter may give poor performance due to how relative offsets are written.

mesh.write_to_file("model.numshb")?;

§Derive Macros

The majority of the reading and writing code is automatically generated from the struct and type definitions using procedural macros. binread_derive generates the parsing code and ssbh_write_derive generates the exporting code. Any changes to structs, enums, or other types used to define a file format will be automatically reflected in the generated read and write functions when the code is rebuilt.

This eliminates the need to write tedious and error prone code for parsing and exporting binary data. The use of procedural macros and provided types such as SsbhString and SsbhArray enforce the conventions used by the SSBH format for calculating relative offsets and alignment.

§Examples

A traditional struct definition for SSBH data may look like the following.

struct FileData {
    name: u64,
    name_offset: u64,
    values_offset: u64,
    values_count: u64
}

The FileData struct has the correct size to represent the data on disk but has a number of issues. The values array doesn’t capture the fact that SSBH arrays are strongly typed. It’s not clear if the name_offset is an offset relative to the current position or some other buffer stored elsewhere in the file.

Composing a combination of predefined SSBH types such as SsbhString with additional types implementing SsbhWrite and BinRead improves the amount of type information for the data and makes the usage of offsets less ambiguous.


use ssbh_lib::{SsbhArray, RelPtr64, SsbhString};
use ssbh_write::SsbhWrite;
use binrw::BinRead;

#[derive(BinRead, SsbhWrite)]
struct FileData {
    name: SsbhString,
    name_offset: RelPtr64<SsbhString>,
    values: SsbhArray<u32>    
}

Now it’s clear that name and name_offset are both null terminated strings, but name_offset has one more level of indirection. In addition, values now has the correct typing information. The element count can be correctly calculated as values.elements.len(). The reading and writing code is generated automatically by adding #[derive(BinRead, SsbhWrite)] to the struct.

Modules§

  • formats
    The supported binary formats for reading and writing. All the supported formats are SSBH formats except for adj and meshex.
  • prelude
    Common imports for supported formats.

Structs§

  • CString
    A null terminated string with a specified alignment. The empty string is represented as N null bytes.
  • Color4f
    4 contiguous floats for encoding RGBA data.
  • Matrix3x3
    A column-major 3x3 matrix of contiguous floats.
  • Matrix4x4
    A column-major 4x4 matrix of contiguous floats.
  • Ptr
    A file pointer relative to the start of the reader.
  • RelPtr64
    A 64 bit file pointer relative to the start of the pointer type.
  • SsbhArray
    A fixed-size collection of contiguous elements consisting of a relative offset to the array elements and an element count.
  • SsbhByteBuffer
    A more performant type for parsing arrays of bytes that should always be preferred over SsbhArray<u8>.
  • SsbhEnum64
    Reads a struct with a relative offset to a structure of type T with some data type. Reading will fail if there is no matching variant for data_type.
  • SsbhFile
    The container type for the various SSBH formats.
  • Vector3
    3 contiguous floats for encoding XYZ or RGB data.
  • Vector4
    4 contiguous floats for encoding XYZW or RGBA data.
  • Versioned
    A versioned file format with a u16 major version and u16 minor version.

Enums§

  • ReadSsbhError
    Errors while reading SSBH files.
  • Ssbh
    The associated magic and format for each SSBH type.

Traits§

Type Aliases§

  • CString1
    A null terminated string without additional alignment requirements.
  • Ptr16
    A 16 bit file pointer relative to the start of the reader.
  • Ptr32
    A 32 bit file pointer relative to the start of the reader.
  • Ptr64
    A 64 bit file pointer relative to the start of the reader.
  • SsbhString
    A 4-byte aligned CString with position determined by a relative offset.
  • SsbhString8
    An 8-byte aligned CString with position determined by a relative offset.