xc3_lib

The goal of xc3_lib is to create the simplest possible API that can fully represent the binary data on disk. This means many buffers will not be decompressed, decoded, deswizzled, etc since this would make it harder to export a file binary identical with the original. Fully representing the binary files makes the public API more complex but makes it easy to test that reading and writing in game files results in identical data with a simple assert. Many xc3_lib types contain unresearched fields and padding fields to ensure that all data is preserved.

The struct and enum definitions also serve as file format documentation for the names and types of fields. Binary reading and writing is done in a declarative way with derive macros. Unlike a separate format wiki or binary template files, the code and documentation will always be in sync and can be tested with automated tests. The types also document the ordering of data items in a file via the write implementations.

Operations like deswizzling and decompression are implemented as functions that users must explicitly call to return a type representing the new data rather than modifying the original object. Types use plain data with no private fields, encapsulation, or change tracking of any kind. This helps ensure encoding or decoding operations are only performed once and avoids ambiguity about whether an object is in the encoded or decoded state. The to_dds operation for Mibl textures deswizzles and returns a new DdsFile file, for example. More advanced decoding operations are implemented in xc3_model.

xc3_lib does not make any attempt to be easy to integrate with other languages. Taking advantage of Rust's type system and code generation enables more idiomatic and robust code. Most applications should use higher level abstractions like xc3_model or the Python bindings available with xc3_model_py.