[[Category:Modeling]]

==Overview==

''Notice: This guide was written for Blender 2.61. 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.

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.

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

* [[Exporting_Models#Engine_Limitations|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.
* 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:

# After ensuring that the above requirements are met, the mesh itself is exported.
# Each animation is exported separately.
# 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).
# A shader is written that determines how the model is textured in-game.
# Finally, everything is compressed into a .pk3 archive, properly named, and placed in the correct folder to ensure that it is loaded and may be tested in-game.

==Advantages and Disadvantages of the MD5 format==

===Advantages===

* 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===

* Some forms of motion are more difficult to achieve.
* Because the Blender 2.5/2.6 MD5 exporter can only export models animated only with bones, 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.

==Engine Limitations==

The engine places certain limitations on the fidelity of your models. 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. See [[Exporting_Models#.22R_LoadMD5:_vertex_.25i_requires_more_than_.25i_weights_on_surface_.28.25i.29_in_model_.27.25s.27.22|this]] for more information. This is a limitation of the vertex shader ([https://github.com/Unvanquished/Unvanquished/blob/master/main/glsl/vertexSkinning_vp.glsl main/glsl/vertexSkinning_vp.glsl]) that deforms the base mesh.

==Limitations of the MD5 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 acheive certain effects, such as moving bones around.

==Acquiring and installing the exporter==

You can download the exporter from [http://www.katsbits.com/smforum/index.php?topic=178.0 this thread on katsbits.com]. Installation instructions are in the thread.

Please be aware that there are [[Exporting_Models#All_or_part_of_the_mesh_appears_to_be_sucked_to_the_center|issues]] with certain versions of the exporter with certain versions of Blender.

As of 15 May 2012, there is another MD5 exporter available for Blender 2.63+, available on [http://www.katsbits.com/smforum/index.php?topic=404.0 katsbits]. This is largely untested by the Unvanquished development team, although we are evaluating its use at present. The instructions in this guide currently apply only to the older exporter.

==Exporting the mesh==

''Please be aware that there are issues with the exporter and the current version of Blender. See [[Exporting_Models#All_or_part_of_the_mesh_appears_to_be_sucked_to_the_center|the troubleshooting section]] below for more information.''

# Select the armature and the mesh. The order in which you select the two does not matter.
# Go to File → Export → Quake Model 5 (.md5)
# 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.
# Hit "Export MD5".

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

<pre>
--- 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 ---
</pre>

Note that <code>models/buildables/medistat</code> 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.

Note that for buildables and weapons, the filename of the exported mesh is dictated by the corresponding [[Exporting_Models#Configuring_the_model|configuration file]]. All player models, however, are hardcoded to look for <code>body.md5mesh</code>.

==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===

''Please be aware that there are issues with the exporter and the current version of Blender. See [[Exporting_Models#All_or_part_of_the_mesh_appears_to_be_sucked_to_the_center|this]] for more information.''

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.

[[Image:Md5_export_timeline.png|frame|center|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.

===Weapon animation names===

For more information, see the <code>CG_ParseWeaponFile()</code> function in <code>[https://github.com/Unvanquished/Unvanquished/blob/master/src/gamelogic/gpp/src/cgame/cg_weapons.c src/gamelogic/gpp/src/cgame/cg_weapons.c]</code>.

Developers: weapon state constants are enumerated in the <code>weaponstate_t</code> enum in <code>[https://github.com/Unvanquished/Unvanquished/blob/master/src/gamelogic/gpp/src/game/bg_public.h src/gamelogic/gpp/src/game/bg_public.h]</code>:

Artists may safely ignore this table.

{| class="wikitable"
|-
! Constant
! Description
|-
| <code>WEAPON_READY</code>
|
|-
| <code>WEAPON_RAISING</code>
|
|-
| <code>WEAPON_DROPPING</code>
|
|-
| <code>WEAPON_FIRING</code>
|
|-
| <code>WEAPON_RELOADING</code>
|
|-
| <code>WEAPON_NEEDS_RESET</code>
|
|-
|}

Note that for both MD3 and MD5 models, there may be separate models for first- and third-person views. Please see "[[Exporting_Models#Weapons|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:

{| class="wikitable"
|-
! Search string
! Tag
! Description
|-
| <code>%s_flash.md3</code>
| <code>tag_flash</code>
| The weapon's muzzle flash.
|-
| <code>%s_barrel.md3</code>
| <code>tag_barrel</code>
| The weapon's barrel.
|-
| <code>%s_hand.md3</code>
| N/A
| Hands holding the weapon model. Note: this is not used for third person models.
|}

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

The tag <code>tag_weapon</code> 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 <code>.md5anim</code> extension.

{| class="wikitable"
|-
! Animation name
! Engine constant
! Description
|-
| <code>%s_view_idle</code>
| <code>WANIM_IDLE</code>
| Animation played when a weapon is not fired
|-
| <code>%s_view_lower</code>
| <code>WANIM_DROP</code>
| Animation palyed when a weapon is switched from?
|-
| <code>%s_view_reload</code>
| <code>WANIM_RELOAD</code>
| Weapon reload animation
|-
| <code>%s_view_raise</code>
| <code>WANIM_RAISE</code>
| Animation played when a weapon is switched to?
|-
| <code>%s_view_fire</code>
| <code>WANIM_ATTACK1</code>
| Default attack animation
|-
|
| <code>WANIM_ATTACK2</code>
| rowspan="7" | Not sure what these are used for
|-
|
| <code>WANIM_ATTACK3</code>
|-
|
| <code>WANIM_ATTACK4</code>
|-
|
| <code>WANIM_ATTACK5</code>
|-
|
| <code>WANIM_ATTACK6</code>
|-
|
| <code>WANIM_ATTACK7</code>
|-
|
| <code>WANIM_ATTACK8</code>
|-
|}

===Buildable animation names===

====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. This file is parsed by <code>CG_ParseBuildableAnimationFile()</code> in [https://github.com/Unvanquished/Unvanquished/blob/master/src/gamelogic/gpp/src/cgame/cg_buildable.c src/gamelogic/gpp/src/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:

<var>firstFrame</var> <var>numFrames</var> [<var>loopFrames</var> [<var>fps</var>]]

* <var>firstFrame</var> — Specifies the initial frame of the animation.
* <var>numFrames</var> — Specifies the number of frames following the initial frame that comprise that animation.
* <var>loopFrames</var> — (''Optional'')
* <var>fps</var> — (''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., <code>//</code> and <code>/* */</code>) are permitted past the last argument.

====MD5====

As with weapon animations, each animation filename must have the <code>.md5anim</code> extension.

These animation constants are in the <code>buildableAnimNumber_t</code> enumeration in [https://github.com/Unvanquished/Unvanquished/blob/master/src/gamelogic/gpp/src/game/bg_public.c src/gamelogic/gpp/src/game/bg_public.c].

{| class="wikitable"
|-
! Animation name
! Engine constant
! Description
|-
| <code>construct</code>
| <code>BANIM_CONSTRUCT1</code>
| rowspan="2" | Construction animation, shown when the buildable is being built.
|-
| <code>construct2</code>
| <code>BANIM_CONSTRUCT2</code>
|-
| <code>idle</code>
| <code>BANIM_IDLE1</code>
| Idle animation, shown when the buildable is not doing anything.
|-
| <code>idle2</code>
| <code>BANIM_IDLE2</code>
| Used for the unshrink animation for the barricade.
|-
| <code>idle3</code>
| <code>BANIM_IDLE3</code>
| Just another idle? (need to check this)
|-
| <code>attack</code>
| <code>BANIM_ATTACK1</code>
| rowspan="2" | Animation played when a buidlable is attacking.
|-
| <code>attack2</code>
| <code>BANIM_ATTACK1</code>
|-
| <code>spawn</code>
| <code>BANIM_SPAWN1</code>
| Used only by spawn points (the telenode and the egg) when someone is spawning from them.
|-
| <code>spawn2</code>
| <code>BANIM_SPAWN2</code>
| Not used
|-
| <code>pain</code>
| <code>BANIM_PAIN1</code>
| Pain animation, used when a buildable is damaged in any way.
|-
| <code>pain2</code>
| <code>BANIM_PAIN2</code>
| Pain animation used for the barricade when it is damaged and shrunk.
|-
| <code>destroy</code>
| <code>BANIM_DESTROY1</code>
| Played when a buildable is killed or destroyed.
|-
| <code>destroy2</code>
| <code>BANIM_DESTROY2</code>
| Not used as far as I can tell
|-
| <code>destroyed</code>
| <code>BANIM_DESTROYED</code>
| The animation played after the buildable's destroy animation finishes playing but before it blows up; essentially, the buildable in a dead state.
|-
|}

===Player animation names===

As with weapon animations, each animation filename must have the <code>.md5anim</code> extension.

Items in italics need to be double-checked.

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

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

Shaders are a very large topic and are outside the scope of this guide. The [http://tremap.xtr3m.net/__Games/Xreal/Manual_Shader_1/ShaderManual.htm XReal shader guide] explains shaders in detail. However, the following shader should do for most purposes:

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

Do take note that
* <code>models/buildables/trapper</code> is NOT a path, it is merely a string that matches the shader specified by the <code>.md5mesh</code>, and
* <code>bumpMap</code> 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 <code>overrides/buildables/</code> (for buildables) or <code>overrides/classes/</code> (for player models), but are now placed in <code>configs/</code>.

===Player models===

Reading the configuration file for player models is handled by the <code>CG_ParseCharacterFile()</code> function in <code>[https://github.com/Unvanquished/Unvanquished/blob/master/src/gamelogic/gpp/src/cgame/cg_players.c src/gamelogic/gpp/src/cgame/cg_players.c]</code>.

The configuration file may use the following keywords:

''Note: this list is incomplete''

<ul>
<li><code>headoffset <var>x</var> <var>y</var> <var>z</var></code></li>
<li><code>sex <var>gender</var></code>

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

</li>
<li><code>fixedlegs</code></li>
<li><code>fixedtorso</code></li>
<li><code>firstTorsoBoneName</code></li>
<li><code>footsteps</code>

* <code>default</code>
* <code>flesh</code>
* <code>metal</code>
* <code>splash</code>
* <code>none</code>

</li>
<li><code>lastTorsoBoneName</code></li>
<li><code>torsoControlBoneName</code></li>
<li><code>neckControlBoneName</code></li>
<li><code>modelScale</code></li>
</ul>

As an example:

<pre>
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
</pre>

===Weapons===

Weapon configuration files are parsed with <code>CG_ParseWeaponConfig()</code> function in <code>[https://github.com/Unvanquished/Unvanquished/blob/master/src/gamelogic/base/src/cgame/cg_weapons.c src/gamelogic/base/src/cgame/cg_weapons.c]</code>.

The configuration file may use the following keywords:

<ul>
<li><code>weaponModel <var>path</var></code></li>
<li><code>weaponModel3rdPerson <var>path</var></code></li>
<li><code>idleSound <var>path</var></code></li>
<li><code>icon <var>path</var></code></li>
<li><code>crosshair <var>path</var></code></li>
<li><code>disableIn3rdPerson</code></li>
</ul>

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

* <code>primary</code> (engine constant: <code>WPM_PRIMARY</code>)
* <code>secondary</code> (engine constant: <code>WPM_SECONDARY</code>)
* <code>tertiary</code> (engine constant: <code>WPM_TERTIARY</code>)

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

<ul>
<li><code>missileModel <var>path</var></code></li>
<li><code>missileSprite <var>size</var> <var>shader</var></code>
* <var>size</var> — The size of the missile sprite. If this value is negative, it is made zero.
* <var>shader</var> — The shader describing the missile sprite.
</li>
<li><code>missileRotates</code></li>
<li><code>missileAnimates <var>startFrame</var> <var>numFrames</var> <var>frameRate</var> <var>looping</var></code></li>
<li><code>missileParticleSystem <var>name</var></code></li>
<li><code>missileTrailSystem <var>name</var></code></li>
<li><code>muzzleParticleSystem <var>name</var></code></li>
<li><code>impactParticleSystem <var>name</var></code></li>
<li><code>impactMark <var>size</var> <var>shader</var></code></li>
<li><code>impactSound <var>index</var> <var>path</var></code>
* <var>index</var> — The index of the sound file, clamped to the range [0,3]; up to four impact sounds may be defined with this keyword.
* <var>path</var> — The file path of the sound file to use.
</li>
<li><code>impactFleshSound <var>index</var> <var>path</var></code>
* <var>index</var> — The index of the sound file, clamped to the range [0,3]; up to four impact sounds may be defined with this keyword.
* <var>path</var> — The file path of the sound file to use.
</li>
<li><code>alwaysImpact</code></li>
<li><code>flashDLightColor <var>red</var> <var>green</var> <var>blue</var></code>
Specifies the color of the muzzle flash  dynamic lighting.
* <var>red</var> — The red color component as a floating point number in the range [0,1].
* <var>green</var> — The green color component as a floating point number in the range [0,1].
* <var>blue</var> — The blue color component as a floating point number in the range [0,1].
</li>
<li><code>continuousFlash</code></li>
<li><code>missileDlightColor <var>red</var> <var>green</var> <var>blue</var></code>
* <var>red</var> — The red color component as a floating point number in the range [0,1].
* <var>green</var> — The green color component as a floating point number in the range [0,1].
* <var>blue</var> — The blue color component as a floating point number in the range [0,1].
</li>
<li><code>missileDlight <var>size</var></code>
* <var>size</var> — If this value is negative, it is made zero.
</li>
<li><code>firingSound <var>path</var></code></li>
<li><code>missileSound <var>path</var></code></li>
<li><code>flashSound <var>index</var> <var>path</var></code>
* <var>index</var> — The index of the sound file, clamped to the range [0,3]; up to four impact sounds may be defined with this keyword.
* <var>path</var> — The file path of the sound file to use.
</li>
</ul>

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

<pre>
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
}
</pre>

===Buildables===

Reading the configuration file for buildables is handled by the <code>BG_ParseBuildableFile()</code> function in <code>[https://github.com/Unvanquished/Unvanquished/blob/master/src/gamelogic/gpp/src/game/bg_misc.c src/gamelogic/gpp/src/game/bg_misc.c]</code>.

The configuration file may use the following keywords:

<ul>
<li><code>model <var>index</var> <var>path</var></code>
* <var>index</var> 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.
* <var>path</var> The file path where the model file is located. Note that for MD5 models, an extension of <code>.md3</code> is still to be used; it will automatically be changed by the engine.
</li>
<li><code>modelScale <var>scale</var></code>
Scales the model linearly.
</li>
<li><code>mins <var>minX</var> <var>minY</var> <var>minZ</var></code>
The coordinates passed to this and <code>maxs</code> 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 <code>\devmap</code> and set <code>\cg_drawBBOX</code> to 1. The three arguments combined form the coordinate of one corner of the bounding box, and <code>maxs</code> the opposite corner.
</li>
<li><code>maxs <var>minX</var> <var>minY</var> <var>minZ</var></code>
Defines the opposite corner of the AABB. (See above.)
</li>
<li><code>zOffset <var>offset</var></code>
Sets the vertical offset of the model; in other words, how far off the ground it is.
* <var>offset</var> The offset as a floating point (decimal) value.
</li>
</ul>

As an example:

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

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.

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

The engine always prioritizes files in <code>.pk3</code> archives over files and folders at the same priority. The priority from highest to lowest is as follows:

# <code>fs_homepath/fs_game</code>
# <code>fs_basepath/fs_game</code>
# <code>$PWD/fs_game</code>
# <code>fs_homepath/fs_basegame</code>
# <code>fs_basepath/fs_basegame</code>
# <code>$PWD/fs_basegame</code>
# <code>fs_homepath/BASEGAME</code>
# <code>fs_basepath/BASEGAME</code>
# <code>$PWD/BASEGAME</code>

<code>BASEGAME</code> is a preprocessor macro (for non-programmers, a constant; i.e., this cannot be changed at runtime) set to <code>main</code> in Unvanquished. <code>$PWD</code> is the directory that Unvanquished was started from.

Programmers may be interested in <code>[https://github.com/Unvanquished/Unvanquished/blob/master/src/engine/qcommon/files.c src/engine/qcommon/files.c]</code>.

The default locations for <code>fs_basepath</code> and <code>fs_homepath</code> are as follows:

{| class="wikitable"
|-
|
| <code>fs_basepath</code>
| <code>fs_homepath</code>
|-
| Windows
| TODO
| TODO
|-
| Linux
| $HOME/.Unvanquished
| The directory in which Unvanquished is installed.
|-
| Mac OS X
| TODO
| TODO
|}

Basically, the process to get data in-game is to create a temporary directory somewhere and copy the model, shader(s) and configuration file to that directory (creating sub-directories as necessary), then compress the temporary directory as a <code>.zip</code> archive. Change the extension of the <code>.zip</code> archive to <code>.pk3</code> and move it into whichever directory you please, knowing that higher priority files will be used over lesser priority files. An example directory structure might look like this:

* tmp
** configs
*** buildables
**** acid_tube.cfg
** models
*** buildables
**** acid_tube
***** acid_tube.md5mesh
***** acid_tube.tga
***** acid_tube_g.tga
***** acid_tube_n.tga
***** acid_tube_s.tga
***** idle.md5anim
***** ''other animations omitted for brevity''
** scripts
*** acid_tube.shader

Please note that the exact name of the textures used is not strictly defined; these may be whatever you please and are specified by the shader file. See [[Exporting_Models#Writing_shaders|Writing shaders]] for more information.

==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 [http://www.katsbits.com/files/md5/modelviewer_0.93a.zip here].

===Testing in game===

Start the game, and enter the following commands:

\sv_pure 0
\devmap atcshd

You may also load a map with the regular <code>\map</code> command. Be aware, however, that <code>devmap</code> enables cheats which can make it easier to test (such as being able to jump directly to stage 2 or 3 if required). Also note that with <code>devmap</code>, the build time for buildables is zero, so the building animation(s) will not play.

====Tips====

* If the model is a buildable, weapon, or player model that is not immediately available (i.e., not available until a later stage), you can change the stage with <code>g_alienStage</code> or <code>g_humanStage</code>. Both of these cvars accept a single parameter, which is the zero-based index of the stage; to skip to stage 2, use 1 as a parameter, and to skip to stage 2, use 2 as a parameter (stage 1 is 0).
* If you do not have sufficient credits to purchase an item model you wish to test, or evos to evolve to the desired class, you may give yourself the maximum amount that you can carry with <code>\give all</code>.
* To make yourself invincible, use the <code>\god</code> command.
* To stop buildables from attacking, use the <code>\notarget</code> command.
* To stress test the engine's ability to display a large number of buildables, set <code>g_humanBuildPoints</code> or <code>g_alienBuildPoints</code> to as high as you wish; this will allow you to build as much as you please.

====Debugging the model====

* To determine what file was loaded for a particular asset (e.g., to determine if files are being read from a particular <code>.pk3</code> archive), use the <code>\which</code> command with the relative path to the asset as an argument, such as <code>\which models/buildables/acid_tube/acid_tube.md5mesh</code>. Note that <code>which</code> accepts both forward- and backslashes regardless of platform.
* To visually inpsect a model's bounding box, which is set by its configuration file, set <code>\cg_drawBBOX</code> to 1.
* To visually inspect the bone structure of a MD5 model, set <code>r_showSkeleton</code> to 1. ''Note: at present there is a bug that causes bones to be displayed incorrectly. See [https://github.com/Unvanquished/Unvanquished/issues/2 Issue #2] on GitHub for more information.''
* To hide map geometry, set <code>r_drawworld</code> to <code>0</code>. Note that with this set to <code>0</code>, PVS will still be in effect, so it might still be difficult to view your model.

==Troubleshooting==

===Error while exporting from Blender with the MD5 exporter===

{| class="wikitable"
|-
| [[Image:Md5_export_error_no_armature.png]]
| style="vertical-align:top;" | 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.
|-
| [[Image:Md5_export_error_no_animation.png]]
| style="vertical-align:top;" | This error displays when there are no keyframes. Follow the abov instructions for exporting a static object with md5.
|-
| [[Image:Md5_export_error_no_material.png]]
| style="vertical-align:top;" | 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 [http://www.katsbits.com/smforum/index.php?topic=167.msg2135#msg2135 the MD5 exporter thread] for more information.''

This can happen for a number of reasons:
<ul>
<li>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.
</li>
<li>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.
</li>
<li>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.
</li>
</ul>

==="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:

<pre>
# 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')
</pre>

====Using the Script====

# Select the mesh (or meshes) that you would like to check.
# Create a new text editor window and text data block.
# Copy and paste the script into the text editor.
# Hit "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.

[[Image:Properties_shelf_vertex_groups.png|frame|center|The vertex group section of the properties shelf]]

==Resources==

* [http://www.modwiki.net/wiki/MD5_%28file_format%29 MD5 file format documentation]
* [http://www.katsbits.com/tools/# Tools for MD5 and other file formats]
* [http://download.blender.org/release/ Older versions of Blender]

Wiki project resources

2012-08-26T02:14:05Z

Devhc: untwiddle a sentence

At present, the wiki needs a lot of work.

At the time of this writing, most article writers need to learn about web design ergonomics.

Various contents, including ToDo lists, screenshots, release data files, large text messages, and other shared files are hosted at foreign websites. They should be moved to unvanquished.net, for which sufficient serving functionality should be installed. The priorities for these are based on the ease of installation, for example, the removal (or the moving) of ''web browsing analytics'' is of high priority.

==Pages in need of work==

Aside from these pages, please also see the [[Special:WantedPages|the list of wanted pages]].

===Technical documentation===

* [[List of cvars]] and their documentation
* [[Creating custom keybinds]]
* [[Mapping]]
* [[Modeling Guide]]
* [[Music and sounds]]

===Gameplay===

* [[Aliens]]
** Buildables:
*** [[Egg]]
*** [[Overmind]]
*** [[Acid Tube]]
*** [[Hive]]
*** [[Trapper]]
*** [[Barricade]]
** Classes:
*** [[Dretch]]
*** [[Granger]]
*** [[Basilisk]]
*** [[Marauder]]
*** [[Dragoon]]
*** [[Tyrant]]
* [[Humans]]
** Upgrades/Armor:
*** [[Jetpack]]
*** [[Helmet]]
*** [[Battery Pack]]
*** [[Battlesuit]]
** Weapons:
*** [[Construction Kit]]
*** [[Blaster]]
*** [[Rifle]]
*** [[Pain Saw]]
*** [[Shotgun]]
*** [[Las Gun]]
*** [[Mass Driver]]
*** [[Chaingun]]
*** [[Plasma Rifle]]
*** [[Lucifer Cannon]]
** Buildables:
*** [[Telenode]]
*** [[Reactor]]
*** [[Machinegun Turret]]
*** [[Armory]]
*** [[Medistation]]
*** [[Defense Computer]]
*** [[Tesla Generator]]

2012-06-27T17:55:03Z

Devhc: /* CMake cannot locate Newton */

==Mac OS X==

The preferred way of building Unvanquished on Mac OS X is to use Apple's [https://developer.apple.com/xcode/ XCode] along with [http://www.cmake.org/cmake/resources/software.html CMake]; CMake is used to generate an XCode project file that is then used to compile the code.

First, you need to [[Getting_the_source|acquire the source code]].

You may use [http://home.comcast.net/~chet102103/compile.sh this script] to perform these tasks. If you downloaded the source to a folder named <code>Unvanquished</code> in the current directory, a typical invocation would look like this:

$./compile.sh --bundle --compile -s Unvanquished --build Unvanquished-build --bundle-dest .

You will also need to build the libraries from source.

Unvanquished requires the following:
* The jpeg library from the [http://www.ijg.org/ Independent JPEG Group], version 8 or higher. (Version 6 was known to have problems).
* Simple DirectMedia Layer
* The OpenGL Extension Wrangler Library

Optional libraries:
* WebP
* Theora
* Speex
* XVid

===Dependencies===

====JPEG====

$ curl http://www.ijg.org/files/jpegsrc.v8d.tar.gz > jpegsrc.v8d.tar.gz
$ tar xvzf jpegsrc.v8d.tar.gz
$ cd jpeg-8d
$ ./configure
$ make
$ sudo make install

====The OpenGL Extension Wrangler Library (GLEW)====

$ curl -L https://sourceforge.net/projects/glew/files/glew/1.7.0/glew-1.7.0.tgz/download > glew-1.7.0.tgz
$ tar xvzf glew-1.7.0.tgz
$ cd glew-1.7.0
$ make
$ sudo make install

====Simple DirectMedia Layer (SDL)====

At present, there are binaries for SDL.

Intel systems running 10.5 or higher:
$ curl http://www.libsdl.org/release/SDL-1.2.15.dmg > SDL-1.2.15.dmg
$ hdiutil attach SDL-1.2.15.dmg
$ sudo cp -r /Volumes/SDL/SDL.framework /Library/Frameworks
$ hdiutil detach /Volumes/SDL

Intel or PPC systems running 10.4 or higher:
$ curl http://www.libsdl.org/release/SDL-1.2.15-OSX10.4.dmg > SDL-1.2.15-OSX10.4.dmg
$ hdiutil attach SDL-1.2.15-OSX10.4.dmg
$ sudo cp -r /Volumes/SDL/SDL.framework /Library/Frameworks
$ hdiutil detach /Volumes/SDL

====The GNU MP Bignum Library (libgmp)====

$ curl ftp://ftp.gmplib.org/pub/gmp-5.0.5/gmp-5.0.5.tar.bz2 > gmp-5.0.5.tar.bz2
$ tar xvjf gmp-5.0.5.tar.bz2
$ cd gmp-5.0.5
$ ./configure
$ make
$ sudo make install

====Ogg====

$ curl http://downloads.xiph.org/releases/ogg/libogg-1.3.0.tar.gz > libogg-1.3.0.tar.gz
$ tar xvzf libogg-1.3.0.tar.gz
$ cd libogg-1.3.0
$ ./configure
$ make
$ sudo make install

====Vorbis====

$ curl http://downloads.xiph.org/releases/vorbis/libvorbis-1.3.3.tar.gz > libvorbis-1.3.3.tar.gz
$ tar xvzf libvorbis-1.3.3.tar.gz
$ cd libvorbis-1.3.3
$ ./configure
$ make
$ sudo make install

===Configuring with CMake===

# Run CMake.
# Enter the location of the source code.
# Enter the location in which you would like to build the source code. This should be a different directory.
# Click "Configure". You will be prompted as to which generator you would like to use. If you have Xcode installed, choose that. Wait while the configuration process runs. You may have to set the following:
## If CMake did not find your jpeg headers for some reason, set <code>JPEG_INCLUDE_DIR</code> to <code>/path/to/Unvanquished/src/libs/jpeg</code>.
## You may safely disable <code>USE_WEBP</code> to avoid having to compile the library. (At present, the format is not used by any game assets.)
## Check <code>USE_INTERNAL_CRYPTO</code> to avoid having to compile nettle and hogweed.
## Check <code>USE_INTERNAL_SPEEX</code> to avoid having to compile Speex.
## Uncheck <code>USE_CIN_THEORA</code> and <code>USE_CIN_XVID</code> to avoid having to compile Theora or Xvid. (At present, there are not cutscenes or any such that require it.)
## '''You will probably not be able to compile with the GLSL optimizer enabled; uncheck <code>USE_GLSL_OPTIMIZER</code>'''
## If you have selected to generate XCode project files, make the <code>SDLMAIN_LIBRARY</code> field blank. This option is not available if you have the generator set to Unix makefiles.
# Click "Generate".
# You may now close XCode.

===Compiling===

====With XCode====
# Either start XCode and open the project file (in the build directory you specified) or double-click the project file in Finder.
# Open the project file created by CMake, which should be in the build directory you specified.
# Change the active target to "ALL_BUILD" and click Product→Build.

====With Unix Makefiles====

<ul>
<li>Start Terminal (Applications → Utilities → Terminal).</li>
<li>Type the following commands:
<pre>
$ cd /path/to/Unvanquished-build
$ make
</pre>
If you are on a multi-core or multi-processor machine, you may speed up the process by passing the <code>-j</code> argument followed by the number of available cores to <code>make</code>; e.g., <code>make -j4</code>. Note that doing so makes reading error messages more difficult, as multiple instances of the compiler will print to the screen at once, causing information to appear out of order.
</li>
</ul>

===Testing the build===

====With Unix Makefiles====

After compiling, you'll have to place the data files (<code>[http://sourceforge.net/projects/Unvanquished/files/Assets/pak0.pk3/download pak0.pk3]</code>, <code>[http://sourceforge.net/projects/Unvanquished/files/Assets/pak1.pk3/download pak1.pk3]</code>, and <code>[http://sourceforge.net/projects/Unvanquished/files/Assets/pak2.pk3/download pak2.pk3]</code>) in the <code>main</code> directory in your build directory.

$ cd /path/to/Unvanquished
$ cd main
$ curl -L http://sourceforge.net/projects/Unvanquished/files/Assets/pak1.pk3/download > pak0.pk3
$ curl -L http://sourceforge.net/projects/Unvanquished/files/Assets/pak1.pk3/download > pak1.pk3
$ curl -L http://sourceforge.net/projects/Unvanquished/files/Assets/pak1.pk3/download > pak2.pk3
$ cd ..

Your file structure should look as follows:

[[File:Build_dir_Mac_OS_X.png]]

You may now start the application as such:

$ ./daemon.i386

Note that older machines will not support the new OpenGL 3 renderer, and must be started specifying the "vanilla" (aka "GL") renderer:

$ ./daemon.i386 +set cl_renderer GL

===Bundling the Application===

====With CPack====

CPack is able to create standalone bundles (as well as many other types of installers). However you must generate the files using Unix Makefiles instead of XCode.
$ cd /path/to/Unvanquished-build
$ cpack -G Bundle
Some warnings will be printed however these can be safely ignored. There should be a file called Unvanquished.dmg in the Unvanquished-build folder.

====Manually====

You'll find the Mac [http://macdylibbundler.sourceforge.net/ dynamic library bundler] to be quite useful (you must generate the files using Unix Makefiles instead of XCode):

$ curl -L http://sourceforge.net/projects/macdylibbundler/files/macdylibbundler/0.4.1/dylibbundler0.4.1.zip/download > dylibbundler0.4.1.zip
$ unzip dylibbundler0.4.1.zip
$ cd dylibbundler
$ make
$ sudo make install

Once you've done that, you can proceed to create the application bundle. Note that these steps assume that you have downloaded the data files to <code>main/</code> as shown above:

<pre>
$ git=/path/to/Unvanquished-git-repo
$ build=/path/to/Unvanquished-build-dir
$ mkdir -pv Unvanquished.app/Contents/{libs,MacOS,Resources,Frameworks}
$ cp -r $build/main Unvanquished.app/Contents/MacOS
$ sips -s format tiff $git/debian/unvanquished.png --out temp.tiff
$ tiff2icns temp.tiff Unvanquished.app/Contents/Resources/Unvanquished.icns
$ rm temp.tiff
$ cp $build/daemon{,ded}.i386 $build/*.dylib Unvanquished.app/Contents/MacOS
$ cp -r /Library/Frameworks/SDL.framework Unvanquished.app/Contents/Frameworks
$ install_name_tool -id @executable_path/../Frameworks/SDL.framework/Versions/A/SDL Unvanquished.app/Contents/Frameworks/SDL.framework/Versions/A/SDL
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL @executable_path/../Frameworks/SDL.framework/Versions/A/SDL Unvanquished.app/Contents/MacOS/daemon.i386
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL @executable_path/../Frameworks/SDL.framework/Versions/A/SDL Unvanquished.app/Contents/MacOS/librendererGLi386.dylib
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL @executable_path/../Frameworks/SDL.framework/Versions/A/SDL Unvanquished.app/Contents/MacOS/librendererGL3i386.dylib
$ for binary in Unvanquished.app/Contents/MacOS/*.{i386,dylib}; do dylibbundler -b -x $binary -d $dest/Unvanquished.app/Contents/libs/; done
$ cp /usr/lib/libGLEW.1.7.0.dylib ./Unvanquished.app/Contents/libs/libGLEW.1.7.0.dylib
$ chmod +w ./Unvanquished.app/Contents/libs/libGLEW.1.7.0.dylib
$ install_name_tool -id @executable_path/../libs/libGLEW.1.7.0.dylib ./Unvanquished.app/Contents/libs/libGLEW.1.7.0.dylib
$ install_name_tool -change /usr/lib/libGLEW.1.7.0.dylib @executable_path/../libs/libGLEW.1.7.0.dylib ./Unvanquished.app/Contents/MacOS/daemon.i386
$ cat > Unvanquished.app/Contents/Info.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleName</key>
<string>Unvanquished</string>
<key>CFBundleDisplayName</key>
<string>Unvanquished</string>
<key>CFBundleExecutable</key>
<string>daemon.i386</string>
<key>CFBundleIconFile</key>
<string>Unvanquished.icns</string>
<key>CFBundleIdentifier</key>
<string>net.Unvanquished</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
<string>0.4.0</string>
<key>CFBundleVersion</key>
<string>0.4.0</string>
</dict>
</plist>
^d
</pre>

Note: <code>^d</code> indicates pressing Ctrl+D on the keyboard.

The contents of the completed application bundle should look like this:

[[File:Bundle_dir_Mac_OS_X.png]]

==Windows==

===Visual Studio===

CMake can generate Visual Studio projects for unvanquished however this feature is relatively new and may have some bugs.

Steps:

# Double click on Visual_Studio32.bat
# Open build-32/Daemon.sln in Visual Studio 2010.
# In the two text boxes in the toolbar, select "Release" or "Debug" in the first one and Win32 in the second one
# Press F5 to build solution and run application, or just use Build → Build Solution to compile the code.

====Important Notes====

* The CMake script currently only supports 32 bit builds however this will change in the future
* QVM, LLVM and glsl-optimizer are disabled and probably do not work correctly with CMake generated Visual Studio projects.
* ncurses is not supported under Visual Studio.

===MinGW===
Unvanquished is supported under MinGW. The build process should be fairly similar to the Linux instructions.

==Linux==

===Dependencies===


====Debian/Ubuntu====

$ sudo apt-get install libcurl4-gnutls-dev libfreetype6-dev libglew1.5-dev \
libgmp3-dev libjpeg8-dev libncurses5-dev libogg-dev libopenal-dev \
libpng12-dev libsdl1.2-dev libvorbis-dev zlib1g-dev nettle-dev \
libwebp-dev libspeexdsp-dev libtheora-dev

Actual dev package names may vary, e.g. libgmp-dev instead of libgmp3-dev and libglew-dev or libglew1.7-dev instead of libglew1.5-dev.

Since we have a debian directory in the source, you can also to check what's needed then install the listed packages (choosing from alternatives as needed):

$ cd <var>/path/to/unvanquished</var>
$ dpkg-checkbuilddeps
…
$ sudo apt-get install <var>package(s)</var>

If dpkg-checkbuilddeps produces no output, you have all necessary build dependencies. Also, debhelper's only needed if you're building .debs.

====Gentoo====

$ emerge curl freetype glew gmp jpeg ncurses libogg openal libpng libsdl libvorbis zlib

===Configuring the code with CMake===

After you have [[Getting the source|acquired the source code]], you can proceed to compile. Unvanquished uses CMake, so you must have that installed.

====Using ccmake (curses-based front-end)====

On Debian or Ubuntu:

$ sudo apt-get install cmake-curses-gui

On Gentoo you should set the '''ncurses''' USE flag either globally or individually, just for cmake.
To add the USE flag globally, edit the USE array in /etc/make.conf for it to include '''ncurses'''.
To only install cmake with ncurses functionality, you could do the following:

$ echo 'dev-util/cmake ncurses' >> /etc/portage/package.use && emerge cmake

Note that in Ubuntu, <code>cmake-curses-gui</code> is in Universe, which you may have to enable with <code>software-properties-gtk</code>. Make sure to reload the software sources with <code>sudo apt-get update</code> afterwards.

Next, configure the codebase.

$ cd <var>/path/to/unvanquished</var>
$ mkdir build
$ cd build
$ ccmake ..

Or, in Debian or Ubuntu, you can build a package (but you'll need to have devscripts and fakeroot installed):

$ cd <var>/path/to/unvanquished</var>
$ fakeroot dpkg-buildpackage -b -uc
$ sudo dpkg -i <var>../unvanquished_*.deb</var>

Once in <code>ccmake</code>, use the following keys:

* Press c to configure. If an error occurs during this phase, make note of it and press e to dismiss it.
* Use the up and down arrow keys to navigate the compilation options.
* Press Enter to enable or disable boolean options (i.e., on/off) or to edit textual options.
** Press Esc when editing a textual option to cancel the change.

Once you have finished the configuration process, press C again, then G to generate the makefile.

====Using cmake-qt-gui (graphical front-end)====

This graphical front end for cmake has its own package you must install:

=====Debian/Ubuntu=====

$ sudo apt-get install cmake-qt-gui

=====Gentoo=====

With the '''qt4''' USE flag enabled:

$ emerge cmake

Once installed, run with <code>cmake-gui</code>.

[[Image:Cmake-qt-gui.png|thumb]]

# Set the path where you have the source code downloaded.
# Set the path where you would like to build the engine. This may be the same directory if you wish.
# Click 'Configure'.
# Click 'Generate'.

====Unnecessary libraries====

Regardless of which front-end to cmake you use, you may want to disable some libraries that are not strictly necessary:

* <code>USE_WEBP</code> — Some maps use WebP to store their textures. Currently this should have little impact on gameplay but more maps will likely use this format in the future.
* <code>USE_OPENAL</code> — If this is disabled, SDL is used instead for sound.
* <code>USE_CODEC_VORBIS</code> — Disabling this will cause certain sound effects (those using the <code>.ogg</code> format) not to play. At present, this has only a minor impact on gameplay, but more and more sounds will likely use the format in the future.
* <code>USE_CURSES</code> — Disabling this will cause the external (not in-game) console to not use curses; it will not be scrollable and will be similar to the console in the original Tremulous. This does in no way affect gameplay.
* <code>USE_CIN_THEORA</code> — Disabling this prevents videos from being recorded in Theora.
* <code>USE_CIN_XVID</code> — Disabling this prevents videos from being recorded in Xvid.
* <code>USE_VOIP</code> — Disabling this removes VOIP support. Alternatively enabling <code>USE_INTERNAL_SPEEX</code> will use the libraries distributed with Unvanquished for VoIP
* <code>USE_INTERNAL_CRYPTO</code> — Enable this to use the crypto libraries provided by Unvanquished.

===Compiling===

$ cd <var>path/to/unvanquished/build</var>
$ make -j4

The <code>-j</code> switch to make allows you to speed up the compilation process by running it in multiple threads; set the number following this to the number of cores your processor(s) have.

===Acquiring the Game Files===

The game files are not in the Git repository, and must be downloaded separately.

$ cd <var>path/to/Unvanquished/build</var>
$ cd main
$ wget http://sourceforge.net/projects/unvanquished/files/Assets/pak0.pk3/download
$ wget http://sourceforge.net/projects/unvanquished/files/Assets/pak1.pk3/download
$ wget http://sourceforge.net/projects/unvanquished/files/Assets/pak2.pk3/download
$ wget http://sourceforge.net/projects/unvanquished/files/Map%20Pack/maps.7z/download

You can also get the pak files in this way (requires curl):

$ cd <var>path/to/Unvanquished</var>
$ mkdir -p ~/.Unvanquished/main
$ ./download-pk3.sh ~/.Unvanquished/main

The maps archive file isn't strictly necessary: if you don't have a particular map, the game will normally download it for you.

Now you can proceed to [[running the game]].

==Errors==

===CMake cannot locate Newton===

If CMake cannot find Newton, you'll need to set it up yourself.

It should be in <code><var>/path/to/Unvanquished</var>/src/libs/libnewton/libs/<var>your_os</var>/libNewton.so</code>.
Be sure to replace <var>your_os</var> with the proper directory name.

Use CMake as before to change the <code>NEWTON_LIBRARY</code> build setting to the said path:

# Start the CMake configurator:<pre>$ ccmake ..</pre>
# Scroll down and highlight <code>NEWTON_LIBRARY</code>.
# Press Enter to begin editing and input in the path.
# Press C to configure and G to generate the new makefiles.
# Press Q to quit.
# Recompile the source:<pre>$ make</pre>

Engine features

2012-06-27T17:12:15Z

Devhc:

==Overview==

The Daemon engine used by Unvanquished is a fork of the OpenWolf engine, which combines many features of the number of Quake 3 derivatives in existence, as well as a number of features unique to it.

==Features==

Also see the list of [[New_Cvars|new cvars]].

===Gameplay===

* [[Navigation Meshes | Navigation-mesh]] based bot AI
* [[Voice say system]]

===Rendering===

* Legacy OpenGL renderer or a more modern (XReal-derived) OpenGL version 3 compliant renderer.
* [[Stereoscopic rendering|Stereoscopic (3d) rendering]]
* MD3 and MD5 model support
* Improved shader system
** Procedural vertex deformation
** Specular mapping (color and intensity)
** Bump (heightmap), normal, and parallax mapping
* Support for a number of image formats (JPEG, WebP, PNG, TGA)
* Outline fonts
* Procedural animation blending

===Networking===

* In-game IRC client
* VoIP support

===Miscellaneous===

* Localization support
* Curses-based console