.MDL File Format – Sequences and animation

Animation descriptions

mstudioanimdesc_t, 100 bytes, at the header’s localanimindex.

Sections

An mstudioanimsections_t is 8 bytes: animblock and animindex (ints). With sections the animation is cut into runs of sectionframes frames, each with its own data, so one frame can be found without reading the whole animation.

Movements

mstudiomovement_t, 44 bytes: endframe (int), motionflags (int, the motion types), v0 (velocity at the start of the block), v1 (at the end), angle (yaw rotation at the end of the block’s movement), vector (movement relative to the block’s initial angle), and position (relative to the start of the animation; the header marks it with question marks).

Local hierarchy

mstudiolocalhierarchy_t, 48 bytes: iBone (the bone being adjusted), iNewParent, start, peak, tail, end (floats: beginning of influence, start of full influence, end of full influence, end of all influence), iStart (first frame), localanimindex (offset of an mstudiocompressedikerror_t, see Skeleton) and four unused ints.

Per-bone animation data

An animation’s data is a chain of mstudioanim_t records, one per animated bone. Each starts with 4 bytes and is followed by data chosen by the flags.

The header’s accessors place the data as follows. The rotation data starts at offset 4. A raw position follows the raw rotation: after a Quaternion48 if RAWROT is set, after a Quaternion64 if RAWROT2 is set. With animated data the position value pointer follows the rotation value pointer if ANIMROT is set, and starts at offset 4 if it is not.

Value streams

mstudioanim_valueptr_t is 6 bytes: offset[3], three shorts, one each for x, y and z. An offset is from the start of this value pointer to a value stream; 0 or negative means there is none for that axis. A stream is made of mstudioanimvalue_t entries, a union of two bytes (valid, total) or one short value. The header declares that union and nothing more, so the run-length coding that decides which entry is a count and which a value, and how the bone’s posscale and rotscale are applied, is not described here (see Not described). The bit layouts of Vector48, Quaternion48 and Quaternion64 are likewise defined outside this header.

Sequence descriptions

mstudioseqdesc_t, 212 bytes, at the header’s localseqindex.

Events

mstudioevent_t, 80 bytes.

Auto layers

mstudioautolayer_t, 24 bytes: iSequence (int16), iPose (int16), flags (int32), and the floats start, peak, tail, end (beginning of influence, start of full influence, end of full influence, end of all influence).

Flags

Pose parameters, transitions and included models

A pose parameter, mstudioposeparamdesc_t at localposeparamindex, is 20 bytes: sznameindex (int), flags (int; the header’s comment is “????”), start, end and loop (floats; loop is the looping range, 0 for no looping, 360 for rotations).

The transition graph is numlocalnodes × numlocalnodes bytes at localnodeindex, read as from × numlocalnodes + to by the header’s pLocalTransition accessor, and an array of name offsets (from the file start) at localnodenameindex.

Included models, mstudiomodelgroup_t at includemodelindex, are 8 bytes: szlabelindex (a text name) and sznameindex (the file name), both from the start of the record. They name external animation and model files (the header’s comment). The animation block table, mstudioanimblock_t (8 bytes: datastart, dataend), at animblockindex, divides the .ani file named by szanimblocknameindex. Block 0 is not used by the accessor, which asserts an index above 0.