xc3_lib

Rust libraries and tools for working with rendering related file formats for Xenoblade Chronicles 1 DE, Xenoblade Chronicles 2, and Xenoblade Chronicles 3.

Report any bugs or request new features in issues. Download precompiled binaries for the tools in releases. Python bindings for xc3_model are available with xc3_model_py.

Formats

xc3_lib supports a number of in game formats. All formats support reading. Write support is still a WIP for some formats. Click on the links to open the corresponding Rust module in xc3_lib.

Extensions starting with wi are for the Switch. Some formats have equivalent formats for desktop PCs starting with pc like pcmdo instead of wimdo. The PC formats aren't as well supported by xc3_lib since they aren't used in game and have few example files.

Format	Magic	Extensions	Read	Write
Apmd	DMPA	`wimdo`	✔️	✔️
Bc	BC	`anm`, `motstm_data`	✔️	✔️*
Dhal	LAHD	`wilay`	✔️	✔️*
Eva	eva	`eva`	✔️	✔️*
Lagp	LAGP	`wilay`	✔️	✔️*
Ltpc	LTPC		✔️	✔️
Mibl	LBIM	`wismt`, `witex`, `witx`	✔️	✔️
Msmd	DMSM	`wismhd`	✔️	❌
Msrd	DRSM	`wismt`	✔️	✔️*
Mxmd	DMXM	`wimdo`	✔️	✔️*
Sar1	1RAS	`arc`, `chr`, `mot`	✔️	✔️
Spch	HCPS	`wishp`	✔️	✔️
Xbc1	xbc1	`wismt`	✔️	✔️

* Some files are not binary identical with the originals after saving.

Projects

See Architecture for a design overview of the various projects. Click on the docs.rs links below to see the generated rustdoc documentation.

Libraries

- file format library
- higher level API for xc3_lib
- model and map renderer
- binary writing and layout

Binaries

xc3_gltf - convert models and maps to glTF
xc3_test - test against files in an extracted dump
xc3_tex - convert textures to and from DDS and images
xc3_viewer - simple model viewer for testing xc3_wgpu
xc3_wgpu_batch - batch render models and maps to PNG

Usage

These projects are still highly unstable. When using the latest version from github, specify a specific git revision or commit the Cargo.lock file to source control. This locks the version and avoids any breaking changes. The debug or JSON output has not stabilized and should not be assumed to be the same between commits.

xc3_model = { git = "https://github.com/ScanMountGoat/xc3_lib", rev = "commit_hash" }
xc3_wgpu = { git = "https://github.com/ScanMountGoat/xc3_lib", rev = "commit_hash" }
xc3_lib = { git = "https://github.com/ScanMountGoat/xc3_lib", rev = "commit_hash" }

Building

After installing the Rust toolchain, run cargo build --release in the repository directory. Running cargo build without the --release will result in faster compile times during development but dramatically worse runtime performance. The tools can be run using cargo run --release -p <project> <args>. xc3_tex uses image_dds, which supports Windows x86, Linux x86, MacOS x86, and MacOS Apple Silicon due to using precompiled kernels for DDS encoding. Other projects should build on other platforms without issues.

Credits

This project is based on previous reverse engineering work, including work done for Xenoblade 2. Special thanks go to members of the World Tree Research discord (formerly the World of Alrest discord) for their assistance.

xc3_lib 0.3.0