Exporting Models

From Unvanquished
Jump to: navigation, search

Overview

Notice: This guide was written for the 2.6 series of Blender. Most of this guide should apply for other versions of Blender, but this is not guaranteed.

Getting a finished model out of Blender and into the game is a relatively involved process with a number of possible pitfalls. This guide aims to describe the process in as much detail as possible to assist users who have not done it before, or those who have exported models for other games and would like to know what (if anything) is different.

If you would like to export from Maya, you may find the official id Software documentation useful.

At present, this guide primarily describes the process for exporting models to the MD5 format. While the engine supports both MD3 and MD5, the latter is preferred. The reasons for this are discussed below.

Before a model may be exported and used in-game, it must be adequately prepared:

  • Engine limitations must be adhered to.
  • The model must have a texture applied to it. This texture is not automagically applied to the model after it is exported and loaded in-game, this is only necessary to satisfy the MD5 exporter; that is, the game cannot read from the exported model the filename of the texture to use.
  • The model must be a mesh and must have an armature modifier applied to it.
  • The armature's bones all must have at least one keyframe.

The actual process of exporting a model is straightforward:

  1. After ensuring that the above requirements are met, the mesh itself is exported.
  2. If using the old exporter, each animation is exported separately. The new exporter adds support for batch export of animations.
  3. A configuration file specifying data such as the bounding box size and vertical offset is written. This may include information that is specific to the particular type of model (i.e., buildable or player model).
  4. A shader is written that determines how the model is textured in-game.
  5. Finally, after everything is properly named and configured, the files are packaged and placed in the correct game data folder to allow it to be loaded in-game.

What is MD5?

MD5 is the model format created by id Software for Doom 3 which is also used by Unvanquished. It is an improvement over its predecessor, MD3, in that it uses bones to pose the model.

Information 48x48.png

What about MD3? IQM? PSK? ASE? Obj?

The Daemon engine currently only supports the following:

Format Introduced in Supported techniques Exporter availability
Title Year
MD3 Quake 3 1999 Per-frame vertex animation
  • Milkshape 3d
  • Blender 2.4 or newer
PSK Unreal Tournament 2003 (Unreal Engine 2)1 2002 Bones with vertex weights
  • Maya2
  • 3ds Max2
  • SoftImage
MDC Wolfenstein: Enemy Territory 2003 Unsure Unsure
MD5 Doom 3 2004 Bones with vertex weights
  • Maya
  • 3ds Max
  • Blender 2.4 or newer
  1. Actually, America's Army 1.0 was the first title to be released using this format, as it used Unreal Engine 2 as well; it was released in June of that year, and Unreal Tournament 2003 in October.
  2. With the ActorX plugin.
  3. With a plugin provided by SoftImage.

However, we recommend that you use the MD5 format at this time.

Support for the IQM format has been planned, also see this.

