User:Turtle Man/MDR (file format)

Unfinished MDR documentation, feel free to finish it.

MDR is a model format used by Star Trek Voyager: Elite Force. The format is used mostly for animated models, such as player legs and torso models. Unlike the MD3 format, the format uses skeletal animation instead of per-vertex animation.

File format[edit]

Data Type	Name	Description
U8	char	8-bit unsigned octet (character)
S16	short	little-endian signed 16-bit integer
S32	int	little-endian signed 32-bit integer
F32	float	IEEE-754 32-bit floating-point
VEC3	vec3_t	triplet of F32 in sequence (read 4 octets, make float, read 4, make float, read 4, make float), describing a 3-space vector
VEC4	vec4_t	Array of four F32 in sequence
*	[]	indicates sequential repeat count (homogenous aggregation, array, vector), as in "U8 * 16" to mean a 16-octet array (i.e. character string
-		file/array offset of which to make special note
!		aggregate complex data that should be described elsewhere

MDR header[edit]

Data Type	Name	Description
S32	IDENT	Magic number. As a string of 4 octets, reads "RDM5"
S32	VERSION	MDR version number, latest known is 2, but use the constant MDR_VERSION.
U8 * 64	NAME	MDR name, usually its pathname in the PK3. ASCII character string, NULL-terminated (C-style).
S32	NUM_FRAMES	Number of Frame objects, with a maximum of UNKNOWN.
S32	NUM_BONES	Number of Bone objects, with a maximum of UNKNOWN.
S32	OFS_FRAMES	Relative offset from start of MDR object where Frame objects start.
S32	NUM_LODS	Number of level of detail (LOD) objects.
S32	OFS_LODS	Relative offset from start of MDR object where LOD objects start.
S32	NUM_TAGS	Number of Tag objects, with a maximum of UNKNOWN.
S32	OFS_TAGS	Relative offset from start of MDR object where Tag objects start.
S32	OFS_EOF	Relative offset from start of MDR to the end of the MDR object.

Frame[edit]

General properties of a single animation frame. Frames are shared by all LODs.

Data Type	Name	Description
VEC3	MIN_BOUNDS	First corner of the bounding box.
VEC3	MAX_BOUNDS	Second corner of the bounding box.
VEC3	LOCAL_ORIGIN	Local origin, usually (0, 0, 0).
F32	RADIUS	Radius of bounding sphere.
U8 * 16	NAME	Name of Frame. ASCII character string, NUL-terminated (C-style)
!	BONES	Array of NUM_BONES (from MDR header) Bone objects.

Bone[edit]

Bone matrix. Offset is stored in matrix[0][3], matrix[1][3], matrix[2][3].

Data Type	Name	Description
VEC4 * 3	MATRIX	Bone orientation and offset.

Compressed Frame[edit]

General properties of a single animation frame. Compressed Frames are shared by all LODs.

Data Type	Name	Description
VEC3	MIN_BOUNDS	First corner of the bounding box.
VEC3	MAX_BOUNDS	Second corner of the bounding box.
VEC3	LOCAL_ORIGIN	Local origin, usually (0, 0, 0).
F32	RADIUS	Radius of bounding sphere.
!	BONES	Array of NUM_BONES (from MDR header) Compressed Bone objects.

Compressed Bone[edit]

Compressed Bone matrix.

Data Type	Name	Description
U8 * 24	COMP	Compressed Bone orientation and offset.

LOD[edit]

Level of detail object pointing to MDR surfaces.

Data Type	Name	Description
S32	NUM_SURFACES	Number of surfaces for this LOD.
S32	OFS_SURFACES	Relative offset from start of LOD to Surface objects.
S32	OFS_LOD	Relative offset from start of LOD to next LOD object. LODs are stored one after the other, so OFS_LOD is always set to the size of a LOD (12).

Tag[edit]

An attachment point for another MDR or MD3 model. Essentially MDR tags allow joints to be named.

Data Type	Name	Description
S32	BONE_INDEX	Bone index of the joint the tag is attached to.
U8 * 32	NAME	Name of Tag object. ASCII character string, NUL-terminated (C-style).

Surface[edit]

An animated triangle mesh.

Data Type	Name	Description
-	SURFACE_START	Offset relative to start of MDR object.
S32	IDENT	Magic number. Same as MDR header.
U8 * 64	NAME	Name of Surface object. ASCII character string, NUL-terminated (C-style).
U8 * 64	SHADER_NAME	Pathname of shader in the PK3. ASCII character string, NUL-terminated (C-style).
S32	SHADER_INDEX	Shader index number. No idea how this is allocated, but presumably in sequential order of definition.
S32	OFS_HEADER	Offset to MDR header. This will be a negative number.
S32	NUM_VERTS	Number of Vertex objects defined in this Surface, up to UNKNOWN.
S32	OFS_VERTS	Relative offset from SURFACE_START where the list of Vertex objects starts.
S32	NUM_TRIANGLES	Number of Triangle objects defined in this Surface, maximum of UNKNOWN.
S32	OFS_TRIANGLES	Relative offset from SURFACE_START where the list of Triangle objects starts.
S32	NUM_BONE_REFS	Number of Bone References. (Unused?)
S32	OFS_BONE_REFS	Relative offset from SURFACE_START where the list of Bone References starts. (Unused?)
S32	OFS_END	Relative offset from SURFACE_START to where the Surface object ends.
!	(Triangle)	List of Triangle objects usually starts immediately after the surface, but use OFS_TRIANGLES (+ SURFACE_START).
!	(Vertex)	List of Vertex objects usually starts immediate after the list of Triangle objects, but use OFS_VERTS (+ SURFACE_START). The total number of objects is NUM_VERTS.
-	SURFACE_END	End of Surface object. Should match OFS_END.

Triangle[edit]

Data Type	Name	Description
S32 * 3	INDEXES	List of offset values into the list of Vertex objects that constitute the corners of the Triangle object. Vertex numbers are used instead of actual coordinates, as the coordinates are implicit in the Vertex object. The triangles have clockwise winding.

Vertex[edit]

Data Type	Name	Description
VEC3	NORMAL	Normal for the vertex.
F32 * 2	TEX_COORDS	s and t texture coordinates, normalized to the range [0, 1]. Values outside the range indicate wraparounds/repeats. Unlike UV coordinates, the origin for texture coordinates is located in the upper left corner (similar to the coordinate system used for computer screens) whereas, in UV mapping, it is placed in the lower left corner. As such, the t value must be flipped to correspond with UV coordinates. See also Left-hand coordinates
S32	NUM_WEIGHTS	Number of influences on the vertex.
!	(Vertex Weight)	List of NUM_WEIGHTS vertex weights.

Vertex Weight[edit]

Data Type	Name	Description
S32	BONE_INDEX	Index of bone that is influencing vertex.
F32	WEIGHT	Force on vertex (0 to 1).
VEC3	OFFSET	TODO: Fill this in.

Compressed Bones[edit]

Encoding[edit]

TODO: Write.

Decoding[edit]