SMD file format

The SMD (Studio Model Data) file format stores 3D geometry data in ASCII, for analysis and compilation by studiomdl. SMD files are usually generated by the SMD exporter plug-in for a given model editor package.

The format is carriage return sensitive — each line must end with a carriage return. The file should also include at least one carriage return after the final end statement. White space is the only delimiter; any combination of tabs and spaces can be used to separate values, and for this reason multiword names should be enclosed in quotation marks (").

Types of SMD

SMD files come in two flavors, Reference and Animation files. Although one file can contain both.

The Reference SMD file is a complete snapshot of the model, including its geometry, its skeletal structure, one animation frame to describe the position of the skeletal bones, its texture, and the links between its mesh vertices and its skeleton. Reference SMDs do not contain any animation data — they produce only a static image of the complete model at one point in time.

The Animation SMD omits the triangle and texture map data and contains only animation and skeletal data.

In addition, VTA files (facial animation) use a similar format to SMD, but contain only vertex animation data.

SMD file sections

Here are the sections of an SMD file, considered in order:

Header data

The only header data required is the tag version 1 in the first line of the file. This is compatible with both HL1 and HL2.

Node tree data

Builds a list of all the bones in the skeleton. Each bone has a unique ID number, a unique text name and a pointer to the ID number of its parent. Children of the world use –1 as their parent ID. ID numbers are integers (starting from 0). Names are text, enclosed in quotes. Names may contain spaces.

• nodes

Starts the node tree data block.

• <ID> "Bone Name" <parent ID>

<ID> is a the ID number for this bone. "Bone Name" is a text name for the bone, enclosed in quotes. <parent ID> is the ID number of the bone’s parent. Children of the world (unparented objects) have a parent ID of -1.

• end

Ends the node tree data block.

Skeleton Pose data

This block contains the position and rotation data for every bone in the skeleton. In an animation SMD there will be a "time" block for every frame in the animation. In reference SMDs there will only be one time block.

The skeleton block is begun by the skeleton tag and ended by an end tag. A time block begins with time <frame> and end when a new "time" tag is encountered.

Each frame is defined by a line telling the frame number, e.g. time 0, followed by the bone's new position and rotations. The frame will end when a new one is defined or the end of the skeleton tree is reached. The frames doesn't have to start at 0 (it can also be negative), but they have to increase in numbers. Frames may be skipped, they will then be linearly interpolated instead.

• Skeleton

Begins the skeleton pose block.

• Time 0

Begins this time block

• <ID> <PosX> <PosY> <PosZ> <RotX> <RotY> <RotZ>

<ID> is the bone ID. <PosX> <PosY> <PosZ> is the position in world units (good to 6 significant digits). <RotX> <RotY> <RotZ> are local Euler rotations in radians. Bones which are not children of the world report their position and rotations in their parent's local space.

• Time 1

Begins the next time block. Any bone without changes from the last frame doesn't have to be entered, but will be linearly interpolated if a new position is later defined.

• end

Ends skeleton pose block.

Triangle block

The triangle block contains a list of triangles. Each triangle is preceded by a texture file name (filename only — path data is supplied in the QC file as $cdmaterials). Each vertex of the triangle then reports its parent bone’s ID (Bone with the highest weights value), the vertex's position, the vertex's texture coordinates, its normals, and bone weights (bone weights can be omitted per vertex).

The Triangle block is begun with the triangles tag and ends with the end tag.

• Triangles

Begins the triangle block

• texturename.*

Name of the texture file for the texture assigned to this face, including the file suffix like .tga. Do not enclose in quotes.

• <Parent> <PosX> <PosY> <PosZ> <NormX> <NormY> <NormZ> <TexU> <TexV> <# of links> <bone ID> <weight> [...]

<Parent> is the ID number of the vertex's parent bone. <PosX> <PosY> <PosZ> is the position of the vertex in world space. <NormX> <NormY> <NormZ> are the components of the vertex's normal vector (used for smoothing the suface). <TexU> and <TexV> are the texture coordinates for this vertex.

<bone ID> <weight> will be looped at the end of each vertex <# of links> times.

If the weights don't add up to 1.0 the rest will be assigned to the <Parent> bone. Same if no <# of links> is defined or if it is 0.

Each triangle contains 3 vertex records.

• nextTextureName.tga

new texture file begins a new triangle listing

• end

ends triangle block.

Vertex Animation Files

VTA files contain the position and normal data for every vertex in the model. There will be a "time" block for every frame in the vertex animation.

The vertex animation is begun by the vertexanimation tag and ended by an end tag. Time block begin with time <frame> and end when a new "time" tag is encountered or the end of the vertex animation block is reached.

• vertexanimation

Begins the vertex animation block

• Time 0

Begins this time block. Time 0 serves as vertex index, so it should have all vertices of the model giving a index number for each.

• <ID> <PosX> <PosY> <PosZ> <NormX> <NormY> <NormZ>

<ID> is the vertex ID. <PosX> <PosY> <PosZ> is the position in world units (good to 6 significant digits). <NormX> <NormY> <NormZ> are the components of the vertex's normal vector

• Time 1

Begins next time block.

• end

Ends vertex animation block