Crate xc3_lib

A library for reading and writing rendering related file formats.

Xenoblade 1 DE, Xenoblade 2, and Xenoblade 3 are supported with Xenoblade 3 receiving the most testing. Struct documentation contains the corresponding type from Xenoblade 2 binary symbols where appropriate.

Getting Started

Each format has its own module based on the name of the type representing the root of the file. Only these top level types support reading and writing from files.

// Read from disk.
let mxmd = xc3_lib::mxmd::Mxmd::from_file("ch01011013.wimdo")?;
println!("{mxmd:#?}");

// Save to disk after making any changes.
mxmd.save("out.wimdo")?;

Design

xc3_lib provides safe, efficient, and robust reading and writing code for binary file formats. Each file format consists of a set of Rust types representing the structures in the binary file. xc3_lib uses derive macros to generate reading and writing code from the type and its attribute annotations. This avoids the need to separately document the format and reading and writing logic.

Each type is intended to be as specific as possible while still being able to generate a binary identical output. Enums are used instead of raw integers to reject unknown variants, for example. Each file is fully parsed and invalid input is not sanitized in any way. xc3_lib can validate the contents of a binary file by parsing it but cannot validate higher level constraints like entry indices being in range. These checks are performed by higher level libraries like xc3_model or xc3_wgpu.

Operations that would be impossible to reverse accurately like compression or byte buffers must be decoded and encoded in a separate step. This allows identical outputs when no modifications are needed to binary buffers.

Modules

• apmd
  Model archive for character and map models in .wimdo files.
• bc
  Animation and skeleton data in .anm or .motstm_data files or Sar1 archives.
• dds
  Conversions between Mibl and [Dds].
• dhal
  User interface Mibl images in .wilay files.
• error
  Shared error types for read and write operations.
• eva
  Camera animations in .eva files or embedded in .mot files.
• hash
  A collection of non-cryptographic hash functions used in game.
• lagp
  User interface Mibl images in .wilay files.
• laps
  User interface data in .wilay files.
• ltpc
  Texture container of Mibl images in .wiltp files.
• map
  Map data stored in compressed sections in .wismda files.
• mibl
  Textures in .witx or .witex files or embedded in .wismt files and other formats.
• msmd
  .wismhd files for map data that points to data in a corresponding .wismda files
• msrd
  Streamed model resources like shaders, geometry, or textures in .wismt files.
• mxmd
  Model data in .wimdo files.
• sar1
  Simple archive data in .arc, .chr, or .mot files.
• spch
  Compiled shaders in .wishp files or embedded in other formats.
• vertex
  Vertex and geometry data for models and map models.
• xbc1
  Compressed container used to store data in other formats.