MD3 file format: header, frames and tags

MD3 has no written specification. It is defined by the header file qfiles.h in the Quake III Arena source code, released by id Software under the GPL in 2005, and by the renderer’s loader, tr_model.c. This page follows both. Numbers are little-endian: 32-bit integers and floats, and 16-bit integers where noted. Names are 64-byte fields (MAX_QPATH) ended by a zero byte.

Header

The header (md3Header_t) is 108 bytes at the start of the file. Offsets are counted from the start of the file.

Offset	Size	Type	Name	Meaning
0	4	char[4]	`ident`	`IDP3` (`49 44 50 33`), 0x33504449 read as an integer
4	4	int32	`version`	15. The game warns and refuses the model for any other value
8	64	char[64]	`name`	Model name, usually its path in the game
72	4	int32	`flags`	No flags are defined; the engine does not read it
76	4	int32	`numFrames`	Animation frames, 1 to 1024; the game refuses a model with none
80	4	int32	`numTags`	Tags in each frame, at most 16
84	4	int32	`numSurfaces`	Surfaces (separate meshes), at most 32
88	4	int32	`numSkins`	Not used by the engine
92	4	int32	`ofsFrames`	Offset of the first frame
96	4	int32	`ofsTags`	Offset of the tags: `numFrames` × `numTags` of them
100	4	int32	`ofsSurfaces`	Offset of the first surface; each surface says where the next begins
104	4	int32	`ofsEnd`	Offset of the end of the file, which is its size

The limits are the constants in qfiles.h: MD3_MAX_FRAMES 1024 per model, MD3_MAX_TAGS 16 per frame, MD3_MAX_SURFACES 32 per model, and per surface MD3_MAX_SHADERS 256, MD3_MAX_VERTS 4096 and MD3_MAX_TRIANGLES 8192. Quake III’s own renderer is stricter: it stops with an error if a surface has more than 1000 vertices or more than 2000 triangles (SHADER_MAX_VERTEXES and SHADER_MAX_INDEXES ÷ 3).

Frames

numFrames entries of 56 bytes at ofsFrames (md3Frame_t). A frame here holds only the pose’s bounds; the vertex positions for each frame are inside the surfaces.

Offset	Size	Type	Name	Meaning
0	12	float32[3]	`bounds[0]`	Minimum x, y, z of the pose
12	12	float32[3]	`bounds[1]`	Maximum x, y, z of the pose
24	12	float32[3]	`localOrigin`	Local origin of the frame
36	4	float32	`radius`	Radius of a sphere around the pose, used for culling
40	16	char[16]	`name`	Frame name, ended by a zero byte

The file has no list of animations. Quake III player models take frame ranges from a separate text file, animation.cfg, beside the models.

Tags

A tag is a named point with an orientation, used to attach one model to another. The tags are stored frame by frame: all numTags tags of frame 0, then all of frame 1, and so on, so tag t of frame f starts at ofsTags + (f × numTags + t) × 112. Each tag is 112 bytes (md3Tag_t).

Offset	Size	Type	Name	Meaning
0	64	char[64]	`name`	Tag name, such as `tag_head`
64	12	float32[3]	`origin`	Position of the tag in this frame
76	36	float32[3][3]	`axis`	Three unit vectors, the tag’s own x, y and z axes: a 3 × 3 rotation

To attach a child model, the engine places the child’s origin at the parent tag’s origin and turns it by the tag’s axes, blending both between frames. Quake III’s game code looks for these names: on the lower body tag_torso; on the upper body tag_head, tag_weapon and tag_flag (a carried flag); on weapons tag_barrel and tag_flash.

Levels of detail

A model may come with simpler versions of itself in separate files. When the game loads name.md3 it also looks for name_1.md3 and name_2.md3 (MD3_MAX_LODS is 3) and draws the simpler ones at a distance. Only the base file is required. Each file is a complete MD3 in its own right.

.MD3 File Format – Header, frames and tags

Header

Frames

Tags

Levels of detail