Skip to main content

Module mdl

rakata_formats

Module mdl 

Source
Expand description

MDL binary model support. MDL binary model reader and writer.

MDL is the 3D model format used by the Odyssey engine (KotOR/KotOR2). Each model consists of two files: an MDL file containing the node tree, controllers, and metadata, and a companion MDX file containing interleaved per-vertex attribute data.

The binary variant uses a 12-byte wrapper followed by a memory-mapped content blob. All internal offsets are content-relative (byte 0 = wrapper end = on-disk byte 12).

Past the two headers almost nothing sits at a fixed address. Every block is reached by reading a pointer out of an earlier one, and those pointers are content-relative, so a reader adds the 12-byte wrapper to each before seeking. Vanilla lays the blocks out as name table, then animation headers, then the node tree, but that ordering is a convention rather than something the format enforces; the pointers are what locate a block.

  • The geometry header starts the content, and the model header follows it immediately. These two are the only fixed addresses.
  • The node tree hangs off a root pointer in the geometry header, and is walked by recursing each node’s own child array. Every node begins with the same 80-byte header; the type flags in it select what data follows.
  • Animation headers come from a counted array in the model header, and each one roots its own node tree.
  • Node names are indirect twice over: the model header points at an array of offsets, and each entry points at a NUL-terminated string.
  • Vertex data is not in this file. It lives in the companion MDX, addressed per mesh by an offset relative to that file rather than this one. Confusing the two is the bug this reader is most prone to.

Byte-level field maps are deliberately not repeated here, because two copies of an offset table drift and this one already had: the header disagreed with the manual about the width of supermodel_name until a corpus check settled it. They live in docs/src/formats/models/mdl.md, with the engine-side load pipeline in docs/src/internals/mdl_deep_dive.md.

§Two traps worth knowing before writing a reader

The file and the loaded struct are different maps. The engine copies the blob into memory and rewrites relative offsets in place, so several fields hold one thing on disk and another once resident. Content +0x4C is a plain 2 in the file and GetType() | 0x80 after load. The page documents the file; the deep dive documents the loaded form.

node_count is not the number of nodes in the file. It counts the resolved supermodel chain, so validating it against the nodes actually reachable rejects hundreds of correct retail models. For a model with no supermodel the two agree exactly.

Re-exports§

pub use ascii_reader::read_mdl_ascii;
pub use ascii_reader::read_mdl_ascii_from_str;
pub use ascii_writer::write_mdl_ascii;
pub use ascii_writer::write_mdl_ascii_to_string;
pub use ascii_writer::MdlAsciiError;
pub use controllers::MdlController;
pub use controllers::MdlControllerType;
pub use controllers::MdlKey;
pub use reader::read_mdl;
pub use reader::read_mdl_from_bytes;
pub use types::AabbNode;
pub use types::MdlAabb;
pub use types::MdlAnimMesh;
pub use types::MdlCamera;
pub use types::MdlDangly;
pub use types::MdlEmitter;
pub use types::MdlFace;
pub use types::MdlLight;
pub use types::MdlMesh;
pub use types::MdlNodeData;
pub use types::MdlReference;
pub use types::MdlSaber;
pub use types::MdlSkin;
pub use writer::write_mdl;
pub use writer::write_mdl_to_vec;
pub use writer::write_mdl_with_mdx_to_vec;

Modules§

ascii_names
ASCII name registry for controllers, classifications, and node types. ASCII MDL name registry for controllers, classifications, and node types.
ascii_reader
ASCII MDL reader. ASCII MDL reader.
ascii_writer
ASCII MDL writer. ASCII MDL writer.
controllers
MDL controller types and keyframe structures. MDL controller types and keyframe structures.
node_flags
Bitflags for node type identification in the on-disk binary format.
orientation
Quaternion and axis-angle conversion utilities. Quaternion and axis-angle conversion utilities for MDL orientation data.
reader
MDL binary reader. MDL binary reader.
types
Node-specific data types. Node-specific data types for the MDL format.
writer
MDL binary writer. MDL binary writer.

Structs§

Mdl
The high-level MDL container.
MdlAnimEvent
An event that fires at a specific time during an animation.
MdlAnimNode
A node in an animation’s node tree.
MdlAnimation
A named animation sequence.
MdlNode
A node in the MDL hierarchy.
MdlWriteResult
Result of writing an MDL model with its companion MDX vertex data.

Enums§

MdlError
MDL binary parsing error type.

Functions§

assign_inverted_counters
Assigns the per-mesh sequence value to every mesh node in DFS tree order.