Sauerbraten Models

MD2 Format

MD2 files must be located in a directory in packages/models/, you must provide a skin (either skin.jpg or skin.png) and the md2 itself (tris.md2). Optionally you may provide a masks.jpg that holds a specmap in the R channel, a glowmap in the G channel, and a chrome map in the B channel. The engine will apply it automatically.

If either of these files is not found, Sauerbraten will search the parent directory for them. For example, if for the flags/red model, the tris.md2 is not found in packages/models/flags/red/, then it will look for tris.md2 in packages/models/flags/. This allows the sharing of skins and geometry.

Sauerbraten expects the md2 to use Quake-compatible scale and animations, unless you configure the model otherwise.

You may also supply a config file (md2.cfg) in your model directory, which allows you to customize the model's animations. The following commands may be used in an md2.cfg:

md2anim N F M [S [P]]

N is the name of the animation to define. Any of the following names may be used:

F is the frame number the animation starts at. M is the number of frames in the animation. S is the optional frames per second at which to run the anim. If none is specified, 10 FPS is the default. P specifies an optional priority for the animation (defaults to P=0).

For example, defining a "pain" animation starting at frame 50 with 6 frames and running at 30 frames per second would like like: md2anim "pain" 50 6 30

MD3 Format

MD3 file can be used for Sauerbraten in one of two ways.

Without Configuration

Go this way if your md3 has no animations (static) and takes only one texture, they must be located in a directory in packages/models/, and provide a skin (either skin.jpg or skin.png) and the md3 itself (tris.md3). Optionally you may provide a masks.jpg that holds a specmap in the R channel, a glowmap in the G channel, and a chrome map in the B channel. The engine will apply it automatically.

If either of these files is not found, Sauerbraten will search the parent directory for them. For example, if for the flags/red model, the tris.md3 is not found in packages/models/flags/red/, then it will look for tris.md3 in packages/models/flags/. This allows the sharing of skins and geometry.

With Configuration

MD3 files with animations multiple skins, or if you want to make use of other configuration possibilities, need to be set up this way. You must place a md3.cfg in a directory in packages/models/. This file specifies which models should be loaded, linked, etc. The following commands may be used in the md3.cfg:

md3load P

This command loads the first part of your model. As an example, this could be the head.md3 of a playermodel. P is the path to the md3 file to load, its recursive to the location of the md3.cfg.

md3pitch S O M N

This command controls how a model responds to the model's pitch. The pitch (in degrees) is scaled by S, offset by O, and then clamped to the range M..N, i.e. clamp(pitch*S + O, M, N). By default, all model parts have S=1, O=0, M=-360, and N=360, such that the model part will pitch one-to-one.

md3skin H S M [E [F]]

This loads a texture and assigns it to a mesh of the last loaded model (md3load). H is the name of the mesh you want to assign the texture to. S is the path to the texture, its recursive to the location of the md3.cfg. The optional M sets a texture for spec (red channel)/glow (green channel) maps as above. If E is non-zero, then the blue channel of the masks is interpreted as a chrome map. E (maximum envmap intensity) and F (minimum envmap intensity, default: 0) are floating point values in the range of 0 to 1, and specify the range in which the envmapping intensity will vary based on a viewing angle (a Fresnel term that is maximal at glancing angles, minimal when viewed dead-on). The intensity, after scaled into this range, is then multiplied by the chrome map.

md3bumpmap H S N

This command enables bumpmapping for a given mesh in the last loaded model (md3load). H is the name of the mesh you want to assign bumpmappign textures to. S is the path to a diffuse skin texture which is used instead of the skin supplied with the "md3skin" command only if the user's 3D card supports bumpmapping, otherwise the skin supplied with "md3skin" takes precedence and no bumpmapping is done. These two diffuse skins may be the same. However a diffuse skin intended for bumpmapping should generally have little to no directional shading baked into it, whereas flat diffuse skins (no bumpmapping) generally should, and this command allows you to provide a separate skin for the bumpmapping case. N is a normal map texture which is used to shade the supplied diffuse skin texture.

md3anim A F N [S [P]]

This assigns a new animation to the last loaded model (md3load). A is the name of the animation to define. Any of the following names may be used:

F is the frame number the animation starts at. N is the number of frames in the animation. S is frames per second at which to run the anim. If none is specified or S=0, 10 FPS is the default. P specifies an optional priority for the animation (defaults to P=0).

A character model will have up to 2 animations simultaneously playing - a primary animation and a secondary animation. If a character model defines the primary animation, it will be used, otherwise the secondary will be used if it is available. Primary animations are:

Secondary animations are:

This allows, for example, a torso part to "shoot" (a primary animation) while a leg part simultaneously runs "forward" (a secondary animation). In the event that a secondary animation other than "idle" is playing and there is no primary animation, then the secondary animation will behave as if it were primary, and the secondary animation will effectively be "idle". This allows parts that would not normally participate in a certain animation to do so in the "idle" case, or otherwise simply be "idle" if this is not desired. However, if you want to override which animation is primary for a specific part, you can set an explicit priority for that animation, and the animation with the highest priority is chosen, regardless of which is primary and which is secondary. So, for example, you could give an animation a -1 priority so that all animations with the default 0 priority are chosen first, or you could give an animation a 1 or greater priority so that it is always chosen before animations with the default 0 priority.

For example, to define a "punch" animation starting at frame 131 with 6 frames and running at 15 frames per second: md3anim "punch" 131 6 15

This links two models together. Every model you load with md3load has an ID. The first model you load has the ID 0, the second has the ID 1, and so on, those ID's are now used to identify the models and link them together. P the ID of the parent model. C to ID of the child model. T name of the tag that specifies at which vertex the models should be linked.

Hint: Make sure you understand the difference between the parent and child model. Rendering starts at model 0 (first loaded model) and then continues with model 0's children, etc. Imagine a tree, model 0 is the root if it.

Sample Configuration

md3load lower.md3 // model no. 0
md3skin l_lower ./default_l.png

md3anim dying           0   30  20
md3anim dead            30  1   25
md3anim "forward|backward|left|right|swim" 114 10  18
md3anim idle            164 30  30
md3anim "jump|lag|edit" 147	8	15

md3load upper.md3 // model no. 1
md3skin u_torso ./default.png

md3anim dying           0   30  20
md3anim dead            30  1   25
md3anim "lag|edit"      91  40  18
md3anim "punch|shoot"   131 6   15
md3anim idle            152 1   15
md3anim pain            152 1   15


md3load head.md3 // model no. 2
md3skin h_head ./default_h.png


md3link 0 1 tag_torso
md3link 1 2 tag_head

mdlspec 50
mdlscale 20         // 20 percent of the original size
mdltrans 0 0 -1.5   // lower the model a bit

Common Commands

mdlcollide N

If N is 0, collisions with the model are disabled (Default: 1).

mdlbb R H [E]

Sets the model's bounding box to radius R and height H. If this is not set, or R and H are 0, a bounding box is automatically generated from the model's geometry. E is fraction of the model's height to be used as the eyeheight (Default: 0.9).

mdlcullface N

If N is 0, backface culling is disabled for this model. Otherwise, backface culling is enabled (Default: 1).

mdlspec S

S is the specular intensity (not given or 0 gives the default of 100, good for metal/plastics and anything shiny, use lower values like 50 for wood etc, -1 means off entirely).

mdlalphatest T

Controls the cut-off threshold, T, at which alpha-channel skins will discard pixels where alpha is less than T. T is a floating point value in the range of 0 to 1 (Default: 0.9).

mdlalphablend B

Controls whether a model with an alpha-channel skin will alpha blend (Default: 1).

mdlglow G

G is the glowmap scale (not given or 0 gives the default of 300, -1 means off entirely), such that the glow is G percent of the diffuse skin color.

mdlshader S

S is the name of the shader to use for rendering the model (Default: "stdmodel").

mdlambient A

A is the percent of the ambient light that should be used for shading. Not given or 0 gives the default of 30%, -1 means no ambient.

mdlscale S

Scale the model's size to be S percent of its default size.

mdltrans X Y Z

Translate the model's center by (X, Y, Z), where X/Y/Z are in model units (may use floating point).

mdlenvmap E F [P]

Sets the environment map used for the model, where P is a pathname in the same syntax as the "loadsky" command. If this is not specified, the model will use the closest "envmap" entity, or skybox, if none is available. If E is non-zero, then the blue channel of the masks is interpreted as a chrome map. E (maximum envmap intensity) and F (minimum envmap intensity, default: 0) are floating point values in the range of 0 to 1, and specify the range in which the envmapping intensity will vary based on a viewing angle (a Fresnel term that is maximal at glancing angles, minimal when viewed dead-on). The intensity, after scaled into this range, is then multiplied by the chrome map.

mdlshadow B

Controls whether a mapmodel will cast shadows (Default: 1).