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.

beb

Cutscene data in .beb files.

beh

Cutscene data in .beh files.

bmn

User interface data in .bmn files.

datasheet

Structured data in .bin files or embedded in .beh files.

dds

Utilities for Dds image files.

dhal

User interface Mibl images in .wilay files.

efb0

Effects in .wiefb files.

error

Error types for read and write operations.

eva

Camera animations in .eva files or embedded in .mot files.

fnt

Fonts in .fnt files.

hash

A collection of non-cryptographic hash functions used in game.

hkt

Skeletons in .hkt files.

idcm

Collisions in .idcm files or embedded in other files.

laft

Fonts in .wifnt files.

lagp

User interface Mibl images in .wilay files.

laps

User interface data in .wilay files.

last

Font styles in .wisty files.

ltpc

Texture container of Mibl images in .wiltp files.

map

Map streaming data 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.

mths

Compiled shaders in .cashd files or embedded in .camdo files.

mtxt

Textures in .catex, .calut, or .caavp files or embedded in .casmt files and other formats.

mxmd

Model data in .wimdo files.

offset

Utilities for validating offsets during parsing.

sar1

Simple archive data in .arc, .chr, or .mot files.

spch

Compiled shaders in .wishp files or embedded in other formats.

spco

vertex

Vertex and geometry data for models and map models.

wipac

Effects in .wipac files.

xbc1

Compressed container used to store data in other formats.

Structs

Offset32

StringOffset32