Crate brres 

brres

BRRES (.brres) is Nintendo’s first-party 3D model format for the Nintendo Wii. Used in games like Mario Kart Wii, Twilight Princess and Super Smash Bros: Brawl, .brres is a versatile and efficient file format. Nearly all data is stored as raw GPU display lists that are directly read by the Wii’s “flipper” GPU.

File format: .brres

At the very root, “.brres” is an archive format for the following sub-files. All but SHP0 are supported.

Filetype	Description	Rust structure
BRRES v0	3D Resource	Archive
MDL0 v11	3D Model	Model
TEX0 v1/v3	Texture	Texture
SRT0 v5	Texture scale/rotate/translate animation	JSONSrtData
VIS0 v4	Bone visibility animation	JSONVisData
CLR0 v4	Shader uniform animation	JSONClrAnim, editing limitations
CHR0 v4	Bone/character animation	ChrData, editing limitations
PAT0 v4	Texture image animation	JSONPatAnim, editing limitations
SHP0	Vertex morph animation	Unsupported

File format: .mdl0

Filetype	Description	Rust structure
MDL0.ByteCode	Draw calls + Skeleton	Merged into JSONBoneData, JSONDrawMatrix
MDL0.Bone	Bone	JSONBoneData
MDL0.PositionBuf	Holds vertex positions	VertexPositionBuffer
MDL0.NormalBuf	Holds vertex normals	VertexNormalBuffer
MDL0.ColorBuf	Holds vertex colors	VertexColorBuffer
MDL0.UVBuf	Holds UV maps	VertexTextureCoordinateBuffer
MDL0.FurVecBuf	Fur related	Not supported
MDL0.FurPosBuf	Fur related	Not supported
MDL0.Material	Material data	JSONMaterial
MDL0.TEV	Shader data	Merged into JSONMaterial
MDL0.Mesh	3D mesh data	Mesh
MDL0.TextureLink	Internal	Recomputed
MDL0.PaletteLink	Internal	Recomputed
MDL0.UserData	Metadata	Not supported

Thus, the Rust view of a MDL0 file looks like this:

use brres::*;
use brres::json::*;

struct Model {
    pub name: String,
    pub info: JSONModelInfo,

    pub bones: Vec<JSONBoneData>,
    pub materials: Vec<JSONMaterial>,
    pub meshes: Vec<Mesh>,

    // Vertex buffers
    pub positions: Vec<VertexPositionBuffer>,
    pub normals: Vec<VertexNormalBuffer>,
    pub texcoords: Vec<VertexTextureCoordinateBuffer>,
    pub colors: Vec<VertexColorBuffer>,

    /// For skinning
    pub matrices: Vec<JSONDrawMatrix>,
}

Reading a file

Read a .brres file from a path on the filesystem.

let archive = brres::Archive::from_path("kuribo.brres").unwrap();
assert!(archive.models[1].name == "kuribo");

println!("{:#?}", archive.get_model("kuribo").unwrap().meshes[0]);

Read a .brres file from a raw slice of bytes.

let raw_bytes = std::fs::read("kuribo.brres").expect("Expected kuribo :)");

let archive = brres::Archive::from_memory(&raw_bytes).unwrap();
assert!(archive.models[1].name == "kuribo");

println!("{:#?}", archive.get_model("kuribo").unwrap().meshes[0]);

Writing a file

(to a file)

let kuribo = brres::Archive::from_path("kuribo.brres").unwrap();
let buf = kuribo.write_path("kuribo_modified.brres").unwrap();

(to memory)

let kuribo = brres::Archive::from_path("kuribo.brres").unwrap();
let buf = kuribo.write_memory().unwrap();
std::fs::write("kuribo_modified.brres", buf).unwrap();

Current limitations

• PAT0, CLR0 and CHR0 support is slightly less than ideal. In particular, existing code emphasizes bit-perfect rebuilding, but lacks the flexibility useful for editing. Future versions should address this.
• The internal parts of the library are written in C++. Additionally, the clang compiler is needed on Windows. The Microsoft Visual C++ compiler cannot be used.
• A lot of documentation is still needed.
• SHP0 is unsupported, although almost never used.
• Only V11 MDL0 is supported. For older titles we should support older (and newer) versions (v7: Wii Sports?, v9: Brawl, v12: Kirby, etc.)
• JSON* structures probably shouldn’t be directly exposed.
• The names of enum values do not always follow Rust convention.

Modules

enums

json

JSON middle-layer for communication between the inner library (C++) and this Rust layer.

Structs

Archive

Corresponds to a single .brres file

ChrData

Bone (character motion) animation

ChrFrame

Hermine spline point in an animation curve. We use f64 because the quantized fixed-point numbers have far more precision than f32 allows (and without this, we wouldn’t currently support 1:1 matching on encode-decode.)

ChrNode

Describes the animations being applied to a single Bone.

ChrTrack

Animation curve data.

MatrixPrimitive

A group of triangles sharing the same skinning information. In unrigged models, there will only be one MatrixPrimitive per Mesh.

Mesh

Holds triangle data.

Model

Corresponds to a single MDL0 file

Texture

Holds a hardware-encoded image. Potentially may store multiple mip levels in a hierarchy. See https://en.wikipedia.org/wiki/Mipmap#Mechanism.

VertexColorBuffer

Holds vertex colors.

VertexNormalBuffer

Holds normal vectors of vertices in 3D space.

VertexPositionBuffer

Holds positions of vertices in 3D space.

VertexTextureCoordinateBuffer

Holds vertex UV coordinates.

Functions

read_mdl0mat_preset_folder

Read a .mdl0mat preset folder TODO: Add test