Unvanquished - User contributions [en-gb]

Formats/Navigation mesh

2013-10-11T15:58:11Z

Fuma: /* Testing the Mesh */

The Daemon engine supports automatic navigation mesh generation from bsp map files. This navigation mesh (or "navmesh" for short) is used by the bots to navigate throughout the world.

==Generating a Navigation Mesh==

The -nav parameter to daemonmap will generate a navigation mesh from a bsp file.
Use it like so:

===Windows===

daemonmap.exe -game unv -nav mapname.bsp

===Linux===

./daemonmap -game unv -nav mapname.bsp

===Optional Parameters===

The navigation mesh generation process is conservative by default. This means some areas (particularly, small ledges) that should be walkable may instead create a break in the navmesh which bots interpret as "I am unable to go past there." The following optional parameters give the map maker some control over navmesh generation to help with this.

<ul>
<li><code>-cellheight</code>

A lower cellheight will increase mesh generation accuracy at the cost of generation time and mesh size.

If there are gaps in the navigation mesh even though a player can easily just walk to get through, you can decrease the value to help.
</li>
<li><code>-median</code>

Applies a median filter to the walkable areas of the mesh to help contain any "noise."

See [http://digestingduck.blogspot.com/2010/07/recast-area-types-per-triangle.html this article] for more information.
</li>
<li><code>-optimistic</code>

Attempts to compensate for cellsize inaccuracy by increasing the stepheight navigation mesh generation parameter based on the current samplesize. It is recommended to be used with a lower than default cellsize to help avoid over optimistic assumptions (i.e., saying some areas are walkable that really aren't). Useful for fixing breaks in the mesh caused by some small ledges.

This produces bad results depending on how big your <code>cellsize</code> parameter is, but generating the mesh in this way will be faster than simply decreasing the <code>cellheight</code>.
</li>
</ul>

==Using a Navigation Mesh==

Navigation mesh files go in the <code>maps/</code> directory either in the folder specified by the <code>fs_game</code> cvar, or in the maps folder inside a map's <code>.pk3</code> file.

==Testing the Mesh==

* You may test your map locally by entering <code>\devmap <var>mapName</var></code> as you would to test any map at any time. Note, of course, that this will disconnect you from whatever game you may currently be in.
* To enable drawing the navigation mesh, use <code>navedit enable navmeshname</code> where "navmeshname" is one of:
<ul>
*human_base
*human_bsuit
*builder
*builder-upg
*level0
*level1
*level1upg
*level2
*level2upg
*level3
*level3upg
*level4
</ul>
Where level4 is tyrant, level3 is dragoon, level2 is marauder, level1 is basilisk, and level0 is dretch. The two builder navmeshes are not used at this time.
* Add bots with the <code>bot</code> command and spectate the game.

==Editing the Navigation Mesh==
Navmesh editing is still a work in progress, but it can be useful for fixing unnavigable ledges.

Unfortunately, automatic navigation mesh generation that fully supports all of the map features and player abilities in Unvanquished is incredibly difficult. Automatic generation will usually produce a very satisfactory base mesh, but some areas may need further tweaking.

To edit the navmesh, you must select the one you wish to edit using the <code>navedit</code> command.

To add connections use the <code>addcon</code> command.

A oneway connection will only allow bots to move from the start of the connection to the end of the connection, but not from the end to the start. A twoway connection will allow bots to move in either direction along the connection. The radius of the connection is how far away the center of the bot has to be from the middle to take the connection.

Modifications to the navmesh are made in real time, so any bots that have spawned will react accordingly.

When you are done editing a specific navmesh, you can use <code>navedit save</code> to save your work.
[[Category:Bots]]

Formats/Navigation mesh

2013-10-11T15:56:32Z

Fuma: /* Editing the Navigation Mesh */

The Daemon engine supports automatic navigation mesh generation from bsp map files. This navigation mesh (or "navmesh" for short) is used by the bots to navigate throughout the world.

==Generating a Navigation Mesh==

The -nav parameter to daemonmap will generate a navigation mesh from a bsp file.
Use it like so:

===Windows===

daemonmap.exe -game unv -nav mapname.bsp

===Linux===

./daemonmap -game unv -nav mapname.bsp

===Optional Parameters===

The navigation mesh generation process is conservative by default. This means some areas (particularly, small ledges) that should be walkable may instead create a break in the navmesh which bots interpret as "I am unable to go past there." The following optional parameters give the map maker some control over navmesh generation to help with this.

<ul>
<li><code>-cellheight</code>

A lower cellheight will increase mesh generation accuracy at the cost of generation time and mesh size.

If there are gaps in the navigation mesh even though a player can easily just walk to get through, you can decrease the value to help.
</li>
<li><code>-median</code>

Applies a median filter to the walkable areas of the mesh to help contain any "noise."

See [http://digestingduck.blogspot.com/2010/07/recast-area-types-per-triangle.html this article] for more information.
</li>
<li><code>-optimistic</code>

Attempts to compensate for cellsize inaccuracy by increasing the stepheight navigation mesh generation parameter based on the current samplesize. It is recommended to be used with a lower than default cellsize to help avoid over optimistic assumptions (i.e., saying some areas are walkable that really aren't). Useful for fixing breaks in the mesh caused by some small ledges.

This produces bad results depending on how big your <code>cellsize</code> parameter is, but generating the mesh in this way will be faster than simply decreasing the <code>cellheight</code>.
</li>
</ul>

==Using a Navigation Mesh==

Navigation mesh files go in the <code>maps/</code> directory either in the folder specified by the <code>fs_game</code> cvar, or in the maps folder inside a map's <code>.pk3</code> file.

==Testing the Mesh==

* You may test your map locally by entering <code>\devmap <var>mapName</var></code> as you would to test any map at any time. Note, of course, that this will disconnect you from whatever game you may currently be in.
* To enable drawing the navigation mesh, use <code>navedit enable navmeshname</code> where "navmeshname" is one of: human_base, human_bsuit, builder, builder-upg, level0, level1, level1upg, level2, level2upg, level3, level3upg, level4. level4 is tyrant, level3 is dragoon, level2 is marauder, level1 is basilisk, level0 is dretch. The two builder navmeshes are not used at this time.
* Add bots with the <code>bot</code> command and spectate the game.

==Editing the Navigation Mesh==
Navmesh editing is still a work in progress, but it can be useful for fixing unnavigable ledges.

Unfortunately, automatic navigation mesh generation that fully supports all of the map features and player abilities in Unvanquished is incredibly difficult. Automatic generation will usually produce a very satisfactory base mesh, but some areas may need further tweaking.

To edit the navmesh, you must select the one you wish to edit using the <code>navedit</code> command.

To add connections use the <code>addcon</code> command.

A oneway connection will only allow bots to move from the start of the connection to the end of the connection, but not from the end to the start. A twoway connection will allow bots to move in either direction along the connection. The radius of the connection is how far away the center of the bot has to be from the middle to take the connection.

Modifications to the navmesh are made in real time, so any bots that have spawned will react accordingly.

When you are done editing a specific navmesh, you can use <code>navedit save</code> to save your work.
[[Category:Bots]]

Formats/Navigation mesh

2013-10-11T15:51:50Z

Fuma: /* Testing the Mesh */

The Daemon engine supports automatic navigation mesh generation from bsp map files. This navigation mesh (or "navmesh" for short) is used by the bots to navigate throughout the world.

==Generating a Navigation Mesh==

The -nav parameter to daemonmap will generate a navigation mesh from a bsp file.
Use it like so:

===Windows===

daemonmap.exe -game unv -nav mapname.bsp

===Linux===

./daemonmap -game unv -nav mapname.bsp

===Optional Parameters===

The navigation mesh generation process is conservative by default. This means some areas (particularly, small ledges) that should be walkable may instead create a break in the navmesh which bots interpret as "I am unable to go past there." The following optional parameters give the map maker some control over navmesh generation to help with this.

<ul>
<li><code>-cellheight</code>

A lower cellheight will increase mesh generation accuracy at the cost of generation time and mesh size.

If there are gaps in the navigation mesh even though a player can easily just walk to get through, you can decrease the value to help.
</li>
<li><code>-median</code>

Applies a median filter to the walkable areas of the mesh to help contain any "noise."

See [http://digestingduck.blogspot.com/2010/07/recast-area-types-per-triangle.html this article] for more information.
</li>
<li><code>-optimistic</code>

Attempts to compensate for cellsize inaccuracy by increasing the stepheight navigation mesh generation parameter based on the current samplesize. It is recommended to be used with a lower than default cellsize to help avoid over optimistic assumptions (i.e., saying some areas are walkable that really aren't). Useful for fixing breaks in the mesh caused by some small ledges.

This produces bad results depending on how big your <code>cellsize</code> parameter is, but generating the mesh in this way will be faster than simply decreasing the <code>cellheight</code>.
</li>
</ul>

==Using a Navigation Mesh==

Navigation mesh files go in the <code>maps/</code> directory either in the folder specified by the <code>fs_game</code> cvar, or in the maps folder inside a map's <code>.pk3</code> file.

==Testing the Mesh==

* You may test your map locally by entering <code>\devmap <var>mapName</var></code> as you would to test any map at any time. Note, of course, that this will disconnect you from whatever game you may currently be in.
* To enable drawing the navigation mesh, use <code>navedit enable navmeshname</code> where "navmeshname" is one of: human_base, human_bsuit, builder, builder-upg, level0, level1, level1upg, level2, level2upg, level3, level3upg, level4. level4 is tyrant, level3 is dragoon, level2 is marauder, level1 is basilisk, level0 is dretch. The two builder navmeshes are not used at this time.
* Add bots with the <code>bot</code> command and spectate the game.

==Editing the Navigation Mesh==
Unfortunately, automatic navigation mesh generation that fully supports all of the map features and player abilities in Unvanquished is incredibly difficult. Automatic generation will usually produce a very satisfactory base mesh, but some areas may need further tweaking.

===Adding Jump Links===
===Adding Ladder Links===
===Adding Pounce Links===
===Adding Drop off Links===
===Adding Walk Links===
[[Category:Bots]]

Formats/Navigation mesh

2013-10-11T15:46:21Z

Fuma: /* Optional Parameters */

The Daemon engine supports automatic navigation mesh generation from bsp map files. This navigation mesh (or "navmesh" for short) is used by the bots to navigate throughout the world.

==Generating a Navigation Mesh==

The -nav parameter to daemonmap will generate a navigation mesh from a bsp file.
Use it like so:

===Windows===

daemonmap.exe -game unv -nav mapname.bsp

===Linux===

./daemonmap -game unv -nav mapname.bsp

===Optional Parameters===

The navigation mesh generation process is conservative by default. This means some areas (particularly, small ledges) that should be walkable may instead create a break in the navmesh which bots interpret as "I am unable to go past there." The following optional parameters give the map maker some control over navmesh generation to help with this.

<ul>
<li><code>-cellheight</code>

A lower cellheight will increase mesh generation accuracy at the cost of generation time and mesh size.

If there are gaps in the navigation mesh even though a player can easily just walk to get through, you can decrease the value to help.
</li>
<li><code>-median</code>

Applies a median filter to the walkable areas of the mesh to help contain any "noise."

See [http://digestingduck.blogspot.com/2010/07/recast-area-types-per-triangle.html this article] for more information.
</li>
<li><code>-optimistic</code>

Attempts to compensate for cellsize inaccuracy by increasing the stepheight navigation mesh generation parameter based on the current samplesize. It is recommended to be used with a lower than default cellsize to help avoid over optimistic assumptions (i.e., saying some areas are walkable that really aren't). Useful for fixing breaks in the mesh caused by some small ledges.

This produces bad results depending on how big your <code>cellsize</code> parameter is, but generating the mesh in this way will be faster than simply decreasing the <code>cellheight</code>.
</li>
</ul>

==Using a Navigation Mesh==

Navigation mesh files go in the <code>maps/</code> directory either in the folder specified by the <code>fs_game</code> cvar, or in the maps folder inside a map's <code>.pk3</code> file.

==Testing the Mesh==

* You may test your map locally by entering <code>\devmap <var>mapName</var></code> as you would to test any map at any time. Note, of course, that this will disconnect you from whatever game you may currently be in.
* To enable drawing the navigation mesh, set <code>r_debugSurface</code> to <code>1</code>.
* Add bots with the <code>bot</code> command and spectate the game.

==Editing the Navigation Mesh==
Unfortunately, automatic navigation mesh generation that fully supports all of the map features and player abilities in Unvanquished is incredibly difficult. Automatic generation will usually produce a very satisfactory base mesh, but some areas may need further tweaking.

===Adding Jump Links===
===Adding Ladder Links===
===Adding Pounce Links===
===Adding Drop off Links===
===Adding Walk Links===
[[Category:Bots]]

Technical Documentation

2013-04-24T04:06:09Z

Fuma: /* Compile Macros */

If you have a question that is not answered here, you can always hop on the [http://unvanquished.net/forum/forumdisplay.php/30-Programming programming sub-forums] or [[IRC]].

==Getting Started==

If you have not already, go [[Getting_the_source|get the code]], read up on your options for [[development environments]], and [[Compiling_the_source|compile it]]. Instructions are available for a variety of platforms. If your platform of choice is not listed, you are welcome to add instructions for it.

From there, play the game! The [[Running the game]] page contains documentation on all the most commonly used and user-accessible commands and console variables. If you have trouble, see the [[troubleshooting]] page for possible solutions. Additional documentation is available on console variables:
* [[New_Cvars|Cvars that are new to Daemon]]
* [[Renderer_Status|Cvars for the renderer]] — This page also lists information on what renderer features are known to have issues.

There are also very detailed instructions on [[Testing|testing the game]], which includes information on using sophisticated profiling tools such as apitrace, GPUPerfStudio, gDEBugger, valgrind, and clang-analyzer.

===Need something to work on?===

There's lots of places to look for work to do:

* You are always welcome to fix any [https://github.com/Unvanquished/Unvanquished/issues issues reported on the bug tracker]. Just either leave a comment on the issue you're interested in or drop in [[IRC]] beforehand to let us know that you're working on it, so we don't try to work on it at the same time. Do be aware that we have several sub-projects, each with their own bug tracker, which are all listed on the [[Bug reporting|Bug Reporting]] page.
* Quick and easy tasks are listed on the [[Contributor Quickies]] page.
* More involved tasks are listed on the [[Programming Task List]].
* The most daunting challenges are listed on the [[Feature Proposals]] page. '''Be sure to communicate with us if you intend on working on one of these features!'''

===Giving Back===

You are welcome to contribute in any way possible! We have [[Contributing_code|guidelines for contributing code]] as well as documentation on [[Coding_convention|coding conventions]].

==Branches==

The following branches are under active development and may be of interest:

* <code>librocket</code> — Work to integrate libRocket is being done on this branch. libRocket is a library that will allow us to create user interfaces using dialects of HTML and CSS.
* <code>bots2</code> — New bot code, using behavior trees.

==Language Oddities==

<ul>
<li>You must use the <code>INLINE</code> macro instead of <code>inline</code>.
<li>You must cast integers that are being used as enum values to an enum type. For example:
<pre>
BG_Class ( ( class_t ) self->client->ps.stats[ STAT_CLASS ] )
</pre>
</li>
</ul>

==Source Code & Data Structure==

* <code>main/</code> Data associated with the game.
** <code>def/</code> Entity definitions for [[Mapping|Radiant]].
** <code>fonts/</code>
** <code>gfx/</code>
** <code>glsl/</code> OpenGL shader code.
** <code>lights/</code>
** <code>models/</code>
** <code>scripts/</code>
** <code>sound/</code>
** <code>translation/</code>
** <code>ui/</code>
* <code>src/</code>
** <code>engine/</code> Engine source code.
*** <code>asm/</code>
*** <code>client/</code>
*** <code>null/</code>
*** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
*** <code>renderer/</code> Vanilla (fixed-function pipeline) renderer
*** <code>rendererGL/</code> Modern XReal-based renderer
*** <code>server/</code>
*** <code>sys/</code>
** <code>gamelogic/</code> Code that falls outside the scope of the core engine. These are all run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>game/</code> Server-side game code.
*** <code>ui/</code> User interface code.

==Program Entry Point==

The <code>main</code> function may be found at around line 591 of {{SourceFile|src/engine/sys/sys_main.c}}. Note that some magic happens on the Mac in {{SourceFile|src/engine/sys/SDLMain.m}}.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [http://www.ra.is/unlagged/ Unlagged mod].

==Data Files==

Daemon uses a variety of file formats. Many of these formats are custom. 

* Bot behavior trees
* Player configuration files
** Crosshair configuration
** Pubkey
** GUID
* Server configuration files
** [[Map_layouts|Map layouts]]
** Map rotations
* Particle & trail system files
* Sound configurations
** [[Music_and_sounds#Buildables|Buildables]]
* Model data ([[Exporting_Models#What_is_MD5.3F|discussion of supported formats]])
** Skins
** [[Exporting_Models#MD3_3|MD3 animation configuration files]] — specify which frames are for which animations
** Configuration files
*** [[Exporting_Models#Buildables_2|Buildables]]
*** [[Exporting_Models#Weapons_2|Weapons]]
*** [[Exporting_Models#Player_models_2|Player models]]
* Map data
** Map geometry (BSPs)
** Color grading configurations

==Game Logic==

Game logic is split into three areas: user interface, server-side, and client-side. Each runs in its own [[Virtual_machines|virtual machine]].

==Client-Side==

Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/gamelogic/cgame/cg_main.c|cg_main.c}})

Constants used to define gamelogic variables are in {{SourceFile|src/gamelogic/game/tremulous.h}}.

Types:
* <code>buildableInfo_t</code> — Encapsulates data associated with buildables (sounds, animations, etc.).
* <code>buildable_t</code> — An enumeration of all buildable types.
* <code>buildableAttributes_t</code> — Encapsulates gameplay information associated with buildables. There is an array of these called <code>bg_buildableList</code>.

==Server-Side==

Server game state initialization occurs in <code>G_InitGame()</code> in {{SourceFile|src/gamelogic/game/g_main.c}}.

==Particle & Trail System==

For now, please see the [http://tremulous.net/manual/#x1-130003.2 Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|src/engine/rendererGL}}. This renderer is often referred to as the "GL3" renderer, whereas the legacy renderer (found in {{SourceFile|src/engine/renderer}}) is often referred to as the "vanilla" renderer.

===Notes===

* There is some incomplete disabled Direct3D code mixed in the modern OpenGL renderer code.
* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|src/engine/rendererGL/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single GLShaderManager class
* Compiled shaders are cached to disk when possible to speed up load times
* Shader compilation may be done up front before the game loads, or delayed till the main menu depending on the value of r_lazyShaders
* All possible parameters (what OpenGL calls [http://www.opengl.org/sdk/docs/man4/xhtml/glUniform.xml "uniform variables"]) that may be passed to a shader are enumerated through multiple inheritance.
E.g., <code>gl_genericShader</code> is of type <code>GLShader_generic*</code> which derives from the following classes:
** <code>GLShader</code>
** <code>u_ColorMap</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_AlphaTest</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_BoneMatrix</code>
** <code>u_VertexInterpolation</code>
** <code>u_PortalPlane</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_PORTAL_CLIPPING</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_DEFORM_VERTEXES</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>

* The u_* parent classes provide functions that allow external code to set shader uniforms. e.g gl_genericShader->SetUniform_ColorTextureMatrix()

* GLSL shaders may be found in <code>main/glsl/</code>. Please see the [[GLSL Shaders|full article]] for a complete listing.

===Helper Classes===

As mentioned above, shader classes make use of multiple inheritance to give them the relevant methods for controlling their behavior.

====Compile Macros====

Compile macros are used to reduce the number of uniforms needed, and speed up execution by eliminating useless if ( ) statements.

They also allow for easy code reuse when turning off some features like e.g Normal Mapping.

Compile macros are set when rendering before the call to shader->BindProgram().

* <code>GLCompileMacro_USE_ALPHA_TESTING</code>
* <code>GLCompileMacro_USE_PORTAL_CLIPPING</code>
* <code>GLCompileMacro_USE_FRUSTUM_CLIPPING</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_DEFORM_VERTEXES</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_NORMAL_MAPPING</code>
* <code>GLCompileMacro_USE_PARALLAX_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_EYE_OUTSIDE</code>
* <code>GLCompileMacro_BRIGHTPASS_FILTER</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_GBUFFER</code>

===Resources===

Mac OS X users with XCode installed can access OpenGL man pages via the terminal. 

Alternatively, OpenGL API reference documentation is available online:
* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages]
* [http://www.opengl.org/sdk/docs/manglsl/ OpenGL Shading Language (GLSL) Reference Pages]
* [http://www.khronos.org/files/opengl-quick-reference-card.pdf OpenGL 3.3 & GLSL Quick Reference Card]

==Valgrind and fglrx==

fglrx drivers cause Valgrind to spew out a lot of false errors. You can suppress these by using the --suppressions=/path/to/file.supp flag. You must pass the full path (no use of the tilde symbol). The following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file. Keep in mind that the location of the fglrx library may need to be changed.

==Resources==

===Publications===

<ul>
<li>[http://halo.bungie.net/Inside/publications.aspx Bungie, Inc.] — creators of the Marathon, Myth, and Halo franchises.</li>
<li>[http://dice.se/publications/ DICE SE] — creators of the Battlefield franchise.</li>
<li>[http://www.guerrilla-games.com/publications/ Guerilla Games] — creators of the Killzone franchise.
Also of interest is the "Making of Killzone 2" video series, not listed on their site:
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-1?objectid=748475 Part 1]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-2?objectid=748475 Part 2]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-3?objectid=748475 Part 3]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-4?objectid=748475 Part 4]
</li>
<li>[http://www.valvesoftware.com/company/publications.html Valve Software] — creators of the Half-Life franchise.</li>
</ul>

===General Game Development===

* [http://devmaster.net/ Devmaster.net]

===OpenGL===

* [http://www.opengl.org/ Official OpenGL page]
* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages]
* [http://www.opengl.org/sdk/docs/manglsl/ OpenGL Shading Language Reference Pages]
* [http://arcsynthesis.org/gltut/ Learning Modern 3D Graphics Programming]

===Quake===

* [http://fd.fabiensanglard.net/doom3/pdfs/johnc-plan_1999.pdf John Carmack's notes from development]
* "Looking at the Quake 3 Source"
** [http://element61.blogspot.com/2005/08/looking-at-quake-3-source-part-1.html Part 1]
** [http://element61.blogspot.com/2005/08/looking-at-quake-3-source-part-2.html Part 2]
** [http://element61.blogspot.com/2005/09/looking-at-quake-3-source-part-3.html Part 3]
* [http://www.quakewiki.net/archives/code3arena/ Code3Arena]
* [http://www.modwiki.net/wiki/MD5_(file_format) MD5 file format]
* [http://tfc.duke.free.fr/coding/md5-specs-en.html Another MD5 format article]
* [http://fabiensanglard.net/quake3/index.php Quake 3 Source Code Review]
* [http://www.quake3world.com/forum/index.php Quake3World Discussion Forums]
* [http://wiki.ioquake3.org/ ioquake3 project wiki] — Primarily oriented for users, developers and server administrators.

Technical Documentation

2013-04-24T04:05:51Z

Fuma: /* Helper Classes */

If you have a question that is not answered here, you can always hop on the [http://unvanquished.net/forum/forumdisplay.php/30-Programming programming sub-forums] or [[IRC]].

==Getting Started==

If you have not already, go [[Getting_the_source|get the code]], read up on your options for [[development environments]], and [[Compiling_the_source|compile it]]. Instructions are available for a variety of platforms. If your platform of choice is not listed, you are welcome to add instructions for it.

From there, play the game! The [[Running the game]] page contains documentation on all the most commonly used and user-accessible commands and console variables. If you have trouble, see the [[troubleshooting]] page for possible solutions. Additional documentation is available on console variables:
* [[New_Cvars|Cvars that are new to Daemon]]
* [[Renderer_Status|Cvars for the renderer]] — This page also lists information on what renderer features are known to have issues.

There are also very detailed instructions on [[Testing|testing the game]], which includes information on using sophisticated profiling tools such as apitrace, GPUPerfStudio, gDEBugger, valgrind, and clang-analyzer.

===Need something to work on?===

There's lots of places to look for work to do:

* You are always welcome to fix any [https://github.com/Unvanquished/Unvanquished/issues issues reported on the bug tracker]. Just either leave a comment on the issue you're interested in or drop in [[IRC]] beforehand to let us know that you're working on it, so we don't try to work on it at the same time. Do be aware that we have several sub-projects, each with their own bug tracker, which are all listed on the [[Bug reporting|Bug Reporting]] page.
* Quick and easy tasks are listed on the [[Contributor Quickies]] page.
* More involved tasks are listed on the [[Programming Task List]].
* The most daunting challenges are listed on the [[Feature Proposals]] page. '''Be sure to communicate with us if you intend on working on one of these features!'''

===Giving Back===

You are welcome to contribute in any way possible! We have [[Contributing_code|guidelines for contributing code]] as well as documentation on [[Coding_convention|coding conventions]].

==Branches==

The following branches are under active development and may be of interest:

* <code>librocket</code> — Work to integrate libRocket is being done on this branch. libRocket is a library that will allow us to create user interfaces using dialects of HTML and CSS.
* <code>bots2</code> — New bot code, using behavior trees.

==Language Oddities==

<ul>
<li>You must use the <code>INLINE</code> macro instead of <code>inline</code>.
<li>You must cast integers that are being used as enum values to an enum type. For example:
<pre>
BG_Class ( ( class_t ) self->client->ps.stats[ STAT_CLASS ] )
</pre>
</li>
</ul>

==Source Code & Data Structure==

* <code>main/</code> Data associated with the game.
** <code>def/</code> Entity definitions for [[Mapping|Radiant]].
** <code>fonts/</code>
** <code>gfx/</code>
** <code>glsl/</code> OpenGL shader code.
** <code>lights/</code>
** <code>models/</code>
** <code>scripts/</code>
** <code>sound/</code>
** <code>translation/</code>
** <code>ui/</code>
* <code>src/</code>
** <code>engine/</code> Engine source code.
*** <code>asm/</code>
*** <code>client/</code>
*** <code>null/</code>
*** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
*** <code>renderer/</code> Vanilla (fixed-function pipeline) renderer
*** <code>rendererGL/</code> Modern XReal-based renderer
*** <code>server/</code>
*** <code>sys/</code>
** <code>gamelogic/</code> Code that falls outside the scope of the core engine. These are all run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>game/</code> Server-side game code.
*** <code>ui/</code> User interface code.

==Program Entry Point==

The <code>main</code> function may be found at around line 591 of {{SourceFile|src/engine/sys/sys_main.c}}. Note that some magic happens on the Mac in {{SourceFile|src/engine/sys/SDLMain.m}}.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [http://www.ra.is/unlagged/ Unlagged mod].

==Data Files==

Daemon uses a variety of file formats. Many of these formats are custom. 

* Bot behavior trees
* Player configuration files
** Crosshair configuration
** Pubkey
** GUID
* Server configuration files
** [[Map_layouts|Map layouts]]
** Map rotations
* Particle & trail system files
* Sound configurations
** [[Music_and_sounds#Buildables|Buildables]]
* Model data ([[Exporting_Models#What_is_MD5.3F|discussion of supported formats]])
** Skins
** [[Exporting_Models#MD3_3|MD3 animation configuration files]] — specify which frames are for which animations
** Configuration files
*** [[Exporting_Models#Buildables_2|Buildables]]
*** [[Exporting_Models#Weapons_2|Weapons]]
*** [[Exporting_Models#Player_models_2|Player models]]
* Map data
** Map geometry (BSPs)
** Color grading configurations

==Game Logic==

Game logic is split into three areas: user interface, server-side, and client-side. Each runs in its own [[Virtual_machines|virtual machine]].

==Client-Side==

Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/gamelogic/cgame/cg_main.c|cg_main.c}})

Constants used to define gamelogic variables are in {{SourceFile|src/gamelogic/game/tremulous.h}}.

Types:
* <code>buildableInfo_t</code> — Encapsulates data associated with buildables (sounds, animations, etc.).
* <code>buildable_t</code> — An enumeration of all buildable types.
* <code>buildableAttributes_t</code> — Encapsulates gameplay information associated with buildables. There is an array of these called <code>bg_buildableList</code>.

==Server-Side==

Server game state initialization occurs in <code>G_InitGame()</code> in {{SourceFile|src/gamelogic/game/g_main.c}}.

==Particle & Trail System==

For now, please see the [http://tremulous.net/manual/#x1-130003.2 Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|src/engine/rendererGL}}. This renderer is often referred to as the "GL3" renderer, whereas the legacy renderer (found in {{SourceFile|src/engine/renderer}}) is often referred to as the "vanilla" renderer.

===Notes===

* There is some incomplete disabled Direct3D code mixed in the modern OpenGL renderer code.
* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|src/engine/rendererGL/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single GLShaderManager class
* Compiled shaders are cached to disk when possible to speed up load times
* Shader compilation may be done up front before the game loads, or delayed till the main menu depending on the value of r_lazyShaders
* All possible parameters (what OpenGL calls [http://www.opengl.org/sdk/docs/man4/xhtml/glUniform.xml "uniform variables"]) that may be passed to a shader are enumerated through multiple inheritance.
E.g., <code>gl_genericShader</code> is of type <code>GLShader_generic*</code> which derives from the following classes:
** <code>GLShader</code>
** <code>u_ColorMap</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_AlphaTest</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_BoneMatrix</code>
** <code>u_VertexInterpolation</code>
** <code>u_PortalPlane</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_PORTAL_CLIPPING</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_DEFORM_VERTEXES</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>

* The u_* parent classes provide functions that allow external code to set shader uniforms. e.g gl_genericShader->SetUniform_ColorTextureMatrix()

* GLSL shaders may be found in <code>main/glsl/</code>. Please see the [[GLSL Shaders|full article]] for a complete listing.

===Helper Classes===

As mentioned above, shader classes make use of multiple inheritance to give them the relevant methods for controlling their behavior.

====Compile Macros====

Compile macros are used to reduce the number of uniforms needed, and speed up execution by eliminating useless if ( ) statements.
They also allow for easy code reuse when turning off some features like e.g Normal Mapping.
Compile macros are set when rendering before the call to shader->BindProgram().

* <code>GLCompileMacro_USE_ALPHA_TESTING</code>
* <code>GLCompileMacro_USE_PORTAL_CLIPPING</code>
* <code>GLCompileMacro_USE_FRUSTUM_CLIPPING</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_DEFORM_VERTEXES</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_NORMAL_MAPPING</code>
* <code>GLCompileMacro_USE_PARALLAX_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_EYE_OUTSIDE</code>
* <code>GLCompileMacro_BRIGHTPASS_FILTER</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_GBUFFER</code>

===Resources===

Mac OS X users with XCode installed can access OpenGL man pages via the terminal. 

Alternatively, OpenGL API reference documentation is available online:
* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages]
* [http://www.opengl.org/sdk/docs/manglsl/ OpenGL Shading Language (GLSL) Reference Pages]
* [http://www.khronos.org/files/opengl-quick-reference-card.pdf OpenGL 3.3 & GLSL Quick Reference Card]

==Valgrind and fglrx==

fglrx drivers cause Valgrind to spew out a lot of false errors. You can suppress these by using the --suppressions=/path/to/file.supp flag. You must pass the full path (no use of the tilde symbol). The following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file. Keep in mind that the location of the fglrx library may need to be changed.

==Resources==

===Publications===

<ul>
<li>[http://halo.bungie.net/Inside/publications.aspx Bungie, Inc.] — creators of the Marathon, Myth, and Halo franchises.</li>
<li>[http://dice.se/publications/ DICE SE] — creators of the Battlefield franchise.</li>
<li>[http://www.guerrilla-games.com/publications/ Guerilla Games] — creators of the Killzone franchise.
Also of interest is the "Making of Killzone 2" video series, not listed on their site:
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-1?objectid=748475 Part 1]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-2?objectid=748475 Part 2]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-3?objectid=748475 Part 3]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-4?objectid=748475 Part 4]
</li>
<li>[http://www.valvesoftware.com/company/publications.html Valve Software] — creators of the Half-Life franchise.</li>
</ul>

===General Game Development===

* [http://devmaster.net/ Devmaster.net]

===OpenGL===

* [http://www.opengl.org/ Official OpenGL page]
* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages]
* [http://www.opengl.org/sdk/docs/manglsl/ OpenGL Shading Language Reference Pages]
* [http://arcsynthesis.org/gltut/ Learning Modern 3D Graphics Programming]

===Quake===

* [http://fd.fabiensanglard.net/doom3/pdfs/johnc-plan_1999.pdf John Carmack's notes from development]
* "Looking at the Quake 3 Source"
** [http://element61.blogspot.com/2005/08/looking-at-quake-3-source-part-1.html Part 1]
** [http://element61.blogspot.com/2005/08/looking-at-quake-3-source-part-2.html Part 2]
** [http://element61.blogspot.com/2005/09/looking-at-quake-3-source-part-3.html Part 3]
* [http://www.quakewiki.net/archives/code3arena/ Code3Arena]
* [http://www.modwiki.net/wiki/MD5_(file_format) MD5 file format]
* [http://tfc.duke.free.fr/coding/md5-specs-en.html Another MD5 format article]
* [http://fabiensanglard.net/quake3/index.php Quake 3 Source Code Review]
* [http://www.quake3world.com/forum/index.php Quake3World Discussion Forums]
* [http://wiki.ioquake3.org/ ioquake3 project wiki] — Primarily oriented for users, developers and server administrators.

Technical Documentation

2013-04-24T03:57:56Z

Fuma: /* Notes */

If you have a question that is not answered here, you can always hop on the [http://unvanquished.net/forum/forumdisplay.php/30-Programming programming sub-forums] or [[IRC]].

==Getting Started==

If you have not already, go [[Getting_the_source|get the code]], read up on your options for [[development environments]], and [[Compiling_the_source|compile it]]. Instructions are available for a variety of platforms. If your platform of choice is not listed, you are welcome to add instructions for it.

From there, play the game! The [[Running the game]] page contains documentation on all the most commonly used and user-accessible commands and console variables. If you have trouble, see the [[troubleshooting]] page for possible solutions. Additional documentation is available on console variables:
* [[New_Cvars|Cvars that are new to Daemon]]
* [[Renderer_Status|Cvars for the renderer]] — This page also lists information on what renderer features are known to have issues.

There are also very detailed instructions on [[Testing|testing the game]], which includes information on using sophisticated profiling tools such as apitrace, GPUPerfStudio, gDEBugger, valgrind, and clang-analyzer.

===Need something to work on?===

There's lots of places to look for work to do:

* You are always welcome to fix any [https://github.com/Unvanquished/Unvanquished/issues issues reported on the bug tracker]. Just either leave a comment on the issue you're interested in or drop in [[IRC]] beforehand to let us know that you're working on it, so we don't try to work on it at the same time. Do be aware that we have several sub-projects, each with their own bug tracker, which are all listed on the [[Bug reporting|Bug Reporting]] page.
* Quick and easy tasks are listed on the [[Contributor Quickies]] page.
* More involved tasks are listed on the [[Programming Task List]].
* The most daunting challenges are listed on the [[Feature Proposals]] page. '''Be sure to communicate with us if you intend on working on one of these features!'''

===Giving Back===

You are welcome to contribute in any way possible! We have [[Contributing_code|guidelines for contributing code]] as well as documentation on [[Coding_convention|coding conventions]].

==Branches==

The following branches are under active development and may be of interest:

* <code>librocket</code> — Work to integrate libRocket is being done on this branch. libRocket is a library that will allow us to create user interfaces using dialects of HTML and CSS.
* <code>bots2</code> — New bot code, using behavior trees.

==Language Oddities==

<ul>
<li>You must use the <code>INLINE</code> macro instead of <code>inline</code>.
<li>You must cast integers that are being used as enum values to an enum type. For example:
<pre>
BG_Class ( ( class_t ) self->client->ps.stats[ STAT_CLASS ] )
</pre>
</li>
</ul>

==Source Code & Data Structure==

* <code>main/</code> Data associated with the game.
** <code>def/</code> Entity definitions for [[Mapping|Radiant]].
** <code>fonts/</code>
** <code>gfx/</code>
** <code>glsl/</code> OpenGL shader code.
** <code>lights/</code>
** <code>models/</code>
** <code>scripts/</code>
** <code>sound/</code>
** <code>translation/</code>
** <code>ui/</code>
* <code>src/</code>
** <code>engine/</code> Engine source code.
*** <code>asm/</code>
*** <code>client/</code>
*** <code>null/</code>
*** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
*** <code>renderer/</code> Vanilla (fixed-function pipeline) renderer
*** <code>rendererGL/</code> Modern XReal-based renderer
*** <code>server/</code>
*** <code>sys/</code>
** <code>gamelogic/</code> Code that falls outside the scope of the core engine. These are all run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>game/</code> Server-side game code.
*** <code>ui/</code> User interface code.

==Program Entry Point==

The <code>main</code> function may be found at around line 591 of {{SourceFile|src/engine/sys/sys_main.c}}. Note that some magic happens on the Mac in {{SourceFile|src/engine/sys/SDLMain.m}}.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [http://www.ra.is/unlagged/ Unlagged mod].

==Data Files==

Daemon uses a variety of file formats. Many of these formats are custom. 

* Bot behavior trees
* Player configuration files
** Crosshair configuration
** Pubkey
** GUID
* Server configuration files
** [[Map_layouts|Map layouts]]
** Map rotations
* Particle & trail system files
* Sound configurations
** [[Music_and_sounds#Buildables|Buildables]]
* Model data ([[Exporting_Models#What_is_MD5.3F|discussion of supported formats]])
** Skins
** [[Exporting_Models#MD3_3|MD3 animation configuration files]] — specify which frames are for which animations
** Configuration files
*** [[Exporting_Models#Buildables_2|Buildables]]
*** [[Exporting_Models#Weapons_2|Weapons]]
*** [[Exporting_Models#Player_models_2|Player models]]
* Map data
** Map geometry (BSPs)
** Color grading configurations

==Game Logic==

Game logic is split into three areas: user interface, server-side, and client-side. Each runs in its own [[Virtual_machines|virtual machine]].

==Client-Side==

Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/gamelogic/cgame/cg_main.c|cg_main.c}})

Constants used to define gamelogic variables are in {{SourceFile|src/gamelogic/game/tremulous.h}}.

Types:
* <code>buildableInfo_t</code> — Encapsulates data associated with buildables (sounds, animations, etc.).
* <code>buildable_t</code> — An enumeration of all buildable types.
* <code>buildableAttributes_t</code> — Encapsulates gameplay information associated with buildables. There is an array of these called <code>bg_buildableList</code>.

==Server-Side==

Server game state initialization occurs in <code>G_InitGame()</code> in {{SourceFile|src/gamelogic/game/g_main.c}}.

==Particle & Trail System==

For now, please see the [http://tremulous.net/manual/#x1-130003.2 Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|src/engine/rendererGL}}. This renderer is often referred to as the "GL3" renderer, whereas the legacy renderer (found in {{SourceFile|src/engine/renderer}}) is often referred to as the "vanilla" renderer.

===Notes===

* There is some incomplete disabled Direct3D code mixed in the modern OpenGL renderer code.
* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|src/engine/rendererGL/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single GLShaderManager class
* Compiled shaders are cached to disk when possible to speed up load times
* Shader compilation may be done up front before the game loads, or delayed till the main menu depending on the value of r_lazyShaders
* All possible parameters (what OpenGL calls [http://www.opengl.org/sdk/docs/man4/xhtml/glUniform.xml "uniform variables"]) that may be passed to a shader are enumerated through multiple inheritance.
E.g., <code>gl_genericShader</code> is of type <code>GLShader_generic*</code> which derives from the following classes:
** <code>GLShader</code>
** <code>u_ColorMap</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_AlphaTest</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_BoneMatrix</code>
** <code>u_VertexInterpolation</code>
** <code>u_PortalPlane</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_PORTAL_CLIPPING</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_DEFORM_VERTEXES</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>

* The u_* parent classes provide functions that allow external code to set shader uniforms. e.g gl_genericShader->SetUniform_ColorTextureMatrix()

* GLSL shaders may be found in <code>main/glsl/</code>. Please see the [[GLSL Shaders|full article]] for a complete listing.

===Helper Classes===

As mentioned above, shader classes make use of multiple inheritance to give them the relevant methods for controlling their behavior.

====Uniform Variables====

Uniform variables are enumerated in the <code>shaderProgram_t</code> structure in {{SourceFile|src/engine/rendererGL/tr_local.h}}, and are controlled by classes beginning with the <code>u_</code> prefix:

* u_BoneMatrix — Provides the convenience method <code>SetUniform_BoneMatrix</code>.

====Compile Macros====

* <code>GLCompileMacro_USE_ALPHA_TESTING</code>
* <code>GLCompileMacro_USE_PORTAL_CLIPPING</code>
* <code>GLCompileMacro_USE_FRUSTUM_CLIPPING</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_DEFORM_VERTEXES</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_NORMAL_MAPPING</code>
* <code>GLCompileMacro_USE_PARALLAX_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_TWOSIDED</code>
* <code>GLCompileMacro_EYE_OUTSIDE</code>
* <code>GLCompileMacro_BRIGHTPASS_FILTER</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_GBUFFER</code>

===Resources===

Mac OS X users with XCode installed can access OpenGL man pages via the terminal. 

Alternatively, OpenGL API reference documentation is available online:
* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages]
* [http://www.opengl.org/sdk/docs/manglsl/ OpenGL Shading Language (GLSL) Reference Pages]
* [http://www.khronos.org/files/opengl-quick-reference-card.pdf OpenGL 3.3 & GLSL Quick Reference Card]

==Valgrind and fglrx==

fglrx drivers cause Valgrind to spew out a lot of false errors. You can suppress these by using the --suppressions=/path/to/file.supp flag. You must pass the full path (no use of the tilde symbol). The following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file. Keep in mind that the location of the fglrx library may need to be changed.

==Resources==

===Publications===

<ul>
<li>[http://halo.bungie.net/Inside/publications.aspx Bungie, Inc.] — creators of the Marathon, Myth, and Halo franchises.</li>
<li>[http://dice.se/publications/ DICE SE] — creators of the Battlefield franchise.</li>
<li>[http://www.guerrilla-games.com/publications/ Guerilla Games] — creators of the Killzone franchise.
Also of interest is the "Making of Killzone 2" video series, not listed on their site:
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-1?objectid=748475 Part 1]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-2?objectid=748475 Part 2]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-3?objectid=748475 Part 3]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-4?objectid=748475 Part 4]
</li>
<li>[http://www.valvesoftware.com/company/publications.html Valve Software] — creators of the Half-Life franchise.</li>
</ul>

===General Game Development===

* [http://devmaster.net/ Devmaster.net]

===OpenGL===

* [http://www.opengl.org/ Official OpenGL page]
* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages]
* [http://www.opengl.org/sdk/docs/manglsl/ OpenGL Shading Language Reference Pages]
* [http://arcsynthesis.org/gltut/ Learning Modern 3D Graphics Programming]

===Quake===

* [http://fd.fabiensanglard.net/doom3/pdfs/johnc-plan_1999.pdf John Carmack's notes from development]
* "Looking at the Quake 3 Source"
** [http://element61.blogspot.com/2005/08/looking-at-quake-3-source-part-1.html Part 1]
** [http://element61.blogspot.com/2005/08/looking-at-quake-3-source-part-2.html Part 2]
** [http://element61.blogspot.com/2005/09/looking-at-quake-3-source-part-3.html Part 3]
* [http://www.quakewiki.net/archives/code3arena/ Code3Arena]
* [http://www.modwiki.net/wiki/MD5_(file_format) MD5 file format]
* [http://tfc.duke.free.fr/coding/md5-specs-en.html Another MD5 format article]
* [http://fabiensanglard.net/quake3/index.php Quake 3 Source Code Review]
* [http://www.quake3world.com/forum/index.php Quake3World Discussion Forums]
* [http://wiki.ioquake3.org/ ioquake3 project wiki] — Primarily oriented for users, developers and server administrators.

Technical Documentation

2013-04-24T03:55:40Z

Fuma: /* Notes */

If you have a question that is not answered here, you can always hop on the [http://unvanquished.net/forum/forumdisplay.php/30-Programming programming sub-forums] or [[IRC]].

==Getting Started==

If you have not already, go [[Getting_the_source|get the code]], read up on your options for [[development environments]], and [[Compiling_the_source|compile it]]. Instructions are available for a variety of platforms. If your platform of choice is not listed, you are welcome to add instructions for it.

From there, play the game! The [[Running the game]] page contains documentation on all the most commonly used and user-accessible commands and console variables. If you have trouble, see the [[troubleshooting]] page for possible solutions. Additional documentation is available on console variables:
* [[New_Cvars|Cvars that are new to Daemon]]
* [[Renderer_Status|Cvars for the renderer]] — This page also lists information on what renderer features are known to have issues.

There are also very detailed instructions on [[Testing|testing the game]], which includes information on using sophisticated profiling tools such as apitrace, GPUPerfStudio, gDEBugger, valgrind, and clang-analyzer.

===Need something to work on?===

There's lots of places to look for work to do:

* You are always welcome to fix any [https://github.com/Unvanquished/Unvanquished/issues issues reported on the bug tracker]. Just either leave a comment on the issue you're interested in or drop in [[IRC]] beforehand to let us know that you're working on it, so we don't try to work on it at the same time. Do be aware that we have several sub-projects, each with their own bug tracker, which are all listed on the [[Bug reporting|Bug Reporting]] page.
* Quick and easy tasks are listed on the [[Contributor Quickies]] page.
* More involved tasks are listed on the [[Programming Task List]].
* The most daunting challenges are listed on the [[Feature Proposals]] page. '''Be sure to communicate with us if you intend on working on one of these features!'''

===Giving Back===

You are welcome to contribute in any way possible! We have [[Contributing_code|guidelines for contributing code]] as well as documentation on [[Coding_convention|coding conventions]].

==Branches==

The following branches are under active development and may be of interest:

* <code>librocket</code> — Work to integrate libRocket is being done on this branch. libRocket is a library that will allow us to create user interfaces using dialects of HTML and CSS.
* <code>bots2</code> — New bot code, using behavior trees.

==Language Oddities==

<ul>
<li>You must use the <code>INLINE</code> macro instead of <code>inline</code>.
<li>You must cast integers that are being used as enum values to an enum type. For example:
<pre>
BG_Class ( ( class_t ) self->client->ps.stats[ STAT_CLASS ] )
</pre>
</li>
</ul>

==Source Code & Data Structure==

* <code>main/</code> Data associated with the game.
** <code>def/</code> Entity definitions for [[Mapping|Radiant]].
** <code>fonts/</code>
** <code>gfx/</code>
** <code>glsl/</code> OpenGL shader code.
** <code>lights/</code>
** <code>models/</code>
** <code>scripts/</code>
** <code>sound/</code>
** <code>translation/</code>
** <code>ui/</code>
* <code>src/</code>
** <code>engine/</code> Engine source code.
*** <code>asm/</code>
*** <code>client/</code>
*** <code>null/</code>
*** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
*** <code>renderer/</code> Vanilla (fixed-function pipeline) renderer
*** <code>rendererGL/</code> Modern XReal-based renderer
*** <code>server/</code>
*** <code>sys/</code>
** <code>gamelogic/</code> Code that falls outside the scope of the core engine. These are all run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>game/</code> Server-side game code.
*** <code>ui/</code> User interface code.

==Program Entry Point==

The <code>main</code> function may be found at around line 591 of {{SourceFile|src/engine/sys/sys_main.c}}. Note that some magic happens on the Mac in {{SourceFile|src/engine/sys/SDLMain.m}}.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [http://www.ra.is/unlagged/ Unlagged mod].

==Data Files==

Daemon uses a variety of file formats. Many of these formats are custom. 

* Bot behavior trees
* Player configuration files
** Crosshair configuration
** Pubkey
** GUID
* Server configuration files
** [[Map_layouts|Map layouts]]
** Map rotations
* Particle & trail system files
* Sound configurations
** [[Music_and_sounds#Buildables|Buildables]]
* Model data ([[Exporting_Models#What_is_MD5.3F|discussion of supported formats]])
** Skins
** [[Exporting_Models#MD3_3|MD3 animation configuration files]] — specify which frames are for which animations
** Configuration files
*** [[Exporting_Models#Buildables_2|Buildables]]
*** [[Exporting_Models#Weapons_2|Weapons]]
*** [[Exporting_Models#Player_models_2|Player models]]
* Map data
** Map geometry (BSPs)
** Color grading configurations

==Game Logic==

Game logic is split into three areas: user interface, server-side, and client-side. Each runs in its own [[Virtual_machines|virtual machine]].

==Client-Side==

Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/gamelogic/cgame/cg_main.c|cg_main.c}})

Constants used to define gamelogic variables are in {{SourceFile|src/gamelogic/game/tremulous.h}}.

Types:
* <code>buildableInfo_t</code> — Encapsulates data associated with buildables (sounds, animations, etc.).
* <code>buildable_t</code> — An enumeration of all buildable types.
* <code>buildableAttributes_t</code> — Encapsulates gameplay information associated with buildables. There is an array of these called <code>bg_buildableList</code>.

==Server-Side==

Server game state initialization occurs in <code>G_InitGame()</code> in {{SourceFile|src/gamelogic/game/g_main.c}}.

==Particle & Trail System==

For now, please see the [http://tremulous.net/manual/#x1-130003.2 Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|src/engine/rendererGL}}. This renderer is often referred to as the "GL3" renderer, whereas the legacy renderer (found in {{SourceFile|src/engine/renderer}}) is often referred to as the "vanilla" renderer.

===Notes===

* There is some incomplete disabled Direct3D code mixed in the modern OpenGL renderer code.
Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|src/engine/rendererGL/gl_shader.h}}.
* Compiled GLSL shader files (located in the hard-coded location <code>"glsl/<shadername>/"</code> with the <code>.bin</code> filename extension) are read by <code>GLShaderManager::LoadShaderBinary()</code>.
* Each GLSL shader has their compilation and loading controlled by the single GLShaderManager class
* Shader compilation may be done up front before the game loads, or delayed till the main menu depending on the value of r_lazyShaders
* All possible parameters (what OpenGL calls [http://www.opengl.org/sdk/docs/man4/xhtml/glUniform.xml "uniform variables"]) that may be passed to a shader are enumerated through multiple inheritance.
E.g., <code>gl_genericShader</code> is of type <code>GLShader_generic*</code> which derives from the following classes:
** <code>GLShader</code>
** <code>u_ColorMap</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_AlphaTest</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_BoneMatrix</code>
** <code>u_VertexInterpolation</code>
** <code>u_PortalPlane</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_PORTAL_CLIPPING</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_DEFORM_VERTEXES</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>

* The u_* parent classes provide functions that allow external code to set shader uniforms. e.g gl_genericShader->SetUniform_ColorTextureMatrix()

* GLSL shaders may be found in <code>main/glsl/</code>. Please see the [[GLSL Shaders|full article]] for a complete listing.

===Helper Classes===

As mentioned above, shader classes make use of multiple inheritance to give them the relevant methods for controlling their behavior.

====Uniform Variables====

Uniform variables are enumerated in the <code>shaderProgram_t</code> structure in {{SourceFile|src/engine/rendererGL/tr_local.h}}, and are controlled by classes beginning with the <code>u_</code> prefix:

* u_BoneMatrix — Provides the convenience method <code>SetUniform_BoneMatrix</code>.

====Compile Macros====

* <code>GLCompileMacro_USE_ALPHA_TESTING</code>
* <code>GLCompileMacro_USE_PORTAL_CLIPPING</code>
* <code>GLCompileMacro_USE_FRUSTUM_CLIPPING</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_DEFORM_VERTEXES</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_NORMAL_MAPPING</code>
* <code>GLCompileMacro_USE_PARALLAX_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_TWOSIDED</code>
* <code>GLCompileMacro_EYE_OUTSIDE</code>
* <code>GLCompileMacro_BRIGHTPASS_FILTER</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_GBUFFER</code>

===Resources===

Mac OS X users with XCode installed can access OpenGL man pages via the terminal. 

Alternatively, OpenGL API reference documentation is available online:
* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages]
* [http://www.opengl.org/sdk/docs/manglsl/ OpenGL Shading Language (GLSL) Reference Pages]
* [http://www.khronos.org/files/opengl-quick-reference-card.pdf OpenGL 3.3 & GLSL Quick Reference Card]

==Valgrind and fglrx==

fglrx drivers cause Valgrind to spew out a lot of false errors. You can suppress these by using the --suppressions=/path/to/file.supp flag. You must pass the full path (no use of the tilde symbol). The following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file. Keep in mind that the location of the fglrx library may need to be changed.

==Resources==

===Publications===

<ul>
<li>[http://halo.bungie.net/Inside/publications.aspx Bungie, Inc.] — creators of the Marathon, Myth, and Halo franchises.</li>
<li>[http://dice.se/publications/ DICE SE] — creators of the Battlefield franchise.</li>
<li>[http://www.guerrilla-games.com/publications/ Guerilla Games] — creators of the Killzone franchise.
Also of interest is the "Making of Killzone 2" video series, not listed on their site:
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-1?objectid=748475 Part 1]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-2?objectid=748475 Part 2]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-3?objectid=748475 Part 3]
* [http://www.ign.com/videos/2009/01/27/killzone-2-ps3-the-making-of-killzone-2-part-4?objectid=748475 Part 4]
</li>
<li>[http://www.valvesoftware.com/company/publications.html Valve Software] — creators of the Half-Life franchise.</li>
</ul>

===General Game Development===

* [http://devmaster.net/ Devmaster.net]

===OpenGL===

* [http://www.opengl.org/ Official OpenGL page]
* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages]
* [http://www.opengl.org/sdk/docs/manglsl/ OpenGL Shading Language Reference Pages]
* [http://arcsynthesis.org/gltut/ Learning Modern 3D Graphics Programming]

===Quake===

* [http://fd.fabiensanglard.net/doom3/pdfs/johnc-plan_1999.pdf John Carmack's notes from development]
* "Looking at the Quake 3 Source"
** [http://element61.blogspot.com/2005/08/looking-at-quake-3-source-part-1.html Part 1]
** [http://element61.blogspot.com/2005/08/looking-at-quake-3-source-part-2.html Part 2]
** [http://element61.blogspot.com/2005/09/looking-at-quake-3-source-part-3.html Part 3]
* [http://www.quakewiki.net/archives/code3arena/ Code3Arena]
* [http://www.modwiki.net/wiki/MD5_(file_format) MD5 file format]
* [http://tfc.duke.free.fr/coding/md5-specs-en.html Another MD5 format article]
* [http://fabiensanglard.net/quake3/index.php Quake 3 Source Code Review]
* [http://www.quake3world.com/forum/index.php Quake3World Discussion Forums]
* [http://wiki.ioquake3.org/ ioquake3 project wiki] — Primarily oriented for users, developers and server administrators.

Getting the source

2012-03-16T21:18:35Z

Fuma: /* ToroiseGIT */

==Overview==

==Installing Git==

If you already have Git installed, you can skip this step.

===Windows===

Windows users can acquire git from the [http://code.google.com/p/msysgit/ MSysGit project]. If you would prefer a graphical front-end, there is [http://code.google.com/p/tortoisegit/ TortoiseGit], but regardless MSysGit must be installed.

===Mac OS X===

Apple has included Git with Xcode since version 4. You may download Xcode from [https://developer.apple.com/xcode/ Apple's developer website].

===Linux===

====Debian & Ubuntu====

Install git using the package manager:

$ sudo apt-get install git

==Downloading the source==

The Unvanquished source code is hosted on GitHub [https://github.com/TremZ/Unvanquished here]. You can either download a snapshot of the source by clicking 'ZIP', or you can use git to clone the repository.

===Linux===

Use git on the command line:

$ git clone https://github.com/TremZ/Unvanquished.git

This will create a directory called <code>Unvanquished</code> in your home folder.

===Mac OS X===

====Command Line====

Acquiring the source code using the command line is the same as on Linux. Just open a Terminal (/Applications/Utilities/Terminal) window and clone the source code like so:

$ git clone https://github.com/TremZ/Unvanquished.git

====Xcode 4====

# Start Xcode.
# Open the Organizer window (Window → Organizer or Shift+Command ⌘+2)
# Click the "Repositories" button on the top bar.
# Click the "+" button in the lower-left corner, and choose "Checkout or Clone Repository…".
# In the rollout sheet that appears, enter <code>https://github.com/TremZ/Unvanquished.git</code> into the "Location" field, and click "Next".
# Enter "Unvanquished" into the "Name" field, ensure that the "Type" combo box is set to "Git", and click "Clone".
# You will be prompted where to save the repository. Choose a location and click "Clone".

===Windows===

====ToroiseGIT====

# Make and enter a new folder to store the source code in
# Right click the inside of the folder -> Git Clone...
# In the Url textbox enter: <code>https://github.com/TremZ/Unvanquished.git</code>
# Click ok.

====Command Line====
Open the MsysGit terminal and type:
$ git clone https://github.com/Tremz/Unvanquished.git

==Compiling==

Please see [[Compiling the source|this page]] for more information.

Getting the source

2012-03-16T21:18:16Z

Fuma: /* Downloading the source */

==Overview==

==Installing Git==

If you already have Git installed, you can skip this step.

===Windows===

Windows users can acquire git from the [http://code.google.com/p/msysgit/ MSysGit project]. If you would prefer a graphical front-end, there is [http://code.google.com/p/tortoisegit/ TortoiseGit], but regardless MSysGit must be installed.

===Mac OS X===

Apple has included Git with Xcode since version 4. You may download Xcode from [https://developer.apple.com/xcode/ Apple's developer website].

===Linux===

====Debian & Ubuntu====

Install git using the package manager:

$ sudo apt-get install git

==Downloading the source==

The Unvanquished source code is hosted on GitHub [https://github.com/TremZ/Unvanquished here]. You can either download a snapshot of the source by clicking 'ZIP', or you can use git to clone the repository.

===Linux===

Use git on the command line:

$ git clone https://github.com/TremZ/Unvanquished.git

This will create a directory called <code>Unvanquished</code> in your home folder.

===Mac OS X===

====Command Line====

Acquiring the source code using the command line is the same as on Linux. Just open a Terminal (/Applications/Utilities/Terminal) window and clone the source code like so:

$ git clone https://github.com/TremZ/Unvanquished.git

====Xcode 4====

# Start Xcode.
# Open the Organizer window (Window → Organizer or Shift+Command ⌘+2)
# Click the "Repositories" button on the top bar.
# Click the "+" button in the lower-left corner, and choose "Checkout or Clone Repository…".
# In the rollout sheet that appears, enter <code>https://github.com/TremZ/Unvanquished.git</code> into the "Location" field, and click "Next".
# Enter "Unvanquished" into the "Name" field, ensure that the "Type" combo box is set to "Git", and click "Clone".
# You will be prompted where to save the repository. Choose a location and click "Clone".

===Windows===

====ToroiseGIT====

# Make and enter a new Folder to store the source code in
# Right click the inside of the folder -> Git Clone...
# In the Url textbox enter: <code>https://github.com/TremZ/Unvanquished.git</code>
# Click ok.

====Command Line====
Open the MsysGit terminal and type:
$ git clone https://github.com/Tremz/Unvanquished.git

==Compiling==

Please see [[Compiling the source|this page]] for more information.

Compiling the source

2012-03-16T21:09:45Z

Fuma: /* Windows */

==Overview==

==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, follow the instructions on [[Getting_the_source##Mac_OS_X_2|this page]] to acquire the source code.

Next, perform the following:

# Run CMake.
# Enter the location of the source code.
# Enter the location in which you would like to build the source code. This may be the same 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.
# '''''TODO: explain which libraries will likely have to be set'''''
# Click "Generate".
# Close CMake and open Xcode.
# Open the project file created by CMake, which should be in the build directory you specified.
# Click the build button.

==Windows==

The preferred way of building Unvanquished on Windows is to use Microsoft Visual Studio.
The free Express version of the software works fine.

Steps:
# Open src/engine/Daemon.sln in Visual Studio
# In the two text boxes in the toolbar, select "Release" in the first one and Win32 or Win64 in the second one
# Use Build -> Build Solution to compile the code

==Linux==

===Debian & Ubuntu===

====Dependencies====



$ sudo apt-get install libcurl4-gnutls-dev libfreetype6-dev libglew1.5-dev \
libgmp-dev libjpeg8-dev libncurses5-dev libogg-dev libopenal-dev \
libpng12-dev libsdl1.2-dev libvorbis-dev zlib1g-dev

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

$ sudo apt-get install cmake-curses-gui

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>
$ ccmake .

Alternatively, you may want to build the engine in another directory.

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

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:

$ sudo apt-get install cmake-qt-gui

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>MYSQL_LIBRARIES</code>
* <code>MYSQL_INCLUDE_DIR</code>
* <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.

====Compiling====

$ cd <var>/path/to/uvanquished</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</var>
$ cd main
$ wget http://sourceforge.net/projects/unvanquished/files/Assets/pak0.pk3/download
$ wget http://sourceforge.net/projects/unvanquished/files/Assets/pak0.pk3/download
$ wget http://sourceforge.net/projects/unvanquished/files/Map%20Pack/maps.7z/download

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

Compiling the source

2012-03-16T21:09:25Z

Fuma: /* Windows */

==Overview==

==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, follow the instructions on [[Getting_the_source##Mac_OS_X_2|this page]] to acquire the source code.

Next, perform the following:

# Run CMake.
# Enter the location of the source code.
# Enter the location in which you would like to build the source code. This may be the same 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.
# '''''TODO: explain which libraries will likely have to be set'''''
# Click "Generate".
# Close CMake and open Xcode.
# Open the project file created by CMake, which should be in the build directory you specified.
# Click the build button.

==Windows==

The preferred way of building Unvanquished on Windows is to use Microsoft Visual Studio.
The free Express version of the software works fine.

Steps:
# 1. Open src/engine/Daemon.sln in Visual Studio
# 2. In the two text boxes in the toolbar, select "Release" in the first one and Win32 or Win64 in the second one
# 3. Use Build -> Build Solution to compile the code

==Linux==

===Debian & Ubuntu===

====Dependencies====



$ sudo apt-get install libcurl4-gnutls-dev libfreetype6-dev libglew1.5-dev \
libgmp-dev libjpeg8-dev libncurses5-dev libogg-dev libopenal-dev \
libpng12-dev libsdl1.2-dev libvorbis-dev zlib1g-dev

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

$ sudo apt-get install cmake-curses-gui

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>
$ ccmake .

Alternatively, you may want to build the engine in another directory.

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

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:

$ sudo apt-get install cmake-qt-gui

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>MYSQL_LIBRARIES</code>
* <code>MYSQL_INCLUDE_DIR</code>
* <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.

====Compiling====

$ cd <var>/path/to/uvanquished</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</var>
$ cd main
$ wget http://sourceforge.net/projects/unvanquished/files/Assets/pak0.pk3/download
$ wget http://sourceforge.net/projects/unvanquished/files/Assets/pak0.pk3/download
$ wget http://sourceforge.net/projects/unvanquished/files/Map%20Pack/maps.7z/download

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