Note that mappers may use other formats for static models, such as the ASE (ASCII Scene Export, not to be confused with Adobe's .ase format) and Wavefront Obj formats. A complete listing is available on the mapping page.

Advantages over MD3

  • Unlike MD3, MD5 is bone-based, meaning that instead of storing an entire mesh for each frame of animation, there is only one mesh file. This single mesh file is deformed using a vertex shader.
  • Because there is only one mesh, only one VBO (vertex buffer object) needs to be created for each MD5 model. The deformation is performed entirely on the GPU, so it is (theoretically) faster than MD3, and uses less memory.
  • Because the format is in plain-text, it can be easily verified for sanity (i.e., to ensure that it was exported correctly and not corrupted in some way).

Disadvantages over MD3

  • Some forms of motion are more difficult to achieve; certain animation techniques (such as lattices) are not usable.
  • Because the format is in plain-text, it takes up more space than it needs to, though this is negligible and a MD5 model will typically be smaller than the same model in MD3 format as less data is used per each frame of animation with MD5 as compared to MD3.

Limitations of the engine

The engine places certain limitations on the fidelity of your models when using the MD5 format. These are:

  • There may not be more than 128 bones. (Note: this was increased from 64.)
  • There may not be more than 100,000 vertices.
  • There may not be more than 10,000 triangles.
  • No vertex may belong to more than four vertex groups (i.e., one vertex may not be controlled by more than four bones). An error message will be displayed in-game if this requirement is not met. A script may be used before exporting to check that this limitation is not exceeded.

Information 48x48.png

Developer Note

The limitation on vertex groups is a hard-coded limitation of the vertex shader (main/glsl/vertexSkinning_vp.glsl) that deforms the base mesh.

Limitations of the format

The MD5 format only supports bones. You may not

  • Use lattices or any other means of deformation.
  • Scale bones.
  • Use keyframes on anything other than bone poses. You may, however, set keyframes on bone constraint influences or anything else that would affect a bone's position or rotation.

Note that you do not have to have a parent/child relationship between bones. In fact, in some instances, avoiding a parent/child relationship is necessary to achieve certain effects, such as moving bones around.

Acquiring and installing the exporter

MD3

If for some reason you are interested in the MD3 exporter, it is available from SourceForge.

MD5

Old exporter

Please be aware that there are numerous issues with the old exporter and the newer versions of Blender. See the troubleshooting section below for more information. It is strongly recommended that you use the new exporter instead.

You can download the exporter from this thread on katsbits.com. Installation instructions are in the thread.

New exporter

As of 15 May 2012, there is another MD5 exporter available for Blender 2.63+ (discussion on katsbits). This has been found to be superior to the old exporter. Note that portions of this guide have not yet been updated to reflect the differences in the new exporter.

We have a patched version which allows each mesh objects to have a custom property, q3tex, which contains the name of a shader. This is output in the ‘shader’ line for that mesh in the md5mesh file.

Exporting the mesh

MD5

Note that for buildables and weapons, the filename of the exported mesh is dictated by the corresponding configuration file. All player models, however, are hardcoded to look for body.md5mesh.

Old exporter

Please be aware that there are numerous issues with the old exporter and the newer versions of Blender. See the troubleshooting section below for more information. It is strongly recommended that you use the new exporter instead.

  1. Select the armature and the mesh. The order in which you select the two does not matter.
  2. Click File → Export → Quake Model 5 (.md5)
  3. On the left shelf that appears in the file prompt, change the Exports combo box to "Mesh only." Don't worry about the scale or name fields.
  4. Click "Export MD5".

Once this has been completed, you must manually edit the mesh file (the one with a .md5mesh extension) to specify the correct shader to use.

--- snip ---
mesh {
	shader "models/buildables/medistat"

	numverts 4
	vert 0 ( 1.000000 0.000000 ) 0 1
	vert 1 ( 0.000000 0.000000 ) 1 1
--- snip ---

Note that models/buildables/medistat is not a file path to a shader; it is the name (again, not filename) of the shader to use. That is, a shader with the matching name will be used for this model.

To avoid having to do this every time you export the mesh, set the name of the material applied to the object in Blender to the same as you edited the md5mesh.

New exporter

  • Select the mesh to export.
  • Click File → Export → MD5 Mesh (.md5mesh).
  • Specify the output filename in the dialog, and click "Export MD5MESH".

The exported model is not ready to be used in-game just yet; it must be manually edited. Open the exported .md5mesh file in a text editor, and manually delete the top three lines of the file (highlighted in red below):

// Parameters used during export:
//   Reorient: True
//   Scale: 1.0
MD5Version 10
commandline ""

numJoints 4
numMeshes 1

joints {

...

remainder of file omitted for brevity

Be sure to save the file when you are done. You will also have to do this for each animation file that you export.

If you do not want to have to do this each time, you can edit the exporter script. Open the export_md5.py script in the io_scene_md5 folder where you installed the script, at around line 30, edit this code:

def record_parameters(correctionMatrix):
    return [
    "// Parameters used during export:\n",
    "//   Reorient: {}\n".format(bool(correctionMatrix.to_euler()[2])),
    "//   Scale: {}\n".format(correctionMatrix.decompose()[2][0])]

to look like this:

def record_parameters(correctionMatrix):
    return []

If you are comfortable with applying patches, you may use this:

@@ -27,10 +27,7 @@
     return pairs
 
 def record_parameters(correctionMatrix):
-    return [
-    "// Parameters used during export:\n",
-    "//   Reorient: {}\n".format(bool(correctionMatrix.to_euler()[2])),
-    "//   Scale: {}\n".format(correctionMatrix.decompose()[2][0])]
+    return []
 
 def define_components(obj, bm, bones, correctionMatrix):
     scaleFactor = correctionMatrix.to_scale()[0]

Note that you will also have to manually set the shader as with the old exporter.

Exporting the animations

MD3

Exported MD3 animations require a configuration file that specifies which frames of the animation correspond to which actions the game will display.

This varies slightly by the type (i.e., weapon or buildable) of model.

MD5

Old exporter

Please be aware that there are numerous issues with the old exporter and the newer versions of Blender. See the troubleshooting section below for more information. It is strongly recommended that you use the new exporter instead.

The procedure for exporting animations is the same as for exporting the mesh with regard to selecting the mesh and the armature. Before using the exporter, however, you must be certain to set the start and end frames to encompass only the particular animation that you wish to export; each animation must be exported separately, unless the new exporter is used, which adds a batch export feature.

The timeline view in Blender, which is used to set which frames of animation to export. Here, only one frame of animation (frame 180) is being exported.

At the export file prompt, choose "Anim only." from the "Exports" combo box. Enter as the filename the name of the particular animation that you are exporting; the correct names to use are given below.

Batch export with the new exporter

The new exporter now supports batch export of models.

To make use of this feature, you must set frame markers denoting the start and end of each animation. The name of frame markers denoting the start of an animation must end in "_start" and markers denoting the end of an animation must end in "_end"; for example, frame markers denoting the start and end of a buildable's construct animation would be "construct_start" and "construct_end". Avoid using frame markers with duplicate names, as which one will be used by the exporter is not predictable. Note that frame markers may overlap however you please; this is useful when two animations share a frame or you would like to automate the process of exporting the same few frames of animation as several different animation files (e.g., for testing purposes).

All operations in modifying frame markers are performed in the timeline:

  • To create a frame marker, move the timeline to the desired frame and press M.
  • To select a frame marker, click with the right mouse button.
  • To move a frame marker, select it and press G.
  • To delete a frame marker, select it and press X.
  • To rename a frame marker, select it and press CtrlM.

The actual exportation process becomes much simpler:

  1. Click File → Export → MD5 (batch export).
  2. Specify the filename of the .md5mesh to export.

Animation names

The filenames for each exported animation must be what the engine expects for it to be able to load them, and vary depending on the format (MD3 or MD5) and type (e.g., buildable, weapon, or player) of model being exported.

Weapons

Information 48x48.png

Developer Note

This information may be safely disregarded by artists.
See the CG_ParseWeaponFile() function in src/gamelogic/cgame/cg_weapons.c</code>.

Weapon state constants are enumerated in the weaponstate_t enum in src/gamelogic/game/bg_public.h</code>:

Constant Description
WEAPON_READY The weapon at its idle state, ready to fire.
WEAPON_RAISING The weapon as it is being raised. It may not be fired in this state.
WEAPON_DROPPING The weapon as it is being put away. It may not be fired in this state.
WEAPON_FIRING The weapon as it is being fired.
WEAPON_RELOADING The weapon as it is being reloaded.
WEAPON_NEEDS_RESET The Lucifer Cannon in its overcharged state.

Control of weapon states is done by PM_Weapon(), PM_BeginWeaponChange(), and PM_FinishWeaponChange() in src/gamelogic/game/bg_pmove.c</code>.

Note that for both MD3 and MD5 models, there may be separate models for first- and third-person views. Please see "Configuring the model" for more information regarding how to specify separate models.

MD3

MD3 does not use separate files for separate animations. Instead, a configuration file specifies what frames of a single MD3 animation are used for each in-game animation.

TODO: Find out how barrel spin is handled by the engine. Is it animated into the barrel model or is it done procedurally?

In addition to the base weapon mesh, there may be as many as three additional MD3 meshes:

Search string Tag Description
%s_flash.md3 tag_flash The weapon's muzzle flash.
%s_barrel.md3 tag_barrel The weapon's barrel.
%s_hand.md3 N/A Hands holding the weapon model. Note: this is not used for third person models.

For non-programmers, the %s string is replaced by the parameter given to the weaponModel or weaponModel3rdPerson keyword.

The tag tag_weapon is used on the main weapon model to align the third person weapon model to the third person player model.

MD5

Note that each animation filename must have the .md5anim extension.

Animation name Engine constant Description
%s_view_idle WANIM_IDLE Animation played when a weapon is not being fired
%s_view_lower WANIM_DROP Animation played when a weapon is being put away
%s_view_reload WANIM_RELOAD Weapon reload animation
%s_view_raise WANIM_RAISE Animation played when a weapon is switched to
%s_view_fire WANIM_ATTACK1 Default attack animation
WANIM_ATTACK2 Usage of these is highly dependent on the player class. The marauder, for example, may randomly use one of these instead of WANIM_ATTACK1.1
WANIM_ATTACK3
WANIM_ATTACK4
WANIM_ATTACK5
WANIM_ATTACK6
WANIM_ATTACK7
WANIM_ATTACK8
  1. See PM_Weapon().

Buildables

MD3

As always, MD3 buildable models require a separate configuration file that specifies which frames of the animation correspond to actions displayed by the game.

Information 48x48.png

Developer Note

This information may be safely disregarded by artists.
This file is parsed by CG_ParseBuildableAnimationFile() in src/gamelogic/cgame/cg_buildable.c.

Each line in the configuration file corresponds to a single animation. Those animations are in the same order as in the table for MD5 animation names below.

The order that animations appear in the configuration file must match this order exactly. Animations may not be omitted.

The syntax is as follows:

firstFrame numFrames [loopFrames [fps]]
  • firstFrame — Specifies the initial frame of the animation.
  • numFrames — Specifies the number of frames following the initial frame that comprise that animation.
  • loopFrames — (Optional)
  • fps — (Optional, may only be used if loopFrames is specified) Specifies the framerate of the animation. If not specified, defaults to 1.

C and C++ style comments (i.e., // and /* */) are permitted past the last argument.

MD5

As with weapon animations, each animation filename must have the .md5anim extension.

Information 48x48.png

Developer Note

This information may be safely disregarded by artists.
These animation constants are in the buildableAnimNumber_t enumeration in src/gamelogic/game/bg_public.c. Animations are set using the G_SetIdleBuildableAnim() and G_SetBuildableAnim() functions. All animations are in entity behavior functions in src/gamelogic/game/g_buildable.c.

Sounds for animations are enumerated in the cg_buildableSoundNames array in src/gamelogic/game/bg_public.h. Which animations are loaded is defined in

Animation name Engine constant Used by Description
idle BANIM_IDLE1 All Idle animation, shown when the buildable is not doing anything (and in the case of human buildables, when they are also powered). Used in place of other animations if they are missing unless otherwise noted.
idle2 BANIM_IDLE2 Medistation, telenode, barricade, egg ‘Active’ idle state, e.g. while the medistation is currently healing (and not transitioning into or out of the healing state).
powerdown BANIM_POWERDOWN Human buildables, (barricade) Animation played when a buildable has just lost power.
idle_unpowered BANIM_IDLE_UNPOWERED Human buildables, (barricade) Idle animation played when a buildable has no power. (Formerly idle3.)
construct BANIM_CONSTRUCT1 All Construction animation, shown when the buildable is being built.
construct2 BANIM_CONSTRUCT2 Medistation, (telenode), (egg) Animation played when returning to the primary idle state, e.g. medistation transitioning from healing.
attack BANIM_ATTACK1 All (except tesla) Animation played when a buidlable is attacking or transitioning to its ‘active’ idle state. For the barricade, the animation when it is shrinking.
attack2 BANIM_ATTACK2 (Medistation), (telenode), barricade, (egg) Unshrink animation for the barricade. (Falls back on BANIM_ATTACK1.)
spawn BANIM_SPAWN1 Telenode, Egg Animation for when when someone is spawning from a telenode or egg.
spawn2 BANIM_SPAWN2 Currently unused.
pain BANIM_PAIN1 All Default pain animation, used when a buildable is damaged.
pain2 BANIM_PAIN2 (Medistation), barricade, (egg) Pain animation used for the barricade when it is damaged and shrunk. (Falls back on BANIM_PAIN1.)
destroy BANIM_DESTROY1 All Played when a buildable is killed or destroyed.
destroy_unpowered BANIM_DESTROY_UNPOWERED All which can be unpowered Played when an unpowered buildable is killed or destroyed. (Falls back on BANIM_DESTROY1.)
destroyed BANIM_DESTROYED All The animation played after the buildable's destroy animation finishes playing but before it blows up; essentially, the buildable in a dead state. For the barricade, this is the same animation as for its shrunk state.

Note: buildables whose names are in (parentheses) may not actually use the animation, but it is possible that at some point they will. However, the animations are loaded.

Player models

MD5

As with weapon animations, each animation filename must have the .md5anim extension.

Items in italics need to be double-checked.

Note that at present, some of these strings do not match the constants.

Animation name Engine constant Humans? Aliens? Description
Assumed Correct Actual (Humans) Actual (Aliens) Humans Aliens
attack attack attack TORSO_ATTACK NSPA_ATTACK1 Yes Yes
attack2 idle attack2 TORSO_ATTACK2 NSPA_ATTACK2 Yes Yes
attack3 attack3 attack3 N/A NSPA_ATTACK3 No Yes
charge N/A charge N/A NSPA_CHARGE No Yes Tyrant charge animation
crouch crouch N/A LEGS_IDLECR N/A Yes No
crouch_backward crouch_forward N/A LEGS_BACKCR N/A Yes No
crouch_forward crouch_forward N/A LEGS_WALKCR N/A Yes No
die die die BOTH_DEATH1 NSPA_DEATH1 Yes Yes
gesture gesture gesture TORSO_GESTURE NSPA_GESTURE Yes Yes
idle idle N/A LEGS_IDLE N/A Yes No Human idle animation. It seems as though NSPA_STAND ("stand") is used as the idle animation for aliens.
jump jump jump LEGS_JUMP NSPA_JUMP Yes Yes
jump_back jump jump_back LEGS_JUMPB NSPA_JUMPBACK Yes Yes Evidently although humans have a separate constant for jumping backwards, they use the same animation file as for jumping forwards.
land land land LEGS_LAND NSPA_LAND Yes Yes
land_back land land_back LEGS_LANDB NSPA_LANDBACK Yes Yes Like with jumping, humans evidently use the same animation for both LEGS_LAND and LEGS_LANDB.
pain1 N/A pain1 N/A NSPA_PAIN1 No Yes Humans evidently do not have a pain animation?
pain2 N/A pain2 N/A NSPA_PAIN2 No Yes
run run run LEGS_RUN NSPA_RUN Yes Yes
run_backwards run (?) run_backwards LEGS_BACK NSPA_RUNBACK Yes Yes Note: Not sure if this is correct for the humans
run_left N/A run_left N/A NSPA_RUNLEFT No Yes
run_right N/A run_right N/A NSPA_RUNLEFT No Yes
stand ? stand NSPA_STAND No Yes TORSO_STAND is in the code, but I didn't see an animation loaded for the humans
stand2 idle TORSO_STAND2 Yes No
step step LEGS_TURN? Yes No
swim swim swim LEGS_SWIM NSPA_SWIM Yes Yes
turn step LEGS_TURN No Yes
walk walk walk LEGS_WALK NSPA_WALK Yes Yes
walk_backwards walk walk_backwards LEGS_BACKWALK NSPA_WALKBACK Yes Yes
walk_left N/A walk_left N/A NSPA_WALKLEFT No Yes
walk_right N/A walk_right N/A NSPA_WALKLEFT No Yes


Writing shaders

As was implied before, the texture(s) used by a model are not stored in the md5mesh or md5anim files; they are specified by a separate shader file that is placed in the scripts/ directory.

Shaders are a very large topic and are outside the scope of this guide. The XReal shader guide explains shaders in detail. However, the following shader should do for most purposes:

models/buildables/trapper
{
	diffuseMap models/buildables/trapper/trapper.tga
	bumpMap models/buildables/trapper/trapper_n.tga
	specularMap models/buildables/trapper/trapper_s.tga
}

Do take note that

  • models/buildables/trapper is NOT a path, it is merely a string that matches the shader specified by the .md5mesh, and
  • bumpMap actually refers to a normal map.

Configuring the model

Aside from the textures used by a model, the scale, vertical position, and bounding box size of the model must be specified. This is done with a configuration file. These were formerly placed in overrides/buildables/ (for buildables) or overrides/classes/ (for player models), but are now placed in configs/.

Player models

Information 48x48.png

Developer Note

This information may be safely disregarded by artists.
Reading the configuration file for player models is handled by the CG_ParseCharacterFile() function in src/gamelogic/cgame/cg_players.c</code>.

The configuration file may use the following keywords:

Note: this list is incomplete

  • headoffset x y z
  • sex gender

    Sets the gender of the model. Options are f for female or n for neuter. Any other character is interpreted as male.

  • fixedlegs
  • fixedtorso
  • firstTorsoBoneName
  • footsteps

    • default
    • flesh
    • metal
    • splash
    • none

  • lastTorsoBoneName
  • torsoControlBoneName
  • neckControlBoneName
  • modelScale

As an example:

name        "Basilisk"
model       level1
modelScale  1.0
skin        default
shadowScale 1.0
hud         alien_general_hud
mins        -18 -18 -18
maxs        18 18 18
crouchMaxs  18 18 18
deadMins    -18 -18 -4
deadMaxs    18 18 4
zOffset     0.0

Weapons

Information 48x48.png

Developer Note

This information may be safely disregarded by artists.
Weapon configuration files are parsed with CG_ParseWeaponConfig() function in src/gamelogic/cgame/cg_weapons.c</code>.

The configuration file may use the following keywords:

  • weaponModel path
  • weaponModel3rdPerson path
  • idleSound path
  • icon path — The relative path to the icon that is displayed in the HUD for that weapon.
  • crosshair path
  • disableIn3rdPerson

After those keywords, one of the following keywords must be used, followed by an opening curly brace ({), more commands, and a final closing curly brace (}):

  • primary (engine constant: WPM_PRIMARY)
  • secondary (engine constant: WPM_SECONDARY)
  • tertiary (engine constant: WPM_TERTIARY)

The configuration between the curly braces is handled by CG_ParseWeaponModeSection, in the same file. It accepts the following keywords:

  • missileModel path
  • missileSprite size shader
    • size — The size of the missile sprite. If this value is negative, it is made zero.
    • shader — The shader describing the missile sprite.
  • missileRotates
  • missileAnimates startFrame numFrames frameRate looping
  • missileParticleSystem name
  • missileTrailSystem name
  • muzzleParticleSystem name
  • impactParticleSystem name
  • impactMark size shader
  • impactSound index path
    • index — The index of the sound file, clamped to the range [0,3]; up to four impact sounds may be defined with this keyword.
    • path — The file path of the sound file to use.
  • impactFleshSound index path
    • index — The index of the sound file, clamped to the range [0,3]; up to four impact sounds may be defined with this keyword.
    • path — The file path of the sound file to use.
  • alwaysImpact
  • flashDLightColor red green blue

    Specifies the color of the muzzle flash dynamic lighting.

    • red — The red color component as a floating point number in the range [0,1].
    • green — The green color component as a floating point number in the range [0,1].
    • blue — The blue color component as a floating point number in the range [0,1].
  • continuousFlash
  • missileDlightColor red green blue
    • red — The red color component as a floating point number in the range [0,1].
    • green — The green color component as a floating point number in the range [0,1].
    • blue — The blue color component as a floating point number in the range [0,1].
  • missileDlight size
    • size — If this value is negative, it is made zero.
  • firingSound path
  • missileSound path
  • flashSound index path
    • index — The index of the sound file, clamped to the range [0,3]; up to four impact sounds may be defined with this keyword.
    • path — The file path of the sound file to use.

As an example, this is the configuration for the chaingun (models/weapons/chaingun/weapon.cfg):

weaponModel       models/weapons/chaingun/chaingun.md3

icon              icons/iconw_chaingun
crosshair         48 gfx/2d/crosshair-chaingun_s

primary
{
  flashDlightColor      1.0 1.0 0.0
  flashSound            0 models/weapons/chaingun/flash0.wav
  flashSound            1 models/weapons/chaingun/flash1.wav
  flashSound            2 models/weapons/chaingun/flash2.wav
  flashSound            3 models/weapons/chaingun/flash3.wav

  impactMark            8 gfx/marks/bullet_mrk

  impactSound           0 models/weapons/chaingun/impact0.wav

  impactParticleSystem  models/weapons/rifle/impactPS
  muzzleParticleSystem  models/weapons/chaingun/muzzlePS
}

Buildables

Information 48x48.png

Developer Note

This information may be safely disregarded by artists.
Reading the configuration file for buildables is handled by the BG_ParseBuildableFile() function in src/gamelogic/game/bg_misc.c</code>.

The configuration file may use the following keywords:

  • model index path
    • index Some models may actually have several different model files (not sure why); this argument specifies which. Clamped to the range [0,3] (which should actually be [0, MAX_BUILDABLE_MODELS]), which means that you may use as many as four models per buildable. This is only used by the machine gun turret, which is composed of different parts.
    • path The file path where the model file is located. Note that for MD5 models, an extension of .md3 is still to be used; it will automatically be changed by the engine.
  • modelScale scale

    Scales the model linearly.

  • mins minX minY minZ

    The coordinates passed to this and maxs define the bounding box for the model that is used for collision. The bounding box is always aligned to the global coordinate axes regardless of the orientation of the model, which is something to keep in mind when defining these values. You will likely have to debug these values by enabling drawing the bounding boxes. Load a map in developer mode with \devmap and set \cg_drawBBOX to 1. The three arguments combined form the coordinate of one corner of the bounding box, and maxs the opposite corner.

  • maxs minX minY minZ

    Defines the opposite corner of the AABB. (See above.)

  • zOffset offset

    Sets the vertical offset of the model; in other words, how far off the ground it is.

    • offset The offset as a floating point (decimal) value.

As an example:

model       0 models/buildables/trapper/trapper.md3
modelScale  0.8
mins        -15 -15 -15
maxs        15 15 15
zOffset     -15

Note that at present, you do not have to change the filename extension of the model to match what it actually is; that is, if the model is actually an md5, you may leave the extension as ".md3" and not ".md5mesh" or whatever.

Directory overview

This section provides an overview of the subset of the directory structure used by models; directories used for other purposes have been omitted.

  • armor/ Location of configurations for the three armor types (i.e., light, helmet, and battlesuit). You should not have to edit these.
  • configs/ Location of configuration files for various models.
    • buildables/
  • scripts/
  • gfx/ Location of various 2d effect textures, such as those used for weapons.
    • Subdirectories omitted for brevity
  • models/
    • ammo/
      • tesla/ Contains a single image used for the tesla sparks. Not sure why it's located here.
    • buildables/
      • acid_tube/ Acid tube
      • arm/ Armory
      • barricade/ Barricade
      • booster/ Booster
      • dcc/ Defense Computer
      • eggpod/ Egg
      • hive/ Hive
      • hovel/ Hovel
      • medistat/ Medistation
      • mgturret/ Machinegun Turret
      • overmind/ Overmind
      • reactor/ Reactor
      • repeater/ Repeater
      • telenode/ Telenode
      • tesla/ Tesla generator
      • trapper/ Trapper
    • players/
      • builder/ Human builder model.
      • human_base/ Unarmored human model. Also includes the jetpack and battery pack.
      • human_bsuit/ Battlesuit model.
      • level0/ Dretch.
      • level1/ Basilisk and advanced basilisk. (The advanced basilisk uses the same model as the regular dragoon, but a different texture.)
      • level2/ Marauder and advanced marauder. (Same as basilisk with regard to advanced model.)
      • level3/ Dragoon and advanced dragoon. (Same as basilisk with regard to advanced model.)
      • level4/ Tyrant.
    • weapons/
      • abuild/ As there is no weapon model for the granger, the only thing in this directory is a config to hide the (nonexistant) weapon model in third person (a hack, I guess).
      • abuildupg/ Advanced granger weapon. Same as above, except the config file specifies sounds for the attack sounds (which are also located in this directory).
      • ackit/ Advanced construction kit.
      • blaster/ Blaster.
      • chaingun/ Chaingun.
      • ckit/ Construction kit.
      • flamer/ Flamethrower.
      • grenade/ Grenade.
      • hive/ Sprites, configuration file, and sound file for the hive.
      • lcannon/ Lucifer cannon.
      • level0/ Dretch configuration and attack sound file.
      • level1/ Basilisk configuration and attack sound files (hit and miss).
      • level1upg/ Advanced Basilisk configuration and added gas attack sound file.
      • level2/ Marauder configuration and attack sound files (hit and miss).
      • level2upg/ Advanced Marauder configuration and added electric attack sound file.
      • level3/ Dragoon configuration and attack sound files (hit, miss, and pounce).
      • level3upg/ Advanced Dragoon configuration and added barb sound files and model.
      • level4/ Tyrant configuration and attack sound files (hit and miss).
      • lgun/ Lasgun
      • lockblob/
      • mdriver/ Mass Driver
      • mgturret/ Machinegun turret FIXME: why does this show up twice?
      • prifle/ Plasma rifle
      • psaw/ Painsaw
      • rifle/ Rifle
      • shells/
      • shotgun/ Shotgun
      • teslagen/ Tesla generator FIXME: why does this show up twice?
  • overrides/ Depreciated directory for model configuration files. Use configs/ instead.
    • buildables/ Depreceated location for buildable model configs.
    • classes/ Depreceated location for character model configs.
  • scripts/ Location for shaders.

Getting the model in game

There are two approaches to test your model in-game. The model and related files may be in actual folders, or the engine can load them from a .pk3 (package) file, which is really just a zip-compressed archive with the extension changed. The process for creating these archives is discussed on the packaging game data page.

Testing the model

Once you have the model exported, the shader and configuration written, and everything packaged into a .pk3 file and in place, you are ready to test.

Testing externally

Rather than testing the exported model in-game, you may also test the model with a stand-alone MD5 viewer. At present, there is a viewer for Windows available here.

Testing in game

See the testing page.

Troubleshooting

Old exporter

Please be aware that there are numerous issues with the old exporter and the newer versions of Blender. See the troubleshooting section below for more information. It is strongly recommended that you use the new exporter instead.

Error while exporting from Blender

Md5 export error no armature.png This error displays when the selected object does not have an armature modifier. Any object exported as an md5 needs bones, even if it is static. If you are unsure of how to create a static object with md5, just add an armature, set the playback start and end frame to 1, and add a location or rotation keyframe at frame 1.
Md5 export error no animation.png This error displays when there are no keyframes. Follow the abov instructions for exporting a static object with md5.
Md5 export error no material.png This error displays when the object does not have a material applied to it. This is required by the script, even though it really does not affect the exported result.

Appearance problems in-game

All or part of the mesh appears to be sucked to the center

Please note that as of 2012-02-27, the MD5 exporter does not work properly in several more recent versions of Blender. Use Blender 2.59 until this is fixed. See the MD5 exporter thread for more information.

This can happen for a number of reasons:

  • There are vertices without weights.

    Solution: apply weights to vertices that do not have them. If those verts are not to be animated, weight them to a bone that does not move.

  • You are using Blender 2.61 and you have bones that have animated positions.

    Solution: Use an earlier version of blender until this is fixed in the exporter.

  • You are using Blender 2.62 and you have bones that are not located at the origin and do not have a parent or have animated positions.

    Solution: Again, use an earlier version of blender until this is fixed in the exporter.

"R_LoadMD5: vertex %i requires more than %i weights on surface (%i) in model '%s'"

This error is displayed in the console in game when a vertex belongs to too many groups.

You can use this script to check your model for this before exporting:

# Copyright 2012 Nicholas De Cicco. <velociostrich@gmail.com>
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#	http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import bpy, math
from bpy.props import *

MAX_GROUPS_PER_VERT = 4

# Switch to object mode for vertex selection to work
bpy.ops.object.mode_set(mode='OBJECT')

for obj in bpy.context.selected_objects:
	# Check to see that the object is a mesh.
	if obj.type != 'MESH':
		continue

	# Select verts that belong to too many groups
	for vertex in obj.data.vertices:
		if len(vertex.groups) > MAX_GROUPS_PER_VERT:
			vertex.select = True
		else:
			vertex.select = False

# Switch back to edit mode so the user can see any selected verts
bpy.ops.object.mode_set(mode='EDIT')

Using the Script

  1. Select the mesh (or meshes) that you would like to check.
  2. Create a new text editor window and text data block.
  3. Copy and paste the script into the text editor.
  4. Click "Run Script".

Once the script has ran, the 3d view will switch to edit mode and any offending vertices will be selected. A handy tip: clicking an individual vertex will reveal which groups it is a member of in the properties shelf.

The vertex group section of the properties shelf

Resources