Crate ssbh_lib[−][src]
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. The library serves two purposes.
The first is to provide high level and unambiguous documentation for the SSBH binary formats. Strongly typed wrapper types such as RelPtr64 replace ambiguous u64 offsets. Enums and bitfields provide additional typing information vs u8 or u64 fields. The structs and types in each of the format modules fully represent the binary data contained in the file. This ensures the binary output of reading and writing a file without any modifications is identical to the original.
The second is to eliminate 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 calcualating relative offsets and alignment.
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.
Example
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; use ssbh_lib::RelPtr64; use ssbh_lib::SsbhString; use ssbh_lib::SsbhWrite; use ssbh_write_derive::SsbhWrite; use binread::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. |
Structs
CString | A null terminated string with a specified alignment.
The empty string is represented as |
Color4f | 4 contiguous floats for encoding RGBA data. |
DebugPosition | A wrapper type that serializes the value and absolute offset of the start of the value to aid in debugging. |
Half | A half precision floating point type used for data in buffers that supports conversions to and from |
InlineString | A C string stored inline. This will likely be wrapped in a pointer type. |
Matrix3x3 | A row-major 3x3 matrix of contiguous floats. |
Matrix4x4 | A row-major 4x4 matrix of contiguous floats. |
Ptr64 | A 64 bit file pointer relative to the start of the buffer or file. |
RelPtr64 | A 64 bit file pointer relative to the start of the pointer type. |
Ssbh | The container type for the various SSBH formats. |
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 |
SsbhEnum64 | Parses a struct with a relative offset to a structure of type T with some data type.
Parsing will fail if there is no matching variant for |
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. |
Vector3 | 3 contiguous floats for encoding XYZ or RGB data. |
Vector4 | 4 contiguous floats for encoding XYZW or RGBA data. |
Enums
ReadSsbhError | Errors while reading SSBH files. |
SsbhFile | The associated magic and format for each SSBH type. |
Traits
SsbhWrite | A trait for exporting types that are part of SSBH formats. |