MD2

.md2 File Format Specification

by Daniel E. Schoenblum

INTRO

This page will try and give some sort of technical documentation on the Quake2 model format (.md2).

These specs can be used freely for whatever you want. I only ask that people send me corrections, suggestions, etc.

Quake2 models are stored in files with the .md2 extension. This is a custom format used only by Quake2 and (probably) Quake2 mission packs. md2 files can be generated from various other file formats by tools provided freely by id, in original and modified form. A single md2 file contains the model's geometry, frame information, skin filename(s), and texture coordinates. The file is little-endian (intel byte ordering).

HEADER

The header comes right at the start of the file. The information in the header is needed to load different parts of the model.

typedef struct {

   int magic;  
   int version;  
   int skinWidth;  
   int skinHeight;  
   int frameSize;  
   int numSkins;  
   int numVertices;  
   int numTexCoords;  
   int numTriangles;  
   int numGlCommands;  
   int numFrames;  
   int offsetSkins;  
   int offsetTexCoords;  
   int offsetTriangles;  
   int offsetFrames;  
   int offsetGlCommands;  
   int offsetEnd;

} model_t;

model_magic

int magic: A "magic number" used to identify the file. The magic number is 844121161 in decimal (0x32504449 in hexadecimal). The magic number is equal to the int "IDP2" (id polygon 2), which is formed by ('I' + ('D' << 8) + ('P' << 16) + ('2' << 24)).

model_version

int version: Version number of the file. Always 8.

model_skinWidth

int skinWidth: Width of the skin(s) in pixels.

model_skinHeight

int skinHeight: Height of the skin(s) in pixels.

model_frameSize

int frameSize: Size of each frame in bytes.

model_numSkins

int numSkins: Number of skins associated with this model.

model_numVertices

int numVertices: Number of vertices in each frame.

model_numTexCoords

int numTexCoords: Number of texture coordinates (not necessarily the same as the number of vertices).

model_numTriangles

int numTriangles: Number of triangles in each frame.

model_numGlCommands

int numGlCommands: Number of dwords (4 bytes) in the gl command list.

model_numFrames

int numFrames: Number of frames.

model_offsetSkins

int offsetSkins: Offset, in bytes from the start of the file, to the list of skin names.

model_offsetTexCoords

int offsetTexCoords: Offset, in bytes from the start of the file, to the list of texture coordinates.

model_offsetTriangles

int offsetTriangles: Offset, in bytes from the start of the file, to the list of triangles.

model_offsetFrames

int offsetFrames: Offset, in bytes from the start of the file, to the list of frames.

model_offsetGlCommands

int offsetGlCommands: Offset, in bytes from the start of the file, to the gl command list.

model_offsetEnd

int offsetEnd: Offset, in bytes from the start of the file, to the end (size of the file).

FRAMES

Each frame contains the positions in 3D space for each vertex of each triangle that makes up the model. Quake 2 (and Quake) models contain only triangles.

typedef struct
{
    byte [[#triangleVertex_vertex|vertex]][3];
    byte [[#triangleVertex_lightNormalIndex|lightNormalIndex]];
} triangleVertex_t;

triangleVertex_vertex

byte vertex[3]: The three bytes represent the x, y, and z coordinates of this vertex. This is not the "real" vertex coordinate. This is a scaled version of the coordinate, scaled so that each of the three numbers fit within one byte.

triangleVertex_lightNormalIndex

byte lightNormalIndex: This is an index into a table of normals kept by Quake2.

TRIANGLES

Quake 2 models are made up of only triangles. At offsetTriangles in the file is an array of triangle_t structures.

typedef struct
{
    short [[#triangle_vertexIndices|vertexIndices]][3];
    short [[#triangle_textureIndices|textureIndices]][3];
} triangle_t;

triangle_vertexIndices

short vertexIndices: These three shorts are indices into the array of vertices in each frame.

triangle_textureIndices

short textureIndices: These three shorts are indices into the array of texture coordinates.

SKINS

There is an array of numSkins skin names stored at offsetSkins into the file. Each skin name is a char[64]. The name is really a path to the skin, relative to the base game directory (baseq2 for "standard" Quake2). The skin files are regular PCX files.

GL COMMANDS

At offsetGlCommands bytes into the file, there is the gl command list.

typedef struct {

   float s, t;
   int vertexIndex;

} glCommandVertex_t;

glCommandVertex_st

float s, t: These two floats are used to map a vertex onto a skin.

glCommandVertex_vertexIndex

int vertexIndex: Index into the array of vertices stored in each frame.

MAXIMUMS

Quake2 has some pre-defined limits:

• Triangles: 4096
• Vertices: 2048
• Texture Coordinates: 2048
• Frames: 512
• Skins: 32

Quake and Quake2 are trademarks of id Software. All trademarks used are properties of their respective owners.