Unvanquished - User contributions [en-gb]

Old/Technical Documentation

2015-07-17T04:37:40Z

Kangz:

{{PetProject|author=Kangz}}
== About the Dæmon engine ==

The Dæmon engine is part of the grand family of Quake engines, having started as an heavily modified Quake3. It started with the big improvements to the renderer made by XReal and ET:Xreal, then the Dæmon developers developed it further, making it the most advanced open-source Quake-derived engine.

* lineage picture

Originally it was being developed as the engine for the Unvanquished, the succesor of Tremulous, a new release of Dæmon coming out every month with the corresponding Unvanquished Alpha. Other games are currently looking at using it as their engine.

The most important [[Engine/Features|features]] are:
* A modern [[Engine/Renderer|renderer]] with shadows, skeletal models and post-processing effectsoul
* [[Engine/NaCl|NaCl]]-based [[Engine/Virtual_Machines|virtual machines]] which allows C++ in the gamelogic
* A somewhat clean C++ codebase (vs. the mess of C we inherited)

While the Quake 3 engine has originally been released under the GPLv2, we want to have Dæmon completely licensed under a 3-clause BSD which means that new files should use that license and that rewrites of subsystem should be made from scratch as much as possible;

== Getting started ==

Currently Dæmon's master [[Engine/Source_Code|source code]] is in the same repository as Unvanquished but it will move soon in the [https://github.com/DaemonDevelopers/ DæmonDevelopers] organization on Github. After [[Engine/Building|building]] the engine you will get three executables:
* daemon, the graphical client that the players use
* daemon-tty, a command line client that can be used for development and server administration
* daemonded, the server

There are not usable on their own, without a game to run on top but if you built it from, inside a game's repository you should be able to run daemon to start the engine. The engine accepts a number of command [[Engine/Flags|line flags]] to specify in which directories it will find the assets, as well as to set variables or run commands at startup.

== Architecture ==

Like Quake 3 our engine runs the gamelogic inside a [[Engine/Virtual_Machines|virtual machine]] so that by simply connecting to a server and downloading some assets, a whole different game can be played. However, because of the technology underlying them, the virtual machines run in a different process than the engine and can only communicate through IPC (InterProcess Communication) such as sockets and shared memory. This forces some architectural choice like having a command buffer for VM-engine communication, and is in stark contrast to Quake 3 in which the gamelogic was run in an interpreter in the engine process.

The client-server communication still follows the Quake 3 model of buffering entity snapshots to be played on the client side and likewise the [[Engine/Renderer|renderer]] buffers all graphics commands to process them on another core. All this buffering is explained in more detail in the [[Engine/Architecture|architecture]] page. It is to be noted that since the gamelogic is in its own process, we can kill it safely: non-fatal errors simply shut down the gamelogic and return to the main menu.

The source code is arganized as follows:
* '''CMakeList.txt''': build system main file
* '''cmake''': additional build system files
* '''external_deps''': binaries needed to compile and run the game, downloaded on the first compilation
* '''libs''': external libraries
* '''src'''
** '''common''': source files compiled both in the gamelogic and the engine
*** '''cm''': Quake 3's collision model or physics
*** '''IPC''': InterProcess Communication library
*** '''math''': our math library
** '''engine'''
*** '''audio'''
*** '''botlib''': pathfinding library for the bots
*** '''client''': other files specific to the client-side engine
*** '''framework''': utilities used by both the client-side and the server-side engine
*** '''null''': noop interfaces for a number of subsystem
*** '''qcommon''': like framework, but containing only legacy files
*** '''renderer''': the biggest part of the engine
*** '''server''': files specific to the client-side engine
*** '''sys''': system support files that haven't been moved in framwork yet
** '''shared''': support code to be used in the gamelogic only

== Development workflow ==

* When changing the engine
* When developing the gamelogic
* When changing assets

== Coding inside Daemon ==
* Code in common
** Command
** Cvar
** Filesystem
** Log
** Math
** System
* IPC / writing a new syscall

== Other ==
* References
* Nacl

Old/Technical Documentation

2015-07-17T04:36:38Z

Kangz:

{{PetProject|author=Kangz}}
== About the Dæmon engine ==

The Dæmon engine is part of the grand family of Quake engines, having started as an heavily modified Quake3. It started with the big improvements to the renderer made by XReal and ET:Xreal, then the Dæmon developers developed it further, making it the most advanced open-source Quake-derived engine.

* lineage picture

Originally it was being developed as the engine for the Unvanquished, the succesor of Tremulous, a new release of Dæmon coming out every month with the corresponding Unvanquished Alpha. Other games are currently looking at using it as their engine.

The most important [[Engine/Features|features]] are:
* A modern [[Engine/Renderer|renderer]] with shadows, skeletal models and post-processing effectsoul
* [[Engine/NaCl|NaCl]]-based [[Engine/Virtual_Machines|virtual machines]] which allows C++ in the gamelogic
* A somewhat clean C++ codebase (vs. the mess of C we inherited)

While the Quake 3 engine has originally been released under the GPLv2, we want to have Dæmon completely licensed under a 3-clause BSD which means that new files should use that license and that rewrites of subsystem should be made from scratch as much as possible;

== Getting started ==

Currently Dæmon's master [[Engine/Source_Code|source code]] is in the same repository as Unvanquished but it will move soon in the [https://github.com/DaemonDevelopers/ DæmonDevelopers] organization on Github. After [[Engine/Building|building]] the engine you will get three executables:
* daemon, the graphical client that the players use
* daemon-tty, a command line client that can be used for development and server administration
* daemonded, the server

There are not usable on their own, without a game to run on top but if you built it from, inside a game's repository you should be able to run daemon to start the engine. The engine accepts a number of command [[Engine/Flags|line flags]] to specify in which directories it will find the assets, as well as to set variables or run commands at startup.

== Architecture ==

Like Quake 3 our engine runs the gamelogic inside a [[Engine/Virtual_Machines|virtual machine]] so that by simply connecting to a server and downloading some assets, a whole different game can be played. However, because of the technology underlying them, the virtual machines run in a different process than the engine and can only communicate through IPC (InterProcess Communication) such as sockets and shared memory. This forces some architectural choice like having a command buffer for VM-engine communication, and is in stark contrast to Quake 3 in which the gamelogic was run in an interpreter in the engine process.

The client-server communication still follows the Quake 3 model of buffering entity snapshots to be played on the client side and likewise the [[Engine/Renderer|renderer]] buffers all graphics commands to process them on another core. All this buffering is explained in more detail in the [[Engine/Architecture|architecture]]page. It is to be noted that since the gamelogic is in its own process, we can kill it safely: non-fatal errors simply shut down the gamelogic and return to the main menu.

The source code is arganized as follows:
* '''CMakeList.txt''': build system main file
* '''cmake''': additional build system files
* '''external_deps''': binaries needed to compile and run the game, downloaded on the first compilation
* '''libs''': external libraries
* '''src'''
** '''common''': source files compiled both in the gamelogic and the engine
*** '''cm''': Quake 3's collision model or physics
*** '''IPC''': InterProcess Communication library
*** '''math''': our math library
** '''engine'''
*** '''audio'''
*** '''botlib''': pathfinding library for the bots
*** '''client''': other files specific to the client-side engine
*** '''framework''': utilities used by both the client-side and the server-side engine
*** '''null''': noop interfaces for a number of subsystem
*** '''qcommon''': like framework, but containing only legacy files
*** '''renderer''': the biggest part of the engine
*** '''server''': files specific to the client-side engine
*** '''sys''': system support files that haven't been moved in framwork yet
** '''shared''': support code to be used in the gamelogic only

== Development workflow ==

* When changing the engine
* When developing the gamelogic
* When changing assets

== Coding inside Daemon ==
* Code in common
** Command
** Cvar
** Filesystem
** Log
** Math
** System
* IPC / writing a new syscall

== Other ==
* References
* Nacl

Old/Technical Documentation

2015-07-17T03:21:39Z

Kangz: /* About the Dæmon engine */

{{PetProject|author=Kangz}
== About the Dæmon engine ==

The Dæmon engine is part of the grand family of Quake engines, having started as an heavily modified Quake3. It started with the big improvements to the renderer made by XReal and ET:Xreal, then the Dæmon developers developed it further, making it the most advanced open-source Quake-derived engine.

* lineage picture

Originally it was being developed as the engine for the Unvanquished, the succesor of Tremulous, a new release of Dæmon coming out every month with the corresponding Unvanquished Alpha. Other games are currently looking at using it as their engine.

The most important [[Engine/Features|features]] are:
* A modern [[Engine/Renderer|renderer]] with shadows, skeletal models and post-processing effectsoul
* [[Engine/NaCl|NaCl]]-based [[Engine/Virtual_Machines|virtual machines]] which allows C++ in the gamelogic
* A somewhat clean C++ codebase (vs. the mess of C we inherited)

While the Quake 3 engine has originally been released under the GPLv2, we want to have Dæmon completely licensed under a 3-clause BSD which means that new files should use that license and that rewrites of subsystem should be made from scratch as much as possible;

== Getting started ==

* Getting the source code bundled with unvanquished
* Building the engine (3 executables and what they are)
* Running the engine, startup flags

== Architecture ==

* The two VMs + netcode
* The renderer with the command list?
* Error handling
* Organization of the source code

== Development workflow ==

* When changing the engine
* When developing the gamelogic
* When changing assets

== Coding inside Daemon ==
* Code in common
** Command
** Cvar
** Filesystem
** Log
** Math
** System
* IPC / writing a new syscall

== Other ==
* References
* Nacl

Old/Technical Documentation

2015-07-17T03:20:41Z

Kangz: Created page with " {{PetProject|author=Kangz} == About the Dæmon engine == The Dæmon engine is part of the grand family of Quake engines, having started as a..."

{{PetProject|author=Kangz}
== About the Dæmon engine ==

The Dæmon engine is part of the grand family of Quake engines, having started as an heavily modified Quake3. It started with the big improvements to the renderer made by XReal and ET:Xreal, then the Dæmon developers developed it further, making it the most advanced open-source Quake-derived engine.

* lineage picture

It started being developed as the engine for the Unvanquished, the succesor of Tremulous, a new release of Dæmon coming out every month with the corresponding Unvanquished Alpha. Other games are currently looking at using it as their engine.

The most important [[Engine/Features|features]] are:
* A modern [[Engine/Renderer|renderer]] with shadows, skeletal models and post-processing effectsoul
* [[Engine/NaCl|NaCl]]-based [[Engine/Virtual_Machines|virtual machines]] which allows C++ in the gamelogic
* A somewhat clean C++ codebase (vs. the mess of C we inherited)

While the Quake 3 engine has originally been released under the GPLv2, we want to have Dæmon completely licensed under a 3-clause BSD which means that new files should use that license and that rewrites of subsystem should be made from scratch as much as possible;

== Getting started ==

* Getting the source code bundled with unvanquished
* Building the engine (3 executables and what they are)
* Running the engine, startup flags

== Architecture ==

* The two VMs + netcode
* The renderer with the command list?
* Error handling
* Organization of the source code

== Development workflow ==

* When changing the engine
* When developing the gamelogic
* When changing assets

== Coding inside Daemon ==
* Code in common
** Command
** Cvar
** Filesystem
** Log
** Math
** System
* IPC / writing a new syscall

== Other ==
* References
* Nacl

Technical Documentation

2015-07-17T02:31:53Z

Kangz:

{{OutOfDate}}

If you have a question that is not answered here, you can always hop on [[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.

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 are all sorts of existing tasks listed on our [https://github.com/Unvanquished/Unvanquished/issues issues reported on the bug tracker] you are free to fix. Please drop in on [[IRC]] and tell us what you're up to.

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

==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] (website down since 2013, use https://web.archive.org/web/20120930061040/http://www.modwiki.net/wiki/MD5_%28file_format%29 )
* [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.

Compiling the source

2015-02-26T14:58:09Z

Kangz: /* Windows */

==Mac OS X==

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

Regardless of what interface you may use to compile the source, you will need [http://www.cmake.org/cmake/resources/software.html CMake] to generate makefiles. You will also need to install [https://developer.apple.com/xcode/ Xcode] (making sure to choose to install the command-line utilities when prompted by the installer).

Then, you will need to acquire (and in some cases, manually compile) at a minimum the [[#Dependencies|necessary libraries]].

Once you have the source code and the libraries installed, you may actually proceed to compile the source. You have several options:
* '''Compile the source at the command line'''. This is the easiest if you would just like to compile the game to use yourself and you do not intend to work on the code.
* '''Compile the source using an IDE'''. This is preferred if you intend on developing the source.
** Xcode is Apple's flagship IDE and you should have installed to compile the source regardless of which method you use.
** [http://qt-project.org/downloads QtCreator] is cross-platform and provides real-time feedback of syntax errors, a Vim mode, as well as other features.
** [http://www.codeblocks.org/ Code::Blcoks] is also cross-platform but lacks some of the features of Xcode and QtCreator.

===Dependencies===

You only need to use one of the following methods (HomeBrew or compiling by hand). Please try and avoid mixing methods as this may produce unexpected results.

Unvanquished requires the following libraries:
* [[#JPEG|JPEG]], version 8 or higher. (Version 6 was known to have problems)
* [[#Simple_DirectMedia_Layer_.28SDL.29|Simple DirectMedia Layer]] (The binary provided by libsdl.org causes graphical corruptions. Compile from source or use homebrew/macports)
* [[#The_OpenGL_Extension_Wrangler_Library_.28GLEW.29|The OpenGL Extension Wrangler Library]]
* CuRL
* [[#The_GNU_MP_Bignum_Library_.28libgmp.29|GMP]]
* [[#WebP|WebP]] (v0.2.0 or newer)

The following libraries are optional:
* Theora
* Speex
* [[#Ogg|Ogg]]
* [[#Vorbis|Vorbis]]

====HomeBrew====
Install [http://mxcl.github.com/homebrew/ HomeBrew] and then run the following command

$ brew install nettle libjpeg curl sdl webp xvid gmp glew speex libvorbis theora

All the necessary libraries should now have been installed.

====Compiling by hand====
The following are shell scripts that download, compile, and install various libraries. This is more time consuming then other methods but might be useful if you need more control over your libraries

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

Do not use the binaries provided by libsdl.org, as these are known to cause issues with gamma and color display. Instead, compile your own:

$ curl http://www.libsdl.org/release/SDL-1.2.15.tar.gz > SDL-1.2.15.tar.gz
$ tar xvzf SDL-1.2.15.tar.gz
$ cd SDL-1.2.15
$ ./configure
$ make
$ sudo make install

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

=====WebP=====

You do not need to compile WebP by hand; Google provides binaries for Mac OS X available from their [https://code.google.com/p/webp/downloads/detail?name=libwebp-0.2.0-mac-10.5.tar.gz project page]. You will need version 0.2.0 or newer.

Once downloaded, you must still install the header files and the binary:

$ curl https://webp.googlecode.com/files/libwebp-0.2.0-mac-10.5.tar.gz > libwebp-0.2.0-mac-10.5.tar.gz
$ tar xvzf libwebp-0.2.0-mac-10.5.tar.gz
$ cd libwebp-0.2.0-mac-10.5
$ sudo cp include/webp /usr/local/include
$ sudo cp lib/libwebp.a /usr/local/lib

===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.
# Hit "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>.
## 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.
# Hit "Generate".
# You may now close CMake.

===Compiling===

====With Xcode====

<ol>
<li>Either start Xcode and open the project file (in the build directory you specified) or double-click the project file in Finder.</li>
<li>Open the project file created by CMake, which should be in the build directory you specified.</li>
<li>Change the active target to "ALL_BUILD" and click Product→Build.</li>
</ol>

====With Unix Makefiles====

<ul>
<li>Start Terminal (Applications → Utilities → Terminal).</li>
<li>Input 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 Xcode 4====

To test the game, select the "client" scheme from the combo box on the toolbar, and click the run button or press {{Hotkey|MacCommand}}{{Hotkey|R}}.

====With Unix Makefiles====

After compiling, you'll have to place the data files in the <code>main</code> directory in your build directory. [[#Acquiring the Game Files|For download instructions, see below.]]

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

{{Note|header=Important|content=
Please be aware that these instructions are very much out of date, and may not work. Also note that the dynamic library bundler does '''not''' work as intended and although you will be able to run your build on your machine, it will most likely not work on other machines. It is strongly suggested that you compile the source using Xcode.
}}

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 {{Hotkey|Ctrl}}{{Hotkey|D}} on the keyboard.

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

[[File:Bundle_dir_Mac_OS_X.png]]

'''Note''': If you compiled SDL from source, you will not see a directory titled <code>SDL.framework</code>.

==Windows==

===Visual Studio===

CMake can generate Visual Studio projects for Unvanquished.

# Add _NO_DEBUG_HEAP=1 to your environment variables otherwise performance under the debugger [http://www.massimpressionsprojects.com/dev/altdevblog/2011/07/27/the-unexpected-performance-of-debug-builds/ will be terrible]
# Run CMake with the source directory as the base directory of your source code (which should contain directories such as <code>main</code> and <code>src</code>), and the build directory as a subdirectory of the source directory named <code>build</code>.
# Open <code>build/Daemon.sln</code> in Visual Studio 2013.
# In the two text boxes in the toolbar, select "Release" or "Debug" in the first one and Win32 in the second one
# Press {{Hotkey|F5}} to build solution and run application, or just use Build → Build Solution to compile the code.

====Important Notes====

* ncurses is not supported under Visual Studio.
* If the path to your build directory is too long, the generation of a NaCl VMs will fail because a command line will be longer than what VS tools support. Put the sources closer to the root of a drive.
* Due to limitations with CMake, the startup project cannot be specified. This must be set manually to debug the client with Visual Studio:
** Right click on client and select "Set as StartUp project".
* The <code>game-nacl</code> project may fail to build if the name of your build-directory is longer than about 43 characters due to generated batch file commands that exceed 8192 characters in length.

===MinGW===

It is possible to build Unvanquished with MinGW, although the process is rather arduous compared to Visual Studio or compiling for other platforms. Currently, you will also need [http://cygwin.com/setup.exe Cygwin] to build the GMP library as well.

====Notes====

* The easiest way to acquire and install MinGW is with the graphical [http://sourceforge.net/projects/mingw/files/Installer/mingw-get-inst/ mingw-get-inst installer]. At a minimum, you will need to install the C and C++ compilers. 
* When configuring the build with CMake, you will find that you will have to set a number of libraries manually. You can find precompiled DLLs for most of the dependencies; those that are not pre-compiled can be built with the corresponding <code>USE_INTERNAL_</code> setting.
* '''The build will fail during QVM compilation if your source or build directories contain spaces.''' This is due to a bug with lcc. If your home directory contains a space, you may want to create source and build directories at the root of one of your drives (e.g., <code>C:\Unvanquished\Source</code> and <code>C:\Unvanquished\Build</code>.)

====Instructions====

The easiest way to get a build up (at the time of writing) is as follows:

{{Note|content=Although there are 64-bit binaries of most of the libraries required to build the game, these do not work with MinGW at present, so the following instructions all use the 32-bit binaries.}}

<ol>
<li>You will need to download and install some version of the DirectX SDK to compile the source. You may download the June 2010 release from [http://www.microsoft.com/en-us/download/details.aspx?id=6812 Microsoft].</li>
<li>Although there are binaries of gmp distributed with the source, they have are dependent on Visual Studio's implementations of <code>_ftol2_sse</code> and <code>_alloca_probe_16</code>. A fix may be found on [http://stackoverflow.com/questions/6753111/static-linking-with-openssl Stack Exchange], but requires that Visual Studio be installed, which defeats the purpose of attempting to use MinGW to compile the source. You can build gmp yourself:
<ol>
<li>Download and extract the latest version of the [http://gmplib.org/ GNU MP Bignum Library (GMP)]. (You will need either cygwin with tar and bz2 installed or 7-zip to extract the archive.)</li>
<li>Install the following Cygwin packages if you have not already:
* binutils
* gcc
* gcc-g++
* m4
* make
</li>
<li>As part of the GMP compilation process, a file called <code>gen-fib.c</code> generates a table of numbers in the Fibonacci sequence. The generated file does not play nicely with Cygwin or MinGW, so you must fix it. Edit <code>gen-fib.c</code>, and at around line 100, change these lines
<pre>
for (i = 0; i < fnum; i++)
{
printf (" CNST_LIMB (0x");
mpz_out_str (stdout, 16, f[i]);
printf ("), /* %d */\n", i-1);
}
printf ("};\n");
</pre>
to look like this:
<pre>
for (i = 0; i < fnum; i++)
{
printf (" CNST_LIMB (0x");
mpz_out_str (stdout, 16, f[i]);
printf (")%c /* %d */\n", (i == (fnum-1)) ? ' ' : ',', i-1);
}
printf ("};\n");
</pre>
The patch file looks like this:
<pre>
@@ -100,7 +100,7 @@
{
printf (" CNST_LIMB (0x");
mpz_out_str (stdout, 16, f[i]);
- printf ("), /* %d */\n", i-1);
+ printf (")%c /* %d */\n", (i == (fnum-1)) ? ' ' : ',', i-1);
}
printf ("};\n");
}
</pre>
</li>
<li>Compiling with MinGW does not work, so you will need to compile with Cygwin. At the prompt:
<pre>
$ ./configure --disable-static --enable-shared
$ make
</pre>
The <code>--disable-static</code> and <code>--enable-shared</code> flags configure GMP to build a DLL instead of a static library. You may optionally perform <code>make install</code>. Additional compilation instructions [http://www.cs.nyu.edu/exact/core/gmp/ are available].
If you experience difficulties with compilation and it appears that MinGW gcc is being detected by <code>configure</code> and not Cygwin gcc, you can try editing your <code>PATH</code> variable:
<pre>
$ export PATH=`echo $PATH | sed "s|/cygdrive/c/MinGW/bin:||"`
</pre>
Re-run <code>configure</code> and <code>make</code> afterwards.
</ol>
</li>
<li>Download the [http://www.libsdl.org/release/SDL-1.2.15-win32.zip latest stable version] of SDL for Windows. Extract the archive and copy <code>SDL.dll</code> from it to the root of your build directory.</li>
<li>Set the following CMake flags:
{| class="wikitable"
! Setting
! Description
! Type
! Value
|-
| <code>USE_INTERNAL_CRYPTO</code>
| Use the provided copies of crypto libraries. 
| <code>BOOL</code>
| <code>true</code>
|-
| <code>USE_INTERNAL_GLEW</code>
| Use the provided copy of GLEW.
| <code>BOOL</code>
| <code>true</code>
|-
| <code>USE_INTERNAL_JPEG</code>
| Use the provided copy of JPEG.
| <code>BOOL</code>
| <code>true</code>
|-
| <code>USE_INTERNAL_SDL</code>
| Use the provided copy of SDL.
| <code>BOOL</code>
| <code>true</code>
|-
| <code>USE_INTERNAL_SPEEX</code>
| Use the provided copy of Speex.
| <code>BOOL</code>
| <code>true</code>
|-
| <code>USE_INTERNAL_WEBP</code>
| Use the provided copy of WebP.
| <code>BOOL</code>
| <code>true</code>
|-
| <code>USE_CURSES</code>
| Enables/disables curses.
| <code>BOOL</code>
| <code>false</code>
|-
| <code>PNG_LIBRARY</code>
| Path to the PNG library DLL.
| <code>FILEPATH</code>
| <code><var>SourcePath</var>/src/libs/libpng/libs/win32/libpng.lib</code>
|-
| <code>PNG_PNG_INCLUDE_DIR</code>
| Path to the PNG library header files.
| <code>PATH</code>
| <code><var>SourcePath</var>/src/libs/libpng</code>
|-
| <code>FREETYPE_LIBRARY</code>
| Path to the compiled FreeType library.
| <code>FILEPATH</code>
| <code><var>SourcePath</var>/src/libs/freetype/lib/freetype.lib</code>
|-
| <code>FREETYPE_INCLUDE_DIR_freetype2</code>
| Path to the FreeType library header files.
| <code>PATH</code>
| <code><var>SourcePath</var>/src/libs/freetype/include/freetype2</code>
|-
| <code>FREETYPE_INCLUDE_DIR_ft2build</code>
| Path to the FreeType library file "ftbuild.h".
| <code>FILEPATH</code>
| <code><var>SourcePath</var>/src/libs/freetype/include/</code>
|-
| <code>GMP_INCLUDE_DIR</code>
| Path to the GMP library header files.
| <code>PATH</code>
| <code><var>SourcePath</var>/src/libs/gmp/include</code>
|-
| <code>GMP_LIBRARY</code>
| Path to the GMP library.
| <code>FILEPATH</code>
| <code><var>path/to/compiled/gmp/</var>.libs/cyggmp-10.dll</code>
|-
| <code>ZLIB_INCLUDE_DIR</code>
| Path to the zlib library header files.
| <code>PATH</code>
| <code><var>SourcePath</var>/src/libs/zlibwapi/include</code>
|-
| <code>ZLIB_LIBRARY</code>
| Path to the zlib library.
| <code>FILEPATH</code>
| <code><var>SourcePath</var>/src/libs/zlibwapi/lib/x32/zlib1.dll</code>
|-
| <code>CURL_LIBRARY</code>
| Path to the CURL library.
| <code>FILEPATH</code>
| <code><var>SourcePath</var>/src/libs/curl-7.21.6/lib/win32/release/libcurl.dll</code>
|-
| <code>CURL_INCLUDE_DIR</code>
| Path to the zlib library.
| <code>PATH</code>
| <code><var>SourcePath</var>/src/libs/curl-7.21.6/include/curl</code>
|-
| <code>USE_OPENAL</code>
| Enables/disables OpenAL support.
| <code>BOOL</code>
| <code>false</code>
|-
| <code>USE_CIN_THEORA</code>
| Enables/disables Theora support.
| <code>BOOL</code>
| <code>false</code>
|-
| <code>USE_CIN_XVID</code>
| Enables/disables Xvid support.
| <code>BOOL</code>
| <code>false</code>
|-
| <code>USE_CODEC_THEORA</code>
| Enables/disables Ogg support.
| <code>BOOL</code>
| <code>false</code>
|-
| <code>SDL_LIBRARY</code>
| The path to the SDL DLL.
| <code>FILEPATH</code>
| <code><var>BuildPath</var>/SDL.dll</code>
|-
| <code>SDLMAIN_LIBRARY</code>
| Enables/disables Ogg support.
| <code>FILEPATH</code>
| <code><var>SourcePath</var>/src/libs/libsdl/src/main/win32/SDL_win32_main.c</code>
|-
|}
Do note that CMake is slash-direction–agnostic; it can handle both forward- and backslashes on Windows.
If you would like to compile a debug build, change <code>CMAKE_RELEASE_TYPE</code> from <code>Release</code> to <code>Debug</code>.
</li>
<li>Open <code><var>SourcePath</var>/CMakeLists.txt</code> and edit the line
<pre>
set( OS_LIBRARIES m winmm ws2_32 psapi z )
</pre>
(around line 1040) to look like this:
<pre>
set( OS_LIBRARIES m winmm ws2_32 psapi )
</pre>
Also edit around line 1700:
<pre>
###########################
#Configure Download Script#
###########################

if( NOT MSVC )
</pre>
to look like this:
<pre>
###########################
#Configure Download Script#
###########################

if( NOT WIN32 )
</pre>
</li>
<li>Open <code><var>SourcePath</var>/src/libs/libsdl/src/main/win32/SDL_win32_main.c</code> and edit the lines:
<pre>
/* Include the SDL main definition header */
#include "SDL.h"
#include "SDL_main.h"
</pre>
to look like:
<pre>
/* Include the SDL main definition header */
#include "../../../include/SDL.h"
#include "../../../include/SDL_main.h"
</pre>
<li>Open a command prompt and <code>cd</code> to your source directory.</li>
<li>Run <code>make</code>:
<pre>
> mingw32-make
</pre>
If you would like verbose output, set the <code>VERBOSE</code> environment variable before running <code>make</code>.
<pre>
> set VERBOSE=1
</pre>
To make it easier to build the source, you can create a batch file (call it something like <code>compile.bat</code>) and place it in your build directory:
<pre>
@echo off

set RETURN=compile

:get_time
:: Thank you, Rob van der Woude:
:: (http://www.robvanderwoude.com/datetimentparse.php)
FOR /F "tokens=1,2,3 delims=:." %%A IN ("%Time%") DO (
SET /A HOURS = 100%%A %% 100
SET /A MINUTES = 100%%B %% 100
SET /A SECONDS = 100%%C %% 100
)
SET /A TICKS=( %HOURS% * 3600 ) + ( %MINUTES% * 60 ) + %SECONDS%
GOTO %RETURN%

:compile
SET START_TICKS=%TICKS%

SET VERBOSE=1
:: mingw32-make clean
mingw32-make -j4

set RETURN=finish
GOTO get_time

:finish
SET /A COMPILE_TIME=%TICKS% - %START_TICKS%
SET /A MINUTES=%COMPILE_TIME% / 60
SET /A SECONDS=%COMPILE_TIME% %% 60
ECHO.
ECHO Compilation took %MINUTES%m %SECONDS%s.
PAUSE
</pre>
</li>
<li>Once compilation finishes, you will find that the game will fail to run due to DLL dependencies. To resolve these:
<ul>
<li>You will need to move <code>INTERNAL_GLEW</code> from the <code>Release/</code> folder of the build directory to the root of the build directory.</li>
<li>You will need to place the following other DLLs in your build directory:
* freetype6.dll
* libcurl.dll
* libpng14-14.dll
* zlib1.dll
If the renderer's DLL dependencies are not met, you will be informed that the game failed to load a renderer. If you receive an error stating that the application failed to start at all, then you are likely missing some version of the Microsoft Visual C runtime redistributable.
You may find that you also need these DLLs (if you configured your build differently):
* libbz2.dll
* libogg.dll
* libtheora.dll
* libvorbis.dll
* libvorbisfile.dll
* msvcr100.dll
* msvcr100d.dll
* zlibwapi.dll
The easiest way to obtain these DLLs is by copying them from the installation directory of an [http://sourceforge.net/projects/unvanquished/files/latest/download official release] of Unvanquished.
</li>
<li>You will need to copy your compiled DLL of GMP to your build directory. It may be found in <code><var>path/to/compiled/gmp/</var>.libs/cyggmp-10.dll</code>.</li>
<li>As you compiled GMP with Cygwin, it in turn depends on <code>cygwin1.dll</code>, which may typically be found in <code>C:\cygwin\bin\</code>. Copy and paste it into your build directory.</li>
</ul>
Once you have completed these steps, you should never have to do them again.
</li>
</ol>

====Notes====

* If you would like to use curses, try using [http://sourceforge.net/projects/pdcurses/files/pdcurses PDCurses].

===QtCreator===

# Install MinGW and follow the above instructions, except select Code::Blocks as the generator.
# Start QtCreator, and select "Open File or Project…" from the File menu.
# Navigate to your source directory and open CMakeLists.txt.
# At the CMake Wizard, select the same build directory you already configured using CMake. (If you did not chose Code::Blocks as the generator, you will have to start over again, as QtCreator requires a Code::Blocks project file in order to compile the source.)
# Ensure that a generator is selected in the combo box, and click "Run CMake". If there is no generator listed, see the [[#Troubleshooting|troubleshooting]] section below.
# Click "Finish" to close the wizard.

You should now be able to compile, run, and debug the code using QtCreator.

====Troubleshooting====

If at the "Run CMake" prompt of the the CMake Wizard, select "Run CMake" and are warned that no generator was selected, and notice that there are no generators in the combo box, you will likely have to [http://doc.qt.digia.com/qtcreator-2.4/creator-tool-chains.html manually configure your toolchain]. Select "Options…" from the "Tools" menu, then navigate to "Build & Run".

At the options window,
* Go to the "Kits" tab, and mouse over the "Desktop (default)" kit under "Manual". If there were any errors in configuring this kit, they will be displayed in the tool tip. If there are problems, select the kit. You may need to manually specify the location of the MinGW debugger, for example, which is typically <code>C:\MinGW\bin\gdb.exe</code>.
* Go to the "Compilers" tab, and ensure that MinGW is present. If not, you will need to add it manually.

==Linux==

===Dependencies===


====Debian/Ubuntu====

$ sudo apt-get install g++ gcc cmake libcurl4-gnutls-dev libfreetype6-dev \
libglew-dev libgmp-dev nettle-dev zlib1g-dev libncursesw5-dev \
libsdl2-dev libopenal-dev libjpeg8-dev libpng12-dev libwebp-dev \
libogg-dev libvorbis-dev libspeexdsp-dev libtheora-dev libopusfile-dev \
libxvidcore-dev libgeoip-dev

If libsdl2-dev isn't available, you can use libsdl1.2-dev instead.

If the version of WebP supplied by your version of Debian or Ubuntu is older than v0.2.0, you will need to [https://code.google.com/p/webp/downloads/detail?name=libwebp-0.2.0.tar.gz download] and [https://developers.google.com/speed/webp/docs/compiling#unix compile it from source]. After compiling and installing with <code>sudo make install</code>, in CMake, you'll need to set <code>WEBP_INCLUDE_DIR</code> to <code>/usr/local/include/webp</code> and <code>WEBP_LIBRARY</code> to <code>/usr/local/lib/libwebp.so</code>.

'''We currently provide ready-to-use libwebp-dev, libogg-dev libopusfile-dev where needed in our [http://{{SERVERNAME}}/index.php/Download#ubuntu Debian and Ubuntu repositories], alongside .debs of the game and server.'''

Actual dev package names may vary, e.g. libgmp3-dev instead of libgmp-dev and libglew1.7-dev instead of libglew-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

====openSUSE====

$ sudo install zypper gcc gcc-c++ Mesa-libGL-devel SDL-devel libjpeg8-devel \
libpng12-devel glew-devel webp-devel ncurses-devel gmp-devel libcurl-devel \
libnettle-devel openal-soft-devel speex-devel libvorbis-devel \
libtheora-devel

The latest version of WebP must be installed manually:

$ wget https://webp.googlecode.com/files/libwebp-0.2.1.tar.gz
$ tar xvzf libwebp-0.2.1.tar.gz
$ cd libwebp-0.2.1
$ ./configure && make
$ sudo make install

You must disable curses (set <code>USE_CURSES</code> appropriately in CMake) as failing to do so will cause Unvanquished to crash on startup.

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

Optionally: to use clang (rather than the default gcc and g++ compilers) export the CC and CXX variables before running cmake:

$ export CC="clang"
$ export CXX="clang++ -stdlib=libc++ -lc++abi"

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

Once you have finished the configuration process, press {{Hotkey|C}} again, then {{Hotkey|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_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==

===Acquiring mandatory game files===

The game files are not in the Git repository, and must be downloaded separately. This may be done on the command line or from your web browser. The downloads may be found on [http://sourceforge.net/projects/unvanquished/files/Assets SourceForge.net]. If you download the files from your browser, just download the files named "pak*.pk3", and save them to the [[Running_the_game#Data_locations|data location]] for your system.

On Linux, this may be done as follows:

$ cd <var>[path to Unvanquished installation or build]</var>/main
$ for file in {{CurrentVersion|PakFiles}}; do
if [ ! -e $file ]; then
wget -O $file "http://sourceforge.net/projects/unvanquished/files/Assets/$file/download"
fi
done

On FreeBSD, using the <code>sh</code> shell:

$ cd <var>[path to Unvanquished installation or build]</var>/main
$ for file in {{CurrentVersion|PakFiles}}; do
if [ ! -e $file ]; then
fetch -r -o $file "http://sourceforge.net/projects/unvanquished/files/Assets/$file/download"
fi
done

On Mac OS X:

$ cd ~/Library/Application\ Support/Unvanquished/main
$ for file in {{CurrentVersion|PakFiles}}; do
if [ ! -e $file ]; then
curl -L "http://sourceforge.net/projects/unvanquished/files/Assets/$file/download" > $file
fi
done

Linux users may also use the <code>download-pk3.sh</code> script that is distributed with the source code, which requires that curl be installed:

$ cd <var>[path to Unvanquished source code]</var>
$ mkdir -p ~/.Unvanquished/main
$ ./download-pk3.sh ~/.unvanquished/pkg

===Downloading the map pack===

The map pack exists only for convenience; if you do not download the map pack, Unvanquished will automatically download maps as needed when you attempt to play online.

To download the map pack on Linux:

$ wget -O maps.7z "http://sourceforge.net/projects/unvanquished/files/Map%20Pack/maps.7z"; done

To download the map pack on Mac OS X:

$ curl -L "http://sourceforge.net/projects/unvanquished/files/Map%20Pack/maps.7z" > maps.7z; done

Note that you will need to unzip the map pack on either system as it is compressed with LZMA. Mac users can use the [http://wakaba.c3.cx/s/apps/unarchiver.html Unarchiver]. Uncompressing the archive on Linux is highly dependent on your distribution.

===Verifying the Files===

Download the latest [http://sourceforge.net/projects/unvanquished/files/Assets/{{CurrentVersion|MD5HashFile}} MD5 hash file] and save it to your system's [[Running_the_game#Data_directory|data location]].

On systems with the <code>md5</code> command (Mac OS X):

$ cd ~/Library/Application\ Support/Unvanquished/main
$ cat {{CurrentVersion|MD5HashFile}} | while read line; do
file="`echo "$line" | sed -E "s/^[a-fA-F0-9]+ +\*?//"`"
if [ -e "$file" ]; then
if [ `md5 -r "$file" | cut -d\ -f1` = "`echo "$line" | cut -d\ -f1`" ]
then echo "File \"$file\" appears okay."
else echo "File \"$file\" is corrupt"'!' >&2
fi; fi; done

On systems with the <code>md5sum</code> command (most Linux distributions):

$ cd <var>[[Running_the_game#Data_directory|/path/to/data/files]]</var>
$ md5sum -c {{CurrentVersion|MD5HashFile}} 2>&1 | grep -v "open or read\|file or directory"

The <code>grep</code> invocation is used to strip output complaining about missing files.

Any files that are found to be corrupt should be replaced; just download a [http://sourceforge.net/projects/unvanquished/files/Assets new copy] of the affected file(s).

==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 {{Hotkey|Enter}} to begin editing and input in the path.
# Press {{Hotkey|C}} to configure and {{Hotkey|G}} to generate the new makefiles.
# Press {{Hotkey|Q}} to quit.
# Recompile the source:<pre>$ make</pre>

===The C Compiler is not able to compile a simple test program===

When attempting to generate a solution for Xcode CMake fails with the following error
-- Check for working C compiler using: Xcode -- broken
CMake Error at /Applications/CMake 2.8-8.app/Contents/share/cmake-2.8/Modules/CMakeTestCCompiler.cmake:52 (MESSAGE):
The C compiler "/usr/bin/gcc" is not able to compile a simple test program.

It fails with the following output:

Change Dir: /Users/danielmaloney/Documents/Unvanquished/build-xcode/CMakeFiles/CMakeTmp

Run Build Command:/Applications/CMake\ 2.8-8.app/Contents/bin/cmakexbuild
-project CMAKE_TRY_COMPILE.xcodeproj build -target
cmTryCompileExec1400153232 -configuration Debug

Error: No developer directory found at /Developer. Run
/usr/bin/xcode-select to update the developer directory path.

CMake will not be able to correctly generate this project.
Call Stack (most recent call first):
CMakeLists.txt:19 (project)

This is due to Xcode 4.3 having a different directory structure to previous versions. Simply running the following command will correct this error:
sudo /usr/bin/xcode-select -switch /Applications/Xcode.app/Contents/Developer/

GSoC idea list

2015-02-17T01:52:02Z

Kangz: Created page with "= Note to students = This is a curated list of ideas suggested by regular developers. They vary in difficulty but are all doable during the summer. Of course feel free to add..."

= Note to students =

This is a curated list of ideas suggested by regular developers. They vary in difficulty but are all doable during the summer. Of course feel free to add your own ideas to the list, respecting the current format (leave Mentor empty). You can also drop by the IRC channel to discuss your ideas, also note that you can get involved in gameplay too!

= Engine =

== Sound shaders ==

* '''Brief explanation:''' Our engine supports only sounds, with no information attached and the little sound effects we have need to be handled in a case by case by the gamelogic. Sound shaders would be sets of parameters associated to a sound file that would allow things like: randomizing samples, changing the attenuation model, looping, sound category, ...
* '''Expected results:''' Sound shaders are implemented and used in a few maps to enrich the audio environment.
* '''Prerequisite knowledge:''' C++.
* '''Mentor:''' Corentin "kangz" Wallez

== Use bullet for physics ==

* '''Brief explanation:''' The Quake3 physics code we use is very limited in both that it only handles collision with the world and supports mostly axis-aligned boxes. Using bullet would overcome this limitations and open the way for more advaned features such as inverse kinematics, ragdolls and more accurate physics simulation.
* '''Expected results:''' All the physics call go through bullet instead of the former physics system, while keeping mostly the same physics.
* '''Prerequisite knowledge:''' C++, vector math, game physics library a big plus.
* '''Mentor:''' Corentin "kangz" Wallez

== Breakpad integration ==

* '''Brief explanation:''' We want to make it easy for users to submit useful crash reports. Google Breakpad is a good solution. In the future, we can even discuss an option to automatically send these to us (with the user's permission) and create an issue on github.
* '''Expected results:''' At least on Windows, a crash of the engine produces a dump that contains useful debug info. Better, the crash handler asks the user if they want to upload it to our servers.
* '''Prerequisite knowledge:''' C++, will require access to a windows machine for testing.
* '''Mentor:''' Corentin "kangz" Wallez (Amanieu d'Antras)

== Renderer support for GL ES 3 ==

* '''Brief explanation:''' Our renderer relies on GL 2.1 + extension or GL 3, the goal is to add support for GL ES 3, potentially removing GL 2.1 support. This would allow us to port the on platforms without Desktop OpenGL support such as the Web and mobile platforms.
* '''Expected results:''' The game engine can run without linking to libGL, or better is shown running on the web / mobile.
* '''Prerequisite knowledge:''' C++, OpenGL.
* '''Mentor:''' Corentin "kangz" Wallez

==Add debug draw capabilities ==

* '''Brief explanation:''' Printf debugging is nice but sometimes it is easier to visualize things than to read them, especially for 3D. We want to add draw debugging to help debugging the gamelogic or subsystems that work with 3D objects, the goal is to have a super simple interface to draw basic geometry, in all parts of the engine and gamelogic.
* '''Expected results:''' Basic shapes (spheres, boxes, arrows) and text can be drawn in the 3d world with control for color, depth test and wireframe mode.
* '''Prerequisite knowledge:''' C++, vector math, OpenGL a plus.
* '''Mentor:''' Corentin "kangz" Wallez

== Input thread / Splashscreen ==

* '''Brief explanation:''' It'd be nice to have a splash screen while the game starts (6 sec on my SSD with hot OS cache). Also we will want inputs to be processed in parallel of the game to reduce latency and enable neat tricks. The two are linked since with SDL all the windowing function must be done in the main thread, including getting new events.
* '''Expected results:''' The splashscreen and input thread are implemented.
* '''Prerequisite knowledge:''' C++, some multithreading.
* '''Mentor:''' Corentin "kangz" Wallez

= Updater =

== Add news support ==

* '''Brief Explanation:''' Every player will see the updater and this gives us an oppurtunity to engage players that wouldn't otherwise be part of the "community". The goal is to fetch news from the site and display it in a pleasing manner
* '''Expected Results:''' Implement both the frontend of this in the updater and a simple backend where news are published.
* '''Prerequisite knowledge:''' QT, C++
* '''Mentor:''' Harsh "`Ishq" Modi

== In game integration ==

* '''Brief Explanation:'''We need to be able to launch the updater frmo the game when an update is found, in a cross platform way otherwise we would be keeping the update manual as it is currently which defeats the purpose of the updater.
* '''Expected Results:''' Message should show up ingame telling player to update. Clicking on message should launch updater to update the game.
* '''Prerequisite knowledge:''' C++
* '''Mentor:''' Harsh "`Ishq" Modi

Coding

2015-02-17T01:23:08Z

Kangz:

=Getting Started=
Introduction: [[Technical Documentation]]

TODO: Rough map of how the engine is divided code-wise, so people know exactly where to look for the things they want to do

== Game ==
* [[Getting the source]]
* [[Compiling the source]]
* [[Using Unvanquished from git]]
* [[Development environments]]

== Source code ==

Game:
* [https://github.com/Unvanquished/Unvanquished Game/engine source] ([https://github.com/Unvanquished/Unvanquished/issues bug tracker])

Sub-projects:
* [https://github.com/Unvanquished/Osavul Osavul server browser source] ([https://github.com/Unvanquished/Osavul/issues bug tracker])
* [https://github.com/Unvanquished/unvanquished-master Master server source] ([https://github.com/Unvanquished/unvanquished-master/issues bug tracker])
* [[Tools/Chameleon|Chameleon]] [https://github.com/Unvanquished/Chameleon source]
* [[Tools/Archipelago|Archipelago]] [https://github.com/velociostrich/remapper source] ([https://github.com/velociostrich/remapper/issues bug tracker])

Related/used projects:
* [https://github.com/harmonise/BitRock Installer source] ([https://github.com/harmonise/BitRock/issues bug tracker])

=Documentation=

* [[Engine features]]
** [[Feature Proposals]]
* [[Renderer Status]]
* [[UI Implementation]]
* [[GSoC idea list]]
* [[List future ideas etherpad]]

=Contributing=

* [[Coding convention]]
* [[Contributing/Code|Contributing code]]
* [[Contributor Quickies]]
* [[Programming Task List]]

List future ideas etherpad

2015-02-16T22:47:35Z

Kangz: Created page with "http://etherpad.wikimedia.org/p/Unv-GSoC http://etherpad.wikimedia.org/p/Unv-resources https://etherpad.wikimedia.org/p/Unv_netcode https://etherpad.wikimedia.org/p/Unv_gam..."

http://etherpad.wikimedia.org/p/Unv-GSoC

http://etherpad.wikimedia.org/p/Unv-resources

https://etherpad.wikimedia.org/p/Unv_netcode

https://etherpad.wikimedia.org/p/Unv_gamelogic_upgrade

https://etherpad.wikimedia.org/p/Unv_rendering

https://etherpad.wikimedia.org/p/Unv_math

Coding

2015-02-16T22:46:05Z

Kangz:

=Getting Started=
Introduction: [[Technical Documentation]]

TODO: Rough map of how the engine is divided code-wise, so people know exactly where to look for the things they want to do

== Game ==
* [[Getting the source]]
* [[Compiling the source]]
* [[Using Unvanquished from git]]
* [[Development environments]]

== Source code ==

Game:
* [https://github.com/Unvanquished/Unvanquished Game/engine source] ([https://github.com/Unvanquished/Unvanquished/issues bug tracker])

Sub-projects:
* [https://github.com/Unvanquished/Osavul Osavul server browser source] ([https://github.com/Unvanquished/Osavul/issues bug tracker])
* [https://github.com/Unvanquished/unvanquished-master Master server source] ([https://github.com/Unvanquished/unvanquished-master/issues bug tracker])
* [[Tools/Chameleon|Chameleon]] [https://github.com/Unvanquished/Chameleon source]
* [[Tools/Archipelago|Archipelago]] [https://github.com/velociostrich/remapper source] ([https://github.com/velociostrich/remapper/issues bug tracker])

Related/used projects:
* [https://github.com/harmonise/BitRock Installer source] ([https://github.com/harmonise/BitRock/issues bug tracker])

=Documentation=

* [[Engine features]]
** [[Feature Proposals]]
* [[Renderer Status]]
* [[UI Implementation]]
* [[List future ideas etherpad]]

=Contributing=

* [[Coding convention]]
* [[Contributing/Code|Contributing code]]
* [[Contributor Quickies]]
* [[Programming Task List]]

Cvar Changes

2015-01-20T17:54:24Z

Kangz:

{| class="wikitable"
! New Cvar !! Old Cvar
|-
| audio.al.availableCaptureDevices || s_alAvailableInputDevices
|-
| audio.al.availableDevices || s_alAvailableDevices
|-
| audio.al.captureDevice || s_alInputDevice
|-
| audio.al.checkAllCalls || N/A
|-
| audio.al.device || s_alDevice
|-
| audio.doppler || s_doppler
|-
| audio.dopplerExaggeration || s_alDopplerFactor
|-
| audio.muteWhenMinimized || s_muteWhenMinimized
|-
| audio.muteWhenUnfocused || s_muteWhenUnfocused
|-
| audio.reverb || N/A
|-
| audio.reverbIntensity || N/A
|-
| audio.volume.effects || N/A
|-
| audio.volume.master || s_volume
|-
| audio.volume.music || s_musicvolume
|-
| common.framerate.fixed || com_fixedtime
|-
| common.framerate.max || com_maxfps
|-
| common.framerate.maxMinimized || com_maxfpsMinimized
|-
| common.framerate.maxUnfocused || com_maxfpsUnfocused
|-
| common.ignoreCrash || com_ignorecrash
|-
| common.pipefile || com_pipefile
|-
| common.showTraceStats || com_showtrace
|-
| common.watchdogCmd || com_watchdog_cmd
|-
| common.watchdogTime || com_watchdog
|-
| logs.logFile.active || N/A
|-
| logs.logFile.filename || com_logfile
|-
| logs.logFile.forceFlush || N/A
|-
| logs.logFile.overwrite || N/A
|-
| logs.logLevel.audio || N/A
|-
| logs.logLevel.common.commands || N/A
|-
| server.lanOnly || dedicated
|-
| vm.game.type || N/A
|}

Cvar Changes

2015-01-20T17:54:01Z

Kangz:

{| class="wikitable"
! New Cvar !! Old Cvar
|-
| audio.al.availableCaptureDevices || s_alAvailableInputDevices
|-
| audio.al.availableDevices || s_alAvailableDevices
|-
| audio.al.captureDevice || s_alInputDevice
|-
| audio.al.checkAllCalls || N/A
|-
| audio.al.device || s_alDevice
|-
| audio.doppler || s_doppler
|-
| audio.dopplerExaggeration || s_alDopplerFactor
|-
| audio.muteWhenMinimized || s_muteWhenMinimized
|-
| audio.muteWhenUnfocused || s_muteWhenUnfocused
|-
| audio.reverb || N/A
|-
| audio.reverbIntensity || N/A
|-
| audio.volume.effects || N/A
|-
| audio.volume.master || s_volume
|-
| audio.volume.music || s_musicvolume
|-
| common.framerate.fixed || com_fixedtime
|-
| common.framerate.max || com_maxfps
|-
| common.framerate.maxMinimized || com_maxfpsMinimized
|-
| common.framerate.maxUnfocused || com_maxfpsUnfocused
|-
| common.ignoreCrash || com_ignorecrash
|-
| common.pipefile || com_pipefile
|-
| common.showTraceStats || com_showtrace
|-
| common.watchdogCmd || com_watchdog_cmd
|-
| common.watchdogTime || com_watchdog
|-
| logs.logFile.active || N/A
|-
| logs.logFile.filename || com_logfile
|-
| logs.logFile.forceFlush || N/A
|-
| logs.logFile.overwrite || N/A
|-
| logs.logLevel.audio || N/A
|-
| logs.logLevel.common.commands || N/A
|-
| vm.game.type || N/A
|-
| server.lanOnly || dedicated
|}

Mentored Coding Project

2014-07-19T01:58:36Z

Kangz:

To help new coders get acquainted with our code we have some mentored coding projects. A mentored project should be:
* interesting like a new feature or some visible change
* approchable, not requiring knowledge of arcane part of the code or crazy templating skills (not everybody is Amanieu)
* mentored by a more experienced developer with a precise knowledge of that area of the code and an idea of the design of the project

[https://github.com/Unvanquished/Unvanquished/issues?labels=D-Mentored&page=1&state=open See the list of mentored projects!]

= Creating mentored projects =

Add the task on github with the D-mentored tag. At the bottom you can put a block like the following:
* Mentor: Kangz (gimhael, Fuma?)
* Knowledge: Renderer, OpenGL, C++ hacks to make the API fluid
* Difficulty: 5 (without visualization) 8 (with visualization)

= Difficulty scale of projects =

The difficulty field of the issue for the project should map approximately on the following scale:
* '''1: limited project''' that doesn't require knowledge of code and stays in a single module
** Nicify prints
** Small tweaks (such as adding interpolation in the gamelogic)
** Adding a cvar for a currently constant parameter
* '''4: self-contained project''' that may require easy interaction with other modules and some knowledge of the code
** Rewriting sound codecs
** Adding the first implementation of the minimap
** New hud element
* '''7: large project''' because of the amount/complexity of the code to produce, modules impacted, architectural implications
** adding IQM
** Implementing a new alien / weapon / building
** Rewriting the command system
* '''10: big changes''', often architectural. Seriously, before doing one of these talk with the rest of the team first
** making the VMs run in NaCl
** librocket
** Bullet

Mentored Coding Project

2014-07-19T01:57:37Z

Kangz: Created page with "To help new coders get acquainted with our code we have some mentored coding projects. A mentored project should be: * interesting like a new feature or some visible change * ..."

To help new coders get acquainted with our code we have some mentored coding projects. A mentored project should be:
* interesting like a new feature or some visible change
* approchable, not requiring knowledge of arcane part of the code or crazy templating skills (not everybody is Amanieu)
* mentored by a more experienced developer with a precise knowledge of that area of the code and an idea of the design of the project

= Creating mentored projects =

Add the task on github with the D-mentored tag. At the bottom you can put a block like the following:
* Mentor: Kangz (gimhael, Fuma?)
* Knowledge: Renderer, OpenGL, C++ hacks to make the API fluid
* Difficulty: 5 (without visualization) 8 (with visualization)

= Difficulty scale of projects =

The difficulty field of the issue for the project should map approximately on the following scale:
* '''1: limited project''' that doesn't require knowledge of code and stays in a single module
** Nicify prints
** Small tweaks (such as adding interpolation in the gamelogic)
** Adding a cvar for a currently constant parameter
* '''4: self-contained project''' that may require easy interaction with other modules and some knowledge of the code
** Rewriting sound codecs
** Adding the first implementation of the minimap
** New hud element
* '''7: large project''' because of the amount/complexity of the code to produce, modules impacted, architectural implications
** adding IQM
** Implementing a new alien / weapon / building
** Rewriting the command system
* '''10: big changes''', often architectural. Seriously, before doing one of these talk with the rest of the team first
** making the VMs run in NaCl
** librocket
** Bullet

Filesystem

2014-07-04T01:35:14Z

Kangz: answer some of Veyrdite's questions

Unvanquished stores its resources (maps, sounds, textures, models etc) in ''packages''. To be able to use your own resources in the game you must put them in a package.

Note: The Unvanquished filesystem rules differ from Tremulous and Quake.

= Overview =
A package is simply a zip-file or a folder containing resources. When a package is loaded its contents are extracted into a virtual filesystem (analogous to a hidden folder). If two packages have the same file, the file that was first extracted always wins out -- files cannot be overwritten once they are in the filesystem (this differs greatly to the traditional quake behavior).

The game only loads packages as it needs them:
* Main ''unvanquished'' package (containing base game resources) is always loaded first.
* Map packages as they are necessary
* Any packages that the above say they depend on (eg texture-packs)
Other packages can be forced to load using fs_extrapaks (detailed below).

Every package has a version number. When a package is loaded (generally) only the latest version is used. For example:
awesometextures_2016-04-25.pk3dir
In this case an enterprising author made their package version an ISO date (YYYY-MM-DD) to ensure that the latest version always has the 'largest' version number. There are [[Packaging Version Guidelines|recommended versioning guidelines]] that go into more detail.

There are two ways packages can be stored: as pk3s or pk3dirs. Packages ending in .pk3dir are plain folders whilst .pk3's are zip-compressed files. Generally it's easier to work with a pk3dir folder and then make a compressed copy only when needed to send over the web.

== Locations ==

Packages can be stored in the 'pkg' folder found in two places: the game installation path (fs_basepath) or the user's own personal path (fs_homepath).

{{Game Locations }}

== Filesystem priority ==
Once a file is in the filesystem, nothing can change it or replace it. If two packages have the same file then the first one to be loaded becomes dominant. The moment a package is loaded, if it contains a DEPS file, its dependencies are loaded recursively in the order of the DEPS file.

Packages are loaded from:
# fs_extrapaks if set: each pak in the space-separated values is loaded starting from the left.
# main unvanquished package hardcoded to be "unvanquished"
# map, as needed.

Dependencies are loaded immediately after their parent package, in the order specified in the DEPS file {{Verify}}

Whole-game modifications can still use the main unvanquished package by listing it as one of their dependencies. Otherwise fs_extrapaks can just be used.

= Packaging Details =
== Naming ==
Packages have three parts to their filename:
* the package basename (eg map-nano)
* the version (eg 2)
* the extension (eg .pk3)
In this case our filename would be ''map-nano_2.pk3''

Rules:
* Underscores must be used to separate the name from the version, but may not be used anywhere else
* Authors intending to release their work should follow the [[Packaging Version Guidelines]]

Sometimes a fourth section (a [https://en.wikipedia.org/wiki/checksum checksum]) is included when auto-downloading maps. This should never be added manually.

== Types ==
* '''.pk3dir''' is for folders
* '''.pk3''' is for zip-compressed packages

To convert from a pk3dir to a pk3:
# Compress the ''contents'' of a pk3dir (not the folder itself){{Verify}} into a zip-file
# Rename this zip file so that it ends with .pk3

= Filesystem layout =
Every package is 'extracted' into the same root folder in the filesystem.

It is recommended you follow the traditional folder-structure for your packages. When there is a chance files from another package may have similiar names, you should make a subfolder with your packages name to avoid a clash. Examples of this are below.

== Recommended folder structure ==
{| class="wikitable"
|-
! Folder
! Description and notes
! Example
|-
| /about
| Info and licensing about your package.
| /about/map-parpax.txt
|-
| /textures
| .crn texture files
| /textures/parpax_evillair/
|-
| /sound
| Sound files.
| /sound/parpax
|-
| /scripts
| .shader, .arena, .particle
| /scripts/parpax.arena
|-
| /minimaps
|
|
/minimaps/parpax_upper.png
/minimaps/parpax_lower.png
/minimaps/parpax.minimap
|-
| /map
| .map .bsp .navMesh (for bots)
| /map/parpax.bsp
|-
| /levelshots
| "Loading screen" picture of a map level
| /levelshots/parpax.jpg
|-
| /gfx
| ???
| /gfx/parpax/
|-
| /DEPS (file)
| Depedencies file. See next section.
| /DEPS
|-
|}

== DEPS file ==
A DEPS file in the root of a package tells the game what dependencies are required for this package. Dependant packages are loaded after the current package, so if any files clash then the dependencies 'lose out'.

Example contents of a DEPS file (from map-parpax_d03a.pk3):
tex-common
tex-ex
tex-exm
tex-pk01
tex-pk02
tex-space
tex-trak5

= Guides =

== Creating your own package ==
Find your user's package directory
[[File:Dir homepkg.png]]

Create a pk3dir folder
[[File:Dir_homepkg_newfolder.png]]

Place inside the files you want to use. Make sure you follow the filesystem organisation guidelines, or [[User:Kangz|kangz]] will eat you.
[[File:Dir inpackage.png]]

If your package is a map, you can ''/devmap mapname'' in the [[console]] to load it. Otherwise you may want to force it to be loaded with ''fs_extrapacks''. See [[Running_the_game#Advanced_options]] for more details.

$ unvanquished +set fs_extrapaks tutorialexample

== Using the latest resources from git ==
See [[Using Unvanquished from git]]

Technical Documentation

2014-06-28T00:29:17Z

Kangz:

If you have a question that is not answered here, you can always hop on [[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>bots</code> — 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] (website down since 2013, use https://web.archive.org/web/20120930061040/http://www.modwiki.net/wiki/MD5_%28file_format%29 )
* [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

2014-06-28T00:25:22Z

Kangz:

If you have a question that is not answered here, you can always hop on [[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>bots</code> — bot code, using behavior trees.
* <code>engine-upgrade</code> — Work to rewrite the engine in C++ for better maintanability.
* <code>nacl</code> — Conversion from QVMs to NaCl sandbox (will be PNaCl at some point)

==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] (website down since 2013, use https://web.archive.org/web/20120930061040/http://www.modwiki.net/wiki/MD5_%28file_format%29 )
* [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.

Wiki project resources

2014-06-28T00:22:50Z

Kangz:

Please '''Be Bold'''! No-one owns the pages here: go for it! https://en.wikipedia.org/wiki/Wikipedia:Be_bold

=Current Tasks=
Join in!

* Get [[Entities]] up to date and all of its links fixed
* Document cvar/cmd changes as a result of the engine-upgrade merge

=Resources=
== Useful Pages ==
Note: keep these as subheadings on the front page to make navigation quicker

*[[Wiki_Editing_Guidelines|Wiki editing guidelines]]
** General rules
** Links to extra help for editing wikis

*[[:Category:OutOfDate]]
** Lists pages marked with the <nowiki>{{OutOfDate}}</nowiki> [[Template:OutOfDate|template]]
** Please help reduce this list by fixing pages!

== Wiki templates you may want to use ==
These templates have to do with the wiki's content, not the game itself. They are here to make the job of being a human, whether an editor or just a reader, easier.

To use these: type or copy the whole <nowiki>{{Template In Brackets}}</nowiki> into the text of a page while editing it.

=== Whole Page Marking ===
Put these at the top of pages to mark them.

* [[Template:OutOfDate|Out of Date]] — for marking pages that need help
** <nowiki>{{OutOfDate}}</nowiki>

* [[Template:PetProject|Pet Project]] — for mega pages actively being developed
** <nowiki>{{PetProject|author=YourName}}</nowiki>

* [[Template:Deprecated|Deprecated]] — for pages that have been merged or superseded, and will eventually get binned
** <nowiki>{{Deprecated|newpage=The Replacement Page}}</nowiki>
** Ordinary emailconfirmed users can't delete pages. Use this to show you have made the effort & the admins will follow through by looking at [[:Category:Deprecated]]
** Please only mark pages with this ''when you are finished!''
** This is for merging multiple pages into one, not moving a ''single'' page. You can do that already once emailconfirmed.

* [[Template:Unknown|Unknown]] — for pages that make no sense, seem temporary or possibly unrelated to the game
** <nowiki>{{Unknown}}</nowiki>
** Pages marked with this will eventually get deleted

=== Inline Page Usage ===
Use these wherever and however you want.

* [[Template:Note|Note]] — big NOTE boxes superimposed on page
** <nowiki>{{Note | content=Read the rest of the next paragraph before attempting this, else you may get stuck }}</nowiki>

* [[Template:Verify|Verify]] — request other wiki editors to confirm whether something is true or not
** <nowiki>Unvanquished is an engine based on half-life's golden-src {{Verify}}</nowiki>

* [[Template:Rehost|Rehost]] — request for an external page to be copied onto the wiki
** <nowiki>[https://yelloweyedgoats.com/kharnov/pictures_of_kharnov Gameplay Guide] {{Rehost}}</nowiki>
** Read the licensing documentation on the [[Template:Rehost|rehost]] page before attempting to copy marked links

=Staying logged in=
The wiki's login session times out quickly. Simply open up the main site's login page (link in the upper right corner of this wiki) to inherit the 'logged-in' status from the main site (which lasts much longer): you don't actually have to fill in the login information again.

=Contacting the Admins=
If you are having issues on this wiki or want to contact an admin for any other reason ''to do with the wiki'', start with [[User:Veyrdite]]. For all other issues and questions: please use the [[IRC]] and [http://www.unvanquished.net/forum forums].

Use either his:
* [[User_talk:Veyrdite|talk page]] (public), or
* Email (private, if it needs to be) {{Verify}}
** Log yourself into the wiki
** Navigate to [[User:Veyrdite]]
** Look for 'Email this user' in the 'Tools' section of the sidebar on the left

User:Kangz

2014-06-18T20:35:47Z

Kangz:

Hey there!

I played and loved Tremulous during 5 years, with the (CY) and Welcomed clans. I'm a french student in computer science at the École polytechnique in France and doing code for Unvanquished.

Things that I did or that I am currently doing:
* Config files
* [[Minimap]]
* Discovering the GL3 renderer
* FXAA
* Upgrading the engine
** Redid Commands
** Redid Cvars
** Redid Logs
** Redid the Audio (check out the [[Tutorials/Reverberation|Reverberation]])
** Moving from QVM to PNaCl
** Other misc stuff

I also play with the assets config files as my artistic ability is limited to creating crappy procedural textures.

I'm always on [[IRC]] (unless my server as a problem) and would love to speak with you!

Engine

2014-06-18T17:29:09Z

Kangz: Add links to relevant blog posts

Unvanquished development uses the 'daemon' engine to power unvanquished, an ever-improving engine with a long list of modern features (see below).

=Engine History=
Daemon can trace its lineage all the way back to Quake 3, integrating the various features and improvements from quite a few engines before it. The aim of Unvanquished Development is to make Daemon the most modern and best available quake-derived FOSS engine.

[[File:Engine_history.svg|thumb|center|700px|The lineage of the Daemon engine.]]

=Engine Features=
==Gameplay==

* [[Navigation Meshes|Navigation-mesh]] based bot AI configured with behavior trees
* [[Voice say system]]
* Support for multiple [[Map_layouts|build layouts]] per map

==Rendering==

* Modern GL3 capable renderer
* Improved Quake 3 shader system:
** Procedural vertex deformation
** Alpha mapping
** Specular mapping (color and intensity)
** Glow mapping
** Bump (heightmap), normal, and parallax mapping
* Many special effects:
** Motion blur
** Rim lighting
** Bloom
** Heat haze
* Outline fonts
* Procedural animation blending

==Networking==

* In-game IRC client
* VoIP support
* Remote administration support

==Miscellaneous==

* Localization support
* Curses-based console
* Custom <code>unv://</code> protocol to allow starting the game from a web browser or with an internet link

=Supported Asset Formats=
See the links on the [[Main Page]] under the "Artists" section for guides on how to export and package assets into these formats.

==Image Formats==
See the [[Texture creation]] page.

*DDS (soon to be standard)
*JPEG
*WebP
*PNG
*TGA

==Model Formats==
See the [[Modeling]] and [[Exporting Models]] pages.

* IQM (recommended)
* MD3 (vertex-based)
* MD5 (bone-based)

==Map Formats==
See the [[Mapping]] page.

* quake 3 style BSP

==Engine related blog posts==
Actually a "TODO: move doc to the wiki"
* [https://www.unvanquished.net/news/75-upgrading-our-15-year-old-engine Upgrading our 15-year-old engine]
* [https://www.unvanquished.net/news/8-news/109-first-engine-upgrade-merge Merge of the first batch of engine-upgrade changes]
* [https://www.unvanquished.net/news/115-big-changes-to-the-filesystem Big changes to the Filesystem]
* [https://www.unvanquished.net/news/119-moving-the-server-side-gamelogic-to-pnacl Moving the server-side gamelogic to PNaCl]

Feature proposals

2014-06-18T17:20:06Z

Kangz: IQM and Minimap are implemented

Please use this page '''in concert''' with the [http://unvanquished.net/ideas/ idea tracker]. While the IdeaTorrent is excellent for discussing the scope of new features, it is not good for describing implementation details.

This is a page to list and elaborate on engine features to implement in the future. As with the [[Game_design_proposals|gameplay proposals]] page, it is not the place to argue or otherwise discuss the validity or merit of these ideas; just to list them and build upon their description. Do not delete any idea for any reason, spam and trolling excepted (but if an idea has been rejected, mark it as deleted and add text describing why). If you would like to discuss any proposed feature or idea, do so in the associated talk page for this page.

==Proposals==

* {{Subpage|Dual-Quaternion Skinning}}
* {{Subpage|Game Code Abstraction}}
* {{Subpage|Gameplay Configuration GUI}}
* {{Subpage|Improved Construction Animations}}
* {{Subpage|Improved Terrain}}
* {{Subpage|Inverse Kinematics}}
* {{Subpage|Map Scripting Support}}
* {{Subpage|Ragdoll Death Animations}}

==Implemented==
* {{Subpage|IQM Format Support}}
* {{Subpage|Minimap}}

==Legacy Wiki Pages for Design==
* [[Singleplayer Brainstorming]]
* [[Game design proposals]]

Engine

2014-04-30T01:50:00Z

Kangz: Remove PSK and PSA

Unvanquished development uses the 'daemon' engine to power unvanquished, an ever-improving engine with a long list of modern features (see below).

=Engine History=
Daemon can trace its lineage all the way back to Quake 3, integrating the various features and improvements from quite a few engines before it. The aim of Unvanquished Development is to make Daemon the most modern and best available quake-derived FOSS engine.

[[File:Engine_history.svg|thumb|center|700px|The lineage of the Daemon engine.]]

=Engine Features=
==Gameplay==

* [[Navigation Meshes|Navigation-mesh]] based bot AI configured with behavior trees
* [[Voice say system]]
* Support for multiple [[Map_layouts|build layouts]] per map

==Rendering==

* Modern GL3 capable renderer
* [[Stereoscopic rendering|Stereoscopic (3d) rendering]]
* Improved Quake 3 shader system:
** Procedural vertex deformation
** Alpha mapping
** Specular mapping (color and intensity)
** Glow mapping
** Bump (heightmap), normal, and parallax mapping
* Many special effects:
** Motion blur
** Rim lighting
** Bloom
** Heat haze
* Outline fonts
* Procedural animation blending

==Networking==

* In-game IRC client
* VoIP support
* Remote administration support

==Miscellaneous==

* Localization support
* Curses-based console
* Custom <code>unv://</code> protocol to allow starting the game from a web browser or with an internet link

=Supported Asset Formats=
See the links on the [[Main Page]] under the "Artists" section for guides on how to export and package assets into these formats.

==Image Formats==
See the [[Texture creation]] page.

*DDS (soon to be standard)
*JPEG
*WebP
*PNG
*TGA

==Model Formats==
See the [[Modeling]] and [[Exporting Models]] pages.

* IQM (recommended)
* MD3 (vertex-based)
* MD5 (bone-based)

==Map Formats==
See the [[Mapping]] page.

* quake 3 style BSP

Tutorials/Reverberation

2014-03-05T10:49:40Z

Kangz: Explain briefly how to see a list of reverb presets

== What it is ==

Reverberation is the effect of a sound lasting after it has been produced because of its the mutiples echos in the environment. It can give great audio clues as to what environment you are in: you would easily distinguish sounds in a regular room from sounds in a hangar from sounds in outdoor based on the reverberation. [http://en.wikipedia.org/wiki/Reverberation Wikipedia] has some examples of reverberation.

Dæmon supports reverberation effects, which you can try using the ''/testReverb'' command (use tab completion to see the list of presets), it can be used in maps to give audio clues of the size of rooms and the material of their walls. However even if reverberation effects sound really cool, you should be subtle when using it: in real life you barely notice these effects unless you are in churches or hangars.

== Mapping reverberation ==

=== Global reverberation ===

Once you have found a reverberation effect you like with ''/testReverb'' you can apply it on the whole map by setting the following keys on the worldspawn.

* '''reverbEffect <presetname>''': with <presetname> the name of the effect to apply globally
* '''reverbIntensity <number>''': with <number> between 0 and 2 the intensity of the effect. The default is 1.0 so you can lower the effect or
crank it up to your liking (but it should mainly be used to lower the effect).

=== Localised reverberation ===

You can also define reverberation effects per area by placing func_static entities and adding the following keys to it:

* '''reverbEffect <presetname>''': like for the worldspawn
* '''reverbIntensity <number>''': like for the worldspawn
* '''reverbDistance <distance>''': a distance in qunits representing the approximate size of the room in which to use the effect. Between such func_statics, effects will be blended, potentially with the global reverb effect.

Cvar Changes

2014-01-20T22:12:21Z

Kangz: Complete

Cvar Changes

2014-01-20T21:59:38Z

Kangz: Add N/A

{| class="wikitable"
! New Cvar !! Old Cvar
|-
| audio.al.availableCaptureDevices ||
|-
| audio.al.availableDevices ||
|-
| audio.al.captureDevice ||
|-
| audio.al.checkAllCalls || N/A
|-
| audio.al.device ||
|-
| audio.doppler || N/A
|-
| audio.dopplerExaggeration || N/A
|-
| audio.muteWhenMinimized ||
|-
| audio.muteWhenUnfocused ||
|-
| audio.reverb || N/A
|-
| audio.reverbIntensity || N/A
|-
| audio.volume.effects ||
|-
| audio.volume.master ||
|-
| audio.volume.music ||
|-
| common.framerate.fixed ||
|-
| common.framerate.max ||
|-
| common.framerate.maxMinimized ||
|-
| common.framerate.maxUnfocused ||
|-
| common.ignoreCrash ||
|-
| common.pipefile ||
|-
| common.showTraceStats ||
|-
| common.watchdogCmd ||
|-
| common.watchdogTime ||
|-
| logs.logFile.active ||
|-
| logs.logFile.filename ||
|-
| logs.logFile.forceFlush ||
|-
| logs.logFile.overwrite ||
|-
| logs.logLevel.audio || N/A
|-
| logs.logLevel.common.commands || N/A
|-
| server.vm.useNaCl || N/A
|}

Troubleshooting

2014-01-13T23:30:02Z

Kangz: Add an explanation for the general case of Syscall ABI Mismatch

If you do not see your issue listed here, please seek support either on the [http://unvanquished.net/forum/forumdisplay.php/6-Troubleshooting support forums] or [[IRC]]. If you think you may have found a bug, please [[Bug_reporting|report it]].

==Installer==

===Installation fails with "Problem running post-install step".===

If you get an error stating "Problem running post-install step. Installation may not complete correctly. Error getting [url]", just try running the installer again; it is possible that the mirror the installer picked was no good. Otherwise, you might want to try [[Compiling_the_source#Acquiring_the_Game_Files|manually downloading the game files]].

==All platforms==

Before attempting any of the fixes listed here, you may want to [[Compiling_the_source#Verifying_the_Files|verify your installation]]. This takes minimal effort and corrupted asset files is often the problem.

====The game crashes with "recursive error 'Syscall ABI mismatch' after: Syscall ABI mismatch"====

This is most of the time caused by having a wrong combination of assets and executable. Try updating the game and assets.

===The console will not open===

<ol>
<li>Locate the autogen.cfg file in your profile folder, which is a subdirectory of your [[#Data_directory|data directory]].</li>
<li>Search for <code>"bind ~ toggleconsole"</code>, and delete the entire line, if present.</li>
<li>Search for <code>"seta cl_consoleKeys"</code>, and ensure that <code>"~"</code> and <code>"`"</code> (at a minimum, though you may assign other keys if you so desire) are listed in a space-delimited quoted string. The line may look like this:
<pre>
seta cl_consoleKeys "~ ` 0x7e 0x60"
</pre>
</li>
</ol>

The console should now work by pressing the {{Hotkey|~}} or {{Hotkey|`}} keys.

===The game appears to stutter===

Enable VSync either through the menu or by setting <code>r_swapInterval</code> to <code>1</code>. Setting <code>r_swapInterval</code> to a value higher than <code>1</code> will synchronize rendering to every ''n''th refresh of the display; i.e., if your monitor's refresh rate was 60 Hz, a value of <code>2</code> would result in a framerate of 30 frames per second, a value of <code>3</code> would result in a framerate of 20 frames per second, etc.

===Certain maps seem excessively bright===

If maps appear far too bright (consistently bright with no static shadows), your version of WebP is likely out of date. Get a newer copy from Google and [[Compiling_the_source|re-compile]].

===Trouble running the game on Unices after updating to Alpha 9===

Make sure that you are running <code>daemon</code> and not <code>daemon.i386</code>; the name has changed and you may safely delete the latter.

===The game crashes upon compiling shaders===

[[Running_the_game#Running_the_game_with_special_options|Run the game]] with "<code>+set r_recompileShaders 1</code>".

===Miscellaneous graphical anomalies===

If you are using the GL3 renderer, you may just need to recompile the shaders. Enter this at the in-game console:

\r_recompileShaders 1; glsl_restart

===Not all servers are listed===

Input the following into the in-game console:

/reset protocol

Hit the "Get New List" button in the in-game server browser, and the formerly omitted servers should appear.

===menu list 'ui/menus.txt' not found, unable to continue!===

The game files are not properly installed or they are corrupt. If this is the case, make sure that the pk3s are in the <code>~/.Unvanquished/main</code> folder, paying careful attention to spelling and capitalization.

===Miscellaneous game freezes/crashes or graphical glitches===

If no other fix works, try reverting to the old renderer by
[[Running_the_game#Running_the_game_with_special_options|running the game]] with the <code>"+set cl_renderer gl"</code> switch.

==Linux==

===Cracking Sound===

In the options dialog which is reachable from the main menu set "OpenAL Sound" to "No".

==Mac OS X==

===Mouse movement seems very slow===

Input the following line into the console:

/in_disablemacosxmouseaccel 0

This will enable mouse acceleration.

==Windows==

====The game crashes with "recursive error 'Syscall ABI mismatch' after: Syscall ABI mismatch"====

Run the game with the [[Running_the_game#Running_the_game_with_special_options|special option]] <code>+set sv_pure 0</code>.

Mapping

2014-01-06T10:05:22Z

Kangz: Add a link to Tutorial/Reverberation

Mapping or 'level-making' for Unvanquished is fun to learn but difficult to master. Creating maps is highly open ended — anyone can use any of an infinite variety of techniques to make a map, for both fun and showing off via release.

This page provides resources and tutorials for all skill levels, from beginner to demi-goat.

== Getting Started ==
* [[Tutorials/Mapping_Tools|Tools]] — installing and setting up the mapping tools
* [[Tutorials/Mapping_Guide|Complete mapping guide]] — From start to finish, assuming little previous knowledge.
* [http://tremmapping.pbworks.com/w/page/22453200/Starting%20Tremulous%20Mapping Tremulous Mapping Tutorial] — still applicable to Unvanquished
* [[Testing#Testing_maps|Map testing hints]]

== Techniques and Features ==
* [[Tutorials/Colour_Grading|Colour Grading]] — Changing colour-schemas on maps.
* [[Tutorials/Reverberation|Reverberation]] — Adding reverberation effects on maps.
* [[Tutorials/Minimap|Minimaps]] — Current minimap system. Will eventually be replaced with automatic model.

== Mapping Approaches ==
* [http://www.thiagoklafke.com/modularenvironments.html Modular environments] — making maps out of pre-made components

== VIS and optimisation ==
Unvanquished employs a VIS (visibility) system to improve game performance. Only a visible subset of a whole levels is 'rendered' at any one time, because rendering things you can't see wastes performance. Although the compiler can do this itself, much more efficient VIS systems can be enforced by doing it by hand.
* [http://tremmapping.pbworks.com/w/page/22453205/Understanding%20Vis%20and%20Hint%20Brushes Understanding Vis and Hint Brushes] {{Rehost}}
* [http://www.quake3world.com/forum/viewtopic.php?t=3620 Advanced VIS and hinting tutorial] {{Rehost}}

== Compilation ==
Maps must be compiled by a compiler to get them into a format the [[Daemon|engine]] understands.
* [[Mapping/Compilation|Compilation overview]]
* [https://en.wikipedia.org/wiki/Quake_engine Wikipedia article on 'Quake Engine'] — brief description of map mesh optimisation.

== Migrating content from other quake engines ==
* [[Entities/Changes|Entity Changes]] — entity changes from Tremulous and Q3

== Old Guides ==
Content in these should either be used in new guides or updated to be useful.
* [[Tutorials/Mapping_Old|Old mapping page]] — old mapping page, some content has still not been merged.

Tutorials/Reverberation

2014-01-06T00:55:47Z

Kangz: Create the page

== What it is ==

Reverberation is the effect of a sound lasting after it has been produced because of its the mutiples echos in the environment. It can give great audio clues as to what environment you are in: you would easily distinguish sounds in a regular room from sounds in a hangar from sounds in outdoor based on the reverberation. [http://en.wikipedia.org/wiki/Reverberation Wikipedia] has some examples of reverberation.

Dæmon supports reverberation effects, which you can try using the ''/testReverb'' command, it can be used in maps to give audio clues of the size of rooms and the material of their walls. However even if reverberation effects sound really cool, you should be subtle when using it: in real life you barely notice these effects unless you are in churches or hangars.

== Mapping reverberation ==

=== Global reverberation ===

Once you have found a reverberation effect you like with ''/testReverb'' you can apply it on the whole map by setting the following keys on the worldspawn.

* '''reverbEffect <presetname>''': with <presetname> the name of the effect to apply globally
* '''reverbIntensity <number>''': with <number> between 0 and 2 the intensity of the effect. The default is 1.0 so you can lower the effect or
crank it up to your liking (but it should mainly be used to lower the effect).

=== Localised reverberation ===

You can also define reverberation effects per area by placing func_static entities and adding the following keys to it:

* '''reverbEffect <presetname>''': like for the worldspawn
* '''reverbIntensity <number>''': like for the worldspawn
* '''reverbDistance <distance>''': a distance in qunits representing the approximate size of the room in which to use the effect. Between such func_statics, effects will be blended, potentially with the global reverb effect.

User:Kangz

2014-01-06T00:13:41Z

Kangz: Try to describe what I did for Unv in engine-upgrade so that I remember later

Hey there!

I played and loved Tremulous during 5 years, with the (CY) and Welcomed clans. I'm a french student in computer science at the École polytechnique in France and doing code for Unvanquished.

Things that I did or that I am currently doing:
* Config files
* [[Minimap]]
* Discovering the GL3 renderer
* FXAA
* Upgrading the engine
** Redid Commands
** Redid Cvars
** Redid Logs
** Redid the Audio (check out the [[Reverberation]])
** Moving from QVM to PNaCl
** Other misc stuff

I also play with the assets config files as my artistic ability is limited to creating crappy procedural textures.

I'm always on [[IRC]] (unless my server as a problem) and would love to speak with you!

User:Kangz

2013-09-04T20:33:42Z

Kangz:

Hey there!

I played and loved Tremulous during 5 years, with the (CY) and Welcomed clans. I'm a french student in computer science at the École polytechnique in France and doing code for Unvanquished.

Things that I did or that I am currently doing:
* Config files
* [[Minimap]]
* Discovering the GL3 renderer
* FXAA
* [[Engine_Upgrade|Upgrading the engine]]

I also play with the assets config files as my artistic ability is limited to creating crappy procedural textures.

I'm always on [[IRC]] (unless my server as a problem) and would love to speak with you!

Technical Documentation

2013-07-31T08:52:16Z

Kangz: /* Branches */ add nacl and engine-upgrade

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>bots</code> — bot code, using behavior trees.
* <code>engine-upgrade</code> — Work to rewrite the engine in C++ for better maintanability.
* <code>nacl</code> — Conversion from QVMs to NaCl sandbox (will be PNaCl at some point)

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

User:Kangz/DevLinks

2013-06-18T21:06:48Z

Kangz:

Dev links and interesting information

== Server side demos ==

[08|06:18:02] < Amanieu> kharnov/kangz: for server-side demos, have a look at https://github.com/lrq3000/openarena_engine_serversidedemos
[08|06:18:20] < Amanieu> Someone took my server-side demo patch and ported it to openarena
[08|06:18:24] < Amanieu> fixed it up a bit too
[08|06:43:20] < Amanieu> you're probably going to need a few gamecode hooks
[08|06:43:55] < Amanieu> have a look at lakitu7-qvm-svdemo.patch
[08|06:43:58] < Amanieu> in tremfusion/misc
[08|06:48:08] < Amanieu> the openarena version probably won't work out of the box
[08|06:48:18] < Amanieu> I expect the scoreboard and stages to be broken
[08|06:48:28] < Amanieu> but otherwise everything else should work fine
[08|06:49:13] < Amanieu> oh and teamchat won't be recorded

== LibRocket ==

[http://blog.wolfire.com/2013/06/Art-Asset-Overview-41 Nice 3d menu by wolfire game]

[https://github.com/TermiT/duke3d-megaton/blob/master/code/rocket/RocketAnimationPlugin.h Interesting librocket plugins]

== Refactor / C++ ==

[http://kotaku.com/undefined The exceptional beauty of DOOM3's source code]

[ftp://ftp.idsoftware.com/idstuff/doom3/source/CodeStyleConventions.doc doom3 coding conventions]

[http://icculus.org/physfs/ a library that mimics the q3 FS]

== Better particles ==

[http://blog.wolfire.com/2010/04/Soft-Particles Wolfire soft particles (no hard clipping)]

[http://http.developer.nvidia.com/GPUGems3/gpugems3_ch23.html GPU Gems 3: Efficient off-screen particles]

[http://www.humus.name/index.php?ID=266 Humus' particle trimming tool]

User:Kangz/Renderer Discovery

2013-06-18T03:36:35Z

Kangz: Add misc source files

I'm trying to learn how the renderer works, usually I write a lot of things on paper but since we have a wiki why not share my work with the other?
I'll be going through all the files in src/engine/rendererGL, things in ''italic'' are things I need to understand.
Please do not make changes to the page, this is a draft I'm using to learn. If you have comments feel free to express yourself on the discussion page.

Kangz

== Headers ==

=== renderer/tr_public.h ===

2 structs refexport_t and refimport_t define the API between the client and the renderer.

refimport_t has API for:
* Printing and errors, cvars, commands
* Memory management
* File management
* Cinematics and AVI recording
* Misc (CM_debug, GL init, input, ftol)

refexport has API for:
* Shutting down the renderer (or reloading it)
* Registration of assets
** BeginRegistration and EndRegistration respectively remove all the assets and upload all the assets
** Registration for models, skins, shaders, fonts, ''fontsVM?, glyph of all sorts'' and the world + visibility
** Things can be registered outside of Begin End but it is less efficient
* Drawing the scene
** Starts with ClearScene and ends with RenderScene (takes the definition of the view, referential definition)
** A bunch of add* functions to add elements to the scene
* Drawing 2d elements directly ''(it seems)''
* Managing visibility queries
* Setting the color grading
* Misc (RTT, shader management, video encoding...)

=== renderer/tr_types.h ===

Companion files for tr_public.h that defines the associated structs and constants

Interesting struct are (add as I go):
* refEntity_t given for any entity that needs to be drawn
** orientation for the different parts of the model
** skin, texture and shader parameters
** ''a lot of other crap that looks redundant''
* refLight_t for any dynamic light
** Position, orientation, projection
** Type and shadow casting stuff
* refDef_t the view used for rendering
** Position, orientation, FOV, screen size
** Motion blur, color grading and fog parameters
** Other things
* gl_config{2}_t OpenGL capabilities and settings

=== rendererGL/tr_local.h ===
All the things shared by the different rendererGL files
* More constants and enums
* Structs for everything
* A struct with the global state of the renderer
* Some global variables, including all the cvars
* An inline linked-list/queue/stack implementation
* Function definitions

Too many things to list all of it. Will detail in the different relevant files

=== rendererGL/tr_image.h ===

Includes JPEG headers

=== rendererGL/tr_model_skel.h ===

Prototype of the few functions in rendererGL/tr_model_skel.c

=== rendererGL/gl_sader.h ===

C++ prototypes for:
* GLShader and GLShaderManager
* GLUniform derived in a class per uniform type
* GLCompileMacro derived in a class per compile macro
* A class par uniform variable in a shader (derives from a uniform type class)
* A class per shader with derived from GLShader, each of the uniform class for this shader and each compile macro (no virtual method so it's ok to do this).
* A variable for each shader.

== Renderer management source files ==

=== rendererGL/tr_init.cpp ===

Stuff that is not used every frame

Contains the definition of global variables (cvars, glconfig, glstate)

Defines some of the renderer console commands:
* modelist
* screenshot{|JPEG|PNG}
* gfxinfo
* glsl_restart

Handles screenshots and video recording stuff

Interesting OpenGL functions:
* InitOpenGL: call GLimpl_Init if not already done, set the default state, initializes the command queue, ...
* GL_CheckErrors_ used by the macro GL_CheckErrors
* RB_ReadPixels, sort of wrapper around glReadPixels
* GL_SetDefaultState

Interesting renderer functions:
* GetRefAPI: the single entry point of the renderer library
* R_Init
** Called by R_BeginRegistration in tr_model.c
** Calls the initialisation of everyhing: LUT, cvars, commandbuffers, OpenGL, GPUshaders, images, fbo, vbo, q3shaders, skins, models, animations, freetype, occlusion queries
** Initialize DX10 as well, with special code for "Nvidia PerfHUD"
** ''seems to start the multiprocessing''
* R_Register, register cvars and console commands
* R_Shutdown
** Removes console commands and all the OpenGL state
** May remove the window
* R_EndRegistration, synchronizes with the render thread and the GPU

Definitions for Com_Printf, Com_DPrintf and Com_Error.

== Backend source files ==

=== rendererGL/tr_backend.c ===

''TODO''

=== rendererGL/tr_shade.cpp ===

Contains the Tess_Begin and Tess_End pseudo state machine and code necessary to transform shaders in real OpenGL calls.

* Tess_Begin sets up the tess data structure with some parameters, the most important being the stage iterator: a function that will iterate over the stages of the shader and decide what to do with them (Forward render, and many iterators for deferred rendering: GBuffer, DepthFill, ...).
* Tess_End essentially calls the stage iterator on the tess data structure.
* Most stage iterators: for each stage they decide what to do with the specific surface type, calling one of the Render_ functions.
* The Render_ functions: they set up all the parameters for a specific OpenGL shader and finish by calling Tess_Draw that gives the actual GL draw calls.
* Also contains code that loads and destroys all the OpenGL shaders.

=== rendererGL/tr_shade_calc.c ===

Handles the user specified expressions and deformations in shaders:
* RB_EvalExpression returns the value of a shader expression.
* Functions that act on the tess structure to deform vertices, called if needed by Tess_DeformGeometry
* RB_CalcTexMatrix for the transformations of the texture coordinates

=== rendererGL/tr_surface.c ===

Definition of rb_surfaceTable with a "Tess" function for each type of surface. Code from the vanilla renderer just fill the arrays in the tess variable table, newer code bind VBOs and IBOs. In the whole file the modelview matrix is supposed to be valid and the calls to rb_surfaceTable are supposed to be surrounded by Tess_Begin() and Tess_End().

== Q3 Shader source files ==

=== rendererGL/tr_shader.c ===

This file is a huge parser for shader files. At the start of the engine all .shader files are read and the different shaders are put in a hashmap. After ParseShader and potentially several ParseStage the shader is optimized (multitexturing).

Also contains:
* The shaderlist command
* The shaderexp (evals a shader expression) command
* R_InitShaders

== OpenGL objects source files ==

=== rendererGL/gl_shader.cpp ===

C++ code dealing with OpenGL shaders.

Contains the implementation of the shader manager:
* Add defines to the shader text
* Computes shader permutation incrementally or not
* Handle binary shaders

Definition of the Compile macro and shader function (dependances, ...)

=== rendererGL/tr_fbo.c ===

Functions to create, bind or attach components to FBOs and:
* Definition of the fbolist command
* R_InitFBO, creates all the needed FBOs

=== rendererGL/tr_vbo.c ===

Functions to create, bind, ... VBOs ad IBOs:
* Definition of the vbolist command
* R_InitVBOs creates the static VBOs
* ''R_Create{VBO|IBO}{2}''

== Misc source files ==

=== rendererGL/tr_decals.c ===

Function to add decals on the world.

=== rendererGL/tr_fog.c ===

''Seems to control the fog through the old glFog calls. Most of the code has been commented and I'm not sure if the file is ever used.''

=== rendererGL/tr_marks.c ===

''Functions to project decals onto the world?''

=== rendererGL/tr_noise.c ===

Functions to fill noise tables.

=== rendererGL/tr_shadows.c ===

Contains a single function that change the tess data structure to make the ugly quake3 "flat" shadows.

=== rendererGL/tr_sky.cpp ===

This backend file is a big hack to make the renderer render the skybox. Contains Tess_StageIteratorSky and helper function. In Tess_Begin if we render the sky we put the real stage iterator in the second slot and StageIteratorSky will be the one that gets called. It will execute different things depending on the second stage iterator.

== Model source files ==

=== rendererGL/tr_animation.c ===

Contains R_LoadMD5Anim and R_LoadPSA, the definition of the "animationlist" console command and R_InitAnimation.

Many functions liked to bones and skeletons (culling, interactions, adding the triangles, ...)

=== rendererGL/tr_model.c ===

Model loading and handle->model

Interesting functions:
* RE_RegisterModel: loads a model files and puts it in the store
* R_GetModelByHandle handle->model
* R_ModelInit, essentially memory alloc
* Definition for the modellist command

Also MDX loading, model tag and bone stuff

=== Format specific files ===

==== rendererGL/tr_animation_mdm.c ====

Functions related to MDM (lod, interactions, animation, ...) and comes with its own math lib.

''Tess_SurfaceVBOMDMMesh and Tess_MDM_SurfaceAnim''.

==== rendererGL/tr_model_md3.c ====

Definition of R_LoadMD3

==== rendererGL/tr_model_md5.c ====

Definition of R_LoadMD5

==== rendererGL/tr_model_mdc.c ====

Definition of R_LoadMDC

==== rendererGL/tr_model_mdm.c ====

Definition of R_LoadMDM

==== rendererGL/tr_model_psk.c ====

Definition of R_LoadPSK

==== rendererGL/tr_model_skel.c ====

''Definition of functions for adding things to skeleton VBO''

=== rendererGL/tr_skin.c ===

''Seems to handle the loading of "skins" for md3 models. We don't seem to use it.'' Also contains the definition of skinlist

== Image source files ==

=== rendererGL/tr_image.c ===

Image (CPU) and texture (GPU) loading, management, computations

Image functions:
* ''Gamma implemenation''
* Image manipulation (mipmaps, blends, ...)
* R_LoadImage with different formats and operations
* Definition of imagelist command
* R_CreateBuiltinImages

Texture OpenGL functions:
* Creation of 2D, Cube and 3D textures (_and glyphs_)
* R_UploadImage with many branches
* Texture mode
* Creates the images needed by the FBOs

Other:
* R_InitImages init memory, default images, ... (charset as well)
* R_ShutdownImages
* ''R_SetColorMapping''
* Color grading upload

=== Format specific files ===

==== rendererGL/tr_image_dds.c ====

Contains R_LoadDDSImage and compressed image uploading to the GPU

==== rendererGL/tr_image_exr.c ====

Contains LoadRGBEToHalfs and LoadRGBEToFloats used in rendererGL/tr_bsp.c (_but what for?_) (_and is it included there?_)

==== rendererGL/tr_image_jpg.c ====

Contains LoadJPG, SaveJPG and SaveJPGToBuffer

==== rendererGL/tr_image_png.c ====

Contains LoadPNG and SavePNG

==== rendererGL/tr_image_tga.c ====

Contains LoadTGA

==== rendererGL/tr_image_webp.c ====

Contains LoadWEBP

User:Kangz/Renderer Discovery

2013-06-18T02:58:02Z

Kangz: tr_shade and tr_shade_calc

I'm trying to learn how the renderer works, usually I write a lot of things on paper but since we have a wiki why not share my work with the other?
I'll be going through all the files in src/engine/rendererGL, things in ''italic'' are things I need to understand.
Please do not make changes to the page, this is a draft I'm using to learn. If you have comments feel free to express yourself on the discussion page.

Kangz

== Headers ==

=== renderer/tr_public.h ===

2 structs refexport_t and refimport_t define the API between the client and the renderer.

refimport_t has API for:
* Printing and errors, cvars, commands
* Memory management
* File management
* Cinematics and AVI recording
* Misc (CM_debug, GL init, input, ftol)

refexport has API for:
* Shutting down the renderer (or reloading it)
* Registration of assets
** BeginRegistration and EndRegistration respectively remove all the assets and upload all the assets
** Registration for models, skins, shaders, fonts, ''fontsVM?, glyph of all sorts'' and the world + visibility
** Things can be registered outside of Begin End but it is less efficient
* Drawing the scene
** Starts with ClearScene and ends with RenderScene (takes the definition of the view, referential definition)
** A bunch of add* functions to add elements to the scene
* Drawing 2d elements directly ''(it seems)''
* Managing visibility queries
* Setting the color grading
* Misc (RTT, shader management, video encoding...)

=== renderer/tr_types.h ===

Companion files for tr_public.h that defines the associated structs and constants

Interesting struct are (add as I go):
* refEntity_t given for any entity that needs to be drawn
** orientation for the different parts of the model
** skin, texture and shader parameters
** ''a lot of other crap that looks redundant''
* refLight_t for any dynamic light
** Position, orientation, projection
** Type and shadow casting stuff
* refDef_t the view used for rendering
** Position, orientation, FOV, screen size
** Motion blur, color grading and fog parameters
** Other things
* gl_config{2}_t OpenGL capabilities and settings

=== rendererGL/tr_local.h ===
All the things shared by the different rendererGL files
* More constants and enums
* Structs for everything
* A struct with the global state of the renderer
* Some global variables, including all the cvars
* An inline linked-list/queue/stack implementation
* Function definitions

Too many things to list all of it. Will detail in the different relevant files

=== rendererGL/tr_image.h ===

Includes JPEG headers

=== rendererGL/tr_model_skel.h ===

Prototype of the few functions in rendererGL/tr_model_skel.c

=== rendererGL/gl_sader.h ===

C++ prototypes for:
* GLShader and GLShaderManager
* GLUniform derived in a class per uniform type
* GLCompileMacro derived in a class per compile macro
* A class par uniform variable in a shader (derives from a uniform type class)
* A class per shader with derived from GLShader, each of the uniform class for this shader and each compile macro (no virtual method so it's ok to do this).
* A variable for each shader.

== Renderer management source files ==

=== rendererGL/tr_init.cpp ===

Stuff that is not used every frame

Contains the definition of global variables (cvars, glconfig, glstate)

Defines some of the renderer console commands:
* modelist
* screenshot{|JPEG|PNG}
* gfxinfo
* glsl_restart

Handles screenshots and video recording stuff

Interesting OpenGL functions:
* InitOpenGL: call GLimpl_Init if not already done, set the default state, initializes the command queue, ...
* GL_CheckErrors_ used by the macro GL_CheckErrors
* RB_ReadPixels, sort of wrapper around glReadPixels
* GL_SetDefaultState

Interesting renderer functions:
* GetRefAPI: the single entry point of the renderer library
* R_Init
** Called by R_BeginRegistration in tr_model.c
** Calls the initialisation of everyhing: LUT, cvars, commandbuffers, OpenGL, GPUshaders, images, fbo, vbo, q3shaders, skins, models, animations, freetype, occlusion queries
** Initialize DX10 as well, with special code for "Nvidia PerfHUD"
** ''seems to start the multiprocessing''
* R_Register, register cvars and console commands
* R_Shutdown
** Removes console commands and all the OpenGL state
** May remove the window
* R_EndRegistration, synchronizes with the render thread and the GPU

Definitions for Com_Printf, Com_DPrintf and Com_Error.

== Backend source files ==

=== rendererGL/tr_backend.c ===

''TODO''

=== rendererGL/tr_shade.cpp ===

Contains the Tess_Begin and Tess_End pseudo state machine and code necessary to transform shaders in real OpenGL calls.

* Tess_Begin sets up the tess data structure with some parameters, the most important being the stage iterator: a function that will iterate over the stages of the shader and decide what to do with them (Forward render, and many iterators for deferred rendering: GBuffer, DepthFill, ...).
* Tess_End essentially calls the stage iterator on the tess data structure.
* Most stage iterators: for each stage they decide what to do with the specific surface type, calling one of the Render_ functions.
* The Render_ functions: they set up all the parameters for a specific OpenGL shader and finish by calling Tess_Draw that gives the actual GL draw calls.
* Also contains code that loads and destroys all the OpenGL shaders.

=== rendererGL/tr_shade_calc.c ===

Handles the user specified expressions and deformations in shaders:
* RB_EvalExpression returns the value of a shader expression.
* Functions that act on the tess structure to deform vertices, called if needed by Tess_DeformGeometry
* RB_CalcTexMatrix for the transformations of the texture coordinates

=== rendererGL/tr_surface.c ===

Definition of rb_surfaceTable with a "Tess" function for each type of surface. Code from the vanilla renderer just fill the arrays in the tess variable table, newer code bind VBOs and IBOs. In the whole file the modelview matrix is supposed to be valid and the calls to rb_surfaceTable are supposed to be surrounded by Tess_Begin() and Tess_End().

== Q3 Shader source files ==

=== rendererGL/tr_shader.c ===

This file is a huge parser for shader files. At the start of the engine all .shader files are read and the different shaders are put in a hashmap. After ParseShader and potentially several ParseStage the shader is optimized (multitexturing).

Also contains:
* The shaderlist command
* The shaderexp (evals a shader expression) command
* R_InitShaders

== OpenGL objects source files ==

=== rendererGL/gl_shader.cpp ===

C++ code dealing with OpenGL shaders.

Contains the implementation of the shader manager:
* Add defines to the shader text
* Computes shader permutation incrementally or not
* Handle binary shaders

Definition of the Compile macro and shader function (dependances, ...)

=== rendererGL/tr_fbo.c ===

Functions to create, bind or attach components to FBOs and:
* Definition of the fbolist command
* R_InitFBO, creates all the needed FBOs

=== rendererGL/tr_vbo.c ===

Functions to create, bind, ... VBOs ad IBOs:
* Definition of the vbolist command
* R_InitVBOs creates the static VBOs
* ''R_Create{VBO|IBO}{2}''

== Model source files ==

=== rendererGL/tr_animation.c ===

Contains R_LoadMD5Anim and R_LoadPSA, the definition of the "animationlist" console command and R_InitAnimation.

Many functions liked to bones and skeletons (culling, interactions, adding the triangles, ...)

=== rendererGL/tr_model.c ===

Model loading and handle->model

Interesting functions:
* RE_RegisterModel: loads a model files and puts it in the store
* R_GetModelByHandle handle->model
* R_ModelInit, essentially memory alloc
* Definition for the modellist command

Also MDX loading, model tag and bone stuff

=== Format specific files ===

==== rendererGL/tr_animation_mdm.c ====

Functions related to MDM (lod, interactions, animation, ...) and comes with its own math lib.

''Tess_SurfaceVBOMDMMesh and Tess_MDM_SurfaceAnim''.

==== rendererGL/tr_model_md3.c ====

Definition of R_LoadMD3

==== rendererGL/tr_model_md5.c ====

Definition of R_LoadMD5

==== rendererGL/tr_model_mdc.c ====

Definition of R_LoadMDC

==== rendererGL/tr_model_mdm.c ====

Definition of R_LoadMDM

==== rendererGL/tr_model_psk.c ====

Definition of R_LoadPSK

==== rendererGL/tr_model_skel.c ====

''Definition of functions for adding things to skeleton VBO''

== Image source files ==

=== rendererGL/tr_image.c ===

Image (CPU) and texture (GPU) loading, management, computations

Image functions:
* ''Gamma implemenation''
* Image manipulation (mipmaps, blends, ...)
* R_LoadImage with different formats and operations
* Definition of imagelist command
* R_CreateBuiltinImages

Texture OpenGL functions:
* Creation of 2D, Cube and 3D textures (_and glyphs_)
* R_UploadImage with many branches
* Texture mode
* Creates the images needed by the FBOs

Other:
* R_InitImages init memory, default images, ... (charset as well)
* R_ShutdownImages
* ''R_SetColorMapping''
* Color grading upload

=== Format specific files ===

==== rendererGL/tr_image_dds.c ====

Contains R_LoadDDSImage and compressed image uploading to the GPU

==== rendererGL/tr_image_exr.c ====

Contains LoadRGBEToHalfs and LoadRGBEToFloats used in rendererGL/tr_bsp.c (_but what for?_) (_and is it included there?_)

==== rendererGL/tr_image_jpg.c ====

Contains LoadJPG, SaveJPG and SaveJPGToBuffer

==== rendererGL/tr_image_png.c ====

Contains LoadPNG and SavePNG

==== rendererGL/tr_image_tga.c ====

Contains LoadTGA

==== rendererGL/tr_image_webp.c ====

Contains LoadWEBP

User:Kangz/DevLinks

2013-06-11T21:44:28Z

Kangz:

Dev links and interesting information

== Server side demos ==

[08|06:18:02] < Amanieu> kharnov/kangz: for server-side demos, have a look at https://github.com/lrq3000/openarena_engine_serversidedemos
[08|06:18:20] < Amanieu> Someone took my server-side demo patch and ported it to openarena
[08|06:18:24] < Amanieu> fixed it up a bit too
[08|06:43:20] < Amanieu> you're probably going to need a few gamecode hooks
[08|06:43:55] < Amanieu> have a look at lakitu7-qvm-svdemo.patch
[08|06:43:58] < Amanieu> in tremfusion/misc
[08|06:48:08] < Amanieu> the openarena version probably won't work out of the box
[08|06:48:18] < Amanieu> I expect the scoreboard and stages to be broken
[08|06:48:28] < Amanieu> but otherwise everything else should work fine
[08|06:49:13] < Amanieu> oh and teamchat won't be recorded

== LibRocket ==

[http://blog.wolfire.com/2013/06/Art-Asset-Overview-41 Nice 3d menu by wolfire game]

[https://github.com/TermiT/duke3d-megaton/blob/master/code/rocket/RocketAnimationPlugin.h Interesting librocket plugins]

== Refactor / C++ ==

[http://kotaku.com/undefined The exceptional beauty of DOOM3's source code]

[ftp://ftp.idsoftware.com/idstuff/doom3/source/CodeStyleConventions.doc doom3 coding conventions]

== Better particles ==

[http://blog.wolfire.com/2010/04/Soft-Particles Wolfire soft particles (no hard clipping)]

[http://http.developer.nvidia.com/GPUGems3/gpugems3_ch23.html GPU Gems 3: Efficient off-screen particles]

[http://www.humus.name/index.php?ID=266 Humus' particle trimming tool]

User:Kangz/DevLinks

2013-06-09T04:17:25Z

Kangz:

Dev links and interesting information

== Server side demos ==

[08|06:18:02] < Amanieu> kharnov/kangz: for server-side demos, have a look at https://github.com/lrq3000/openarena_engine_serversidedemos
[08|06:18:20] < Amanieu> Someone took my server-side demo patch and ported it to openarena
[08|06:18:24] < Amanieu> fixed it up a bit too
[08|06:43:20] < Amanieu> you're probably going to need a few gamecode hooks
[08|06:43:55] < Amanieu> have a look at lakitu7-qvm-svdemo.patch
[08|06:43:58] < Amanieu> in tremfusion/misc
[08|06:48:08] < Amanieu> the openarena version probably won't work out of the box
[08|06:48:18] < Amanieu> I expect the scoreboard and stages to be broken
[08|06:48:28] < Amanieu> but otherwise everything else should work fine
[08|06:49:13] < Amanieu> oh and teamchat won't be recorded

== LibRocket ==

[http://blog.wolfire.com/2013/06/Art-Asset-Overview-41 Nice 3d menu by wolfire game]

[https://github.com/TermiT/duke3d-megaton/blob/master/code/rocket/RocketAnimationPlugin.h Interesting librocket plugins]

== Refector / C++ ==

[http://kotaku.com/undefined The exceptional beauty of DOOM3's source code]

[ftp://ftp.idsoftware.com/idstuff/doom3/source/CodeStyleConventions.doc doom3 coding conventions]

User:Kangz/DevLinks

2013-06-08T06:47:14Z

Kangz: Created page with "Dev links and interesting information == Server side demos == [08|06:18:02] < Amanieu> kharnov/kangz: for server-side demos, have a look at https://github.com/lrq3000/opena..."

User:Kangz

2013-05-27T01:45:37Z

Kangz:

Hey there!

I played and loved Tremulous during 5 years, with the (CY) and Welcomed clans. I'm a french student in computer science at the École polytechnique in France and doing code for Unvanquished.

Things that I did or that I am currently doing:
* Config files
* [[Minimap]]
* Discovering the GL3 renderer

I also play with the assets config files as my artistic ability is limited to creating crappy procedural textures.

I'm always on [[IRC]] (unless my server as a problem) and would love to speak with you!

User:Minimap

2013-05-27T01:45:13Z

Kangz: Kangz moved page User:Minimap to Minimap: Forgot the namespace :)

#REDIRECT [[Minimap]]

Tutorials/Minimap

2013-05-27T01:45:12Z

Kangz: Kangz moved page User:Minimap to Minimap: Forgot the namespace :)

[[File:Minimap_atcshd_example.png|thumb|200px|A basic minimap for atcshd]]

Minimaps have two purposes: help the player navigate some very large and confusing map and promote teamplay by showing the location of your teammates. They are created by the mapper and are part of the assets of a map. They follow more or less [[Feature_Proposals/Minimap|the old design document]]. Each minimap consists of a number of zones: in each region of the map a different image can be used, for example to represent the different floors of a facility.

== How to create a minimap: the quick and simple method ==

* Open the map using netradiant.
* Go in the Build menu and select Customize.
* Search for the minimap command line and set the number after -size to a large value (e.g. 512).
* Go in the Build menu and build the minimap.
* Note the numbers in the log window appearing after ''size_texcoords''.
* Put the resulting tga file in the minimaps/ folder.
* Create a file minimaps/<name of your map>.minimap and write it using the following template (by replacing 1, 2, 4 and 5 by the first, second, fourth and fifth number appearing after ''size_texcoords''):
{
zone {
bounds -100000 -100000 -100000 100000 100000 100000
image "minimaps/<mapname>" 1 2 4 5
}
}
* Load your map and enjoy that magnificient minimap.

== How to create a minimap: tutorial using q3map2 ==

q3map2 can create minimaps from the .map file. These minimaps basically show the solid walls by checking how much solid brush is under each pixel: a wall has a big intersection with the vertical line but a floor not so much.

=== Configuring netRadiant ===

Before you start generating images you probably want to change the options given to q3map2 and make sure the image size is at least 512. To do that go on the Build menu and select Customize. Below is a very simple sample configuration for a minimap build.

[[File:Minimap_customize_options.png]]

You can use the q3map2 minimap options list below to customize the output. A good default build line is

[q3map2] -minimap -samples 10 -size 512 -border 0.0 "[MapFile]"

=== Creating the images ===

[[File:Minimap_atcshd_cutted.png|thumb|200px|atcshd with the center missing and a filled door]]

Running the minimap build at this point will create a single minimap image for the whole map. You might want to create several images either because the maps is too cluttered (many intricated levels) either because the map is too large.

If you simply want to cut the minimap in several part, first try to make a bigger image (image with a size of 2048 should work in the engine) with a bigger ''globalScale'' parameter in your minimap config file. If you aren't happy with the result, try using the ''minmax'' switch for the minimap build to render a smaller part; make sure the different images overlap so that there is a smooth transition ingame.

When the map is too cluttered, the only solution is too cut parts of it and make differents zones for the different levels of your map. To do this remove all the parts you don't want to see and fill the "holes" left in you map with a solid brush (to avoid leaks).

=== Creating the minimap file ===

To create the minimap follow the manual, look at the example in the simple tutorial or look at an existing minimap file. You'll have to add parameters and potentially more zones. You can keep most parameters to their default value. The tricky part are the ''bounds'' and ''image'' parameters.

For the ''bounds'' parameter you can either:
* picks the points coordinates by hand in netRadiant
* use the 6 ''size_texcoords'' numbers in the q3map2 output
* use the parameter you gave to the ''minmax'' q3map2 switch is you used it.
These numbers will make a somewhat good default value for the zone bounds then you can tweak it so that it to your taste. Note that the numbers must always by <xmin> then <xmax> as in the doc, otherwise the zone will never be used. You can use multiple zones with the same image to define a more complex shape.

For the ''image'' parameter, first use the image filename without the extension then big the four numbers highlighted in the q3map2 log below and paste them in the same order (do not confuse ''size'' and ''size_texcoords'').

[[File:Minimap_q3map2_texcoords.png]]

== Minimap file manual ==

A minimap file has the following structure (with at least one zone block)

{
<zone blocks or global parameters>
}

With each zone block with the following structure

zone {
<zone-specific parameters>
}

The zone are used to show different images in different regions of the map. When a player gets outside the bounds of the zone he is currently on, zones will be searched in the order defined in the file to choose the new image. If no zone fits then the last one defined will be used. This way you can define a default zone by putting at the end of the minimap file the following zone block:

zone {
bounds 0.0 0.0 0.0 0.0 0.0 0.0
<other parameters>
}

=== Global parameters ===

==== backgroundColor ====

backgroundColor <float r> <float g> <float b> <float a>

Chooses the color of the background of the map. Defaults to opaque black. If the map has been generated by q3map2 you most probably to leave it to opaque black. You can use a transparent background but it won't play well with semi-transparent maps; you'd better use a binary transparency and a semi-transparent background color.

==== globalScale ====

globalScale <float ratio>

Multiplies the size of the minimap and all the minimap objects by the given ratio: it is a sort of global zoom of the map. Defaults to 1.0.

=== Zone-specific parameters ===

Each zone block must have a bounds and image parameter or an error will be generated.

==== bounds ====

bounds <float xmin> <float ymin> <float zmin> <float xmax> <float ymax> <float zmax>

Defines in which "box volume" this zone is in effect. The arguments are world units and must be in that order (xmin < xmax, ...)

==== image ====

image <filename> <float xmin> <float ymin> <float xmax> <float ymax>

Defines which image to use and what rectangular area that image represents in the world. The four position arguments are in world units; they are the X and Y bounds of a brush that would cover the whole minimap. The filename should ideally be without the file extension (you could theoretically use a shader name too).

==== scale ====

scale <float ratio>

When the player is inside the zone, multiplies the size of the minimap and all the minimap objects by the given ratio. Defaults to 1.0.

== q3map2 minimap options ==

The q3map2 commandline looks like this in netRadiant:

[q3map2] -minimap <switches> "[MapFile]"

=== "Color" switches ===

==== autolevel ====

-autolevel

Tries to find automatically the right contrast and brightness values to use. Defaults to off.

==== boost ====

-boost <float b>

Changes the gamma of the resulting image using the following formula color' = color / ((b - 1) * color + 1). Defaults to 1.0. (the pass is made before the contrast/sharpen pass)

==== contrast ====

-contrast <float c>

Changes the contrast of the resulting image using the following formula color' = color * c + sharpen. Defaults to 1.0. (the pass is made after the boost pass)

==== noautolevel ====

-noautolevel

Will not try to find automatically the right contrast and brightness values to use. Defaults to on.

==== sharpen ====

-sharpen <float s>

Changes the brightness of the resulting image using the following formula color' = color * contrast + s. Defaults to 1.0. (the pass is made after the boost pass)

=== Output control switches ===

==== black ====

-black

Writes the resulting minimap as a black TGA file with levels of transparency. (It was not tested yet, maybe the engine will treat it as a completely black image)

==== gray ====

-gray

Writes the image as a GRAY8 TGA file.

==== o ====

-o <filename.tga>

THIS IS SET AUTOMATICALLY BY NETRADIANT. Sets the filename of the output file.

==== white ====

-white

Writes the resulting minimap as a white TGA file with levels of transparency. (It seems our engine converts it in levels of gray)

=== Region switches ===

==== border ====

-border <float ratio>

Adds borders to the image with size (image_size * ratio). Defaults to 0.0 (at least for Tremulous).

==== keepaspect ====

-keepaspect

Makes it so that the resulting image will keep the aspect ratio (a square will stay a square) by adding empty space. Defaults to on.

==== minmax ====

-minmax <float xmin> <float ymin> <float zmin> <float xmax> <float ymax> <float zmax>

Restricts the minimap to the part of the map contained in the box defined by the parameters. By default this box is the bounding box of the whole map.

==== nokeepaspect ====

-nokeepaspect

THIS IS NOT SUPPORTED BY THE UNVANQUISHED MINIMAPS and included for completeness only. Allows q3map2 to not preserve the aspect ratio (in some way). Defaults to off.

==== size ====

-size <int N>

Changes the sizes of the resulting image to NxN. defaults to 512 for Tremulous.

=== Sampling switches ===

==== random ====

-random <int n>

Makes the minimap generation use random samples and sets the number of samples to take for each pixel of the minimap. Defaults to on and 1.

==== samples ====

-samples <int n>

Makes the minimap generation use ordered samples and sets the number of samples to take for each pixel of the minimap. Defaults to off and 1.

User:Kangz/Minimap

2013-05-27T01:44:41Z

Kangz: Kangz moved page User:Kangz/Minimap to User:Minimap: The draft is finished

#REDIRECT [[User:Minimap]]

Tutorials/Minimap

2013-05-27T01:44:41Z

Kangz: Kangz moved page User:Kangz/Minimap to User:Minimap: The draft is finished

Tutorials/Minimap

2013-05-24T05:26:06Z

Kangz: First version complete.

File:Minimap q3map2 texcoords.png

2013-05-24T05:25:26Z

Kangz: Extract from a q3map2 minimap output, highlight the size_texcoords numbers

Extract from a q3map2 minimap output, highlight the size_texcoords numbers

Tutorials/Minimap

2013-05-24T04:32:12Z

Kangz: /* nokeepaspect */

[[File:Minimap_atcshd_example.png|thumb|200px|A basic minimap for atcshd]]

Minimaps have two purposes: help the player navigate some very large and confusing map and promote teamplay by showing the location of your teammates. They are created by the mapper and are part of the assets of a map. They follow more or less [[Feature_Proposals/Minimap|the old design document]]. Each minimap consists of a number of zones: in each region of the map a different image can be used, for example to represent the different floors of a facility.

== How to create a minimap: the quick and simple method ==

* Open the map using netradiant.
* Go in the Build menu and select Customize.
* Search for the minimap command line and set the number after -size to a large value (e.g. 512).
* Go in the Build menu and build the minimap.
* Note the numbers in the log window appearing after texcoord_size
* Put the resulting tga file in the minimaps/ folder.
* Create a file minimaps/<name of your map>.minimap and write it using the following template (by replacing 1, 2, 4 and 5 by the first, second, fourth and fifth number appearing after texcoord_size):
{
zone {
bounds -100000 -100000 -100000 100000 100000 100000
image "minimaps/<mapname>" 1 2 4 5
}
}
* Load your map and enjoy that magnificient minimap.

== How to create a minimap: tutorial using q3map2 ==

q3map2 can create minimaps from the .map file. These minimaps basically show the solid walls by checking how much solid brush is under each pixel: a wall has a big intersection with the vertical line but a floor not so much.

=== Configuring netRadiant ===

Before you start generating images you probably want to change the options given to q3map2 and make sure the image size is at least 512. To do that go on the Build menu and select Customize. Below is a very simple sample configuration for a minimap build.

[[File:Minimap_customize_options.png]]

You can use the q3map2 minimap options list below to customize the output. A good default build line is

Whatever, need to find out

=== Creating the images ===

Running the minimap build at this point will create a single minimap image for the whole map. You might want to create several images either because the maps is too cluttered (many intricated levels) either because the map is too large.

[[File:Minimap_atcshd_cutted.png|thumb|200px|atcshd with the center missing and a filled door]]

If you simply want to cut the minimap in several part, first try to make a bigger image (image with a size of 2048 should work in the engine) with a bigger ''globalScale'' parameter in your minimap config file. If you aren't happy with the result, try using the ''minmax'' switch for the minimap build to render a smaller part; make sure the different images overlap so that there is a smooth transition ingame.

When the map is too cluttered, the only solution is too cut parts of it and make differents zones for the different levels of your map. To do this remove all the parts you don't want to see and fill the "holes" left in you map with a solid brush (to avoid leaks).

=== Creating the minimap file ===

== Minimap file manual ==

A minimap file has the following structure (with at least one zone block)

{
<zone blocks or global parameters>
}

With each zone block with the following structure

zone {
<zone-specific parameters>
}

The zone are used to show different images in different regions of the map. When a player gets outside the bounds of the zone he is currently on, zones will be searched in the order defined in the file to choose the new image. If no zone fits then the last one defined will be used. This way you can define a default zone by putting at the end of the minimap file the following zone block:

zone {
bounds 0.0 0.0 0.0 0.0 0.0 0.0
<other parameters>
}

=== Global parameters ===

==== backgroundColor ====

backgroundColor <float r> <float g> <float b> <float a>

Chooses the color of the background of the map. Defaults to opaque black. If the map has been generated by q3map2 you most probably to leave it to opaque black. You can use a transparent background but it won't play well with semi-transparent maps; you'd better use a binary transparency and a semi-transparent background color.

==== globalScale ====

globalScale <float ratio>

Multiplies the size of the minimap and all the minimap objects by the given ratio: it is a sort of global zoom of the map. Defaults to 1.0.

=== Zone-specific parameters ===

Each zone block must have a bounds and image parameter or an error will be generated.

==== bounds ====

bounds <float xmin> <float ymin> <float zmin> <float xmax> <float ymax> <float zmax>

Defines in which "box volume" this zone is in effect. The arguments are world units and must be in that order (xmin < xmax, ...)

==== image ====

image <filename> <float xmin> <float ymin> <float xmax> <float ymax>

Defines which image to use and what rectangular area that image represents in the world. The four position arguments are in world units; they are the X and Y bounds of a brush that would cover the whole minimap. The filename should ideally be without the file extension (you could theoretically use a shader name too).

==== scale ====

scale <float ratio>

When the player is inside the zone, multiplies the size of the minimap and all the minimap objects by the given ratio. Defaults to 1.0.

== q3map2 minimap options ==

The q3map2 commandline looks like this in netRadiant:

[q3map2] -minimap <switches> "[MapFile]"

=== "Color" switches ===

==== autolevel ====

-autolevel

Tries to find automatically the right contrast and brightness values to use. Defaults to off.

==== boost ====

-boost <float b>

Changes the gamma of the resulting image using the following formula color' = color / ((b - 1) * color + 1). Defaults to 1.0. (the pass is made before the contrast/sharpen pass)

==== contrast ====

-contrast <float c>

Changes the contrast of the resulting image using the following formula color' = color * c + sharpen. Defaults to 1.0. (the pass is made after the boost pass)

==== noautolevel ====

-noautolevel

Will not try to find automatically the right contrast and brightness values to use. Defaults to on.

==== sharpen ====

-sharpen <float s>

Changes the brightness of the resulting image using the following formula color' = color * contrast + s. Defaults to 1.0. (the pass is made after the boost pass)

=== Output control switches ===

==== black ====

-black

Writes the resulting minimap as a black TGA file with levels of transparency. (It was not tested yet, maybe the engine will treat it as a completely black image)

==== gray ====

-gray

Writes the image as a GRAY8 TGA file.

==== o ====

-o <filename.tga>

THIS IS SET AUTOMATICALLY BY NETRADIANT. Sets the filename of the output file.

==== white ====

-white

Writes the resulting minimap as a white TGA file with levels of transparency. (It seems our engine converts it in levels of gray)

=== Region switches ===

==== border ====

-border <float ratio>

Adds borders to the image with size (image_size * ratio). Defaults to 0.0 (at least for Tremulous).

==== keepaspect ====

-keepaspect

Makes it so that the resulting image will keep the aspect ratio (a square will stay a square) by adding empty space. Defaults to on.

==== minmax ====

-minmax <float xmin> <float ymin> <float zmin> <float xmax> <float ymax> <float zmax>

Restricts the minimap to the part of the map contained in the box defined by the parameters. By default this box is the bounding box of the whole map.

==== nokeepaspect ====

-nokeepaspect

THIS IS NOT SUPPORTED BY THE UNVANQUISHED MINIMAPS and included for completeness only. Allows q3map2 to not preserve the aspect ratio (in some way). Defaults to off.

==== size ====

-size <int N>

Changes the sizes of the resulting image to NxN. defaults to 512 for Tremulous.

=== Sampling switches ===

==== random ====

-random <int n>

Makes the minimap generation use random samples and sets the number of samples to take for each pixel of the minimap. Defaults to on and 1.

==== samples ====

-samples <int n>

Makes the minimap generation use ordered samples and sets the number of samples to take for each pixel of the minimap. Defaults to off and 1.

Tutorials/Minimap

2013-05-24T04:31:45Z

Kangz: Add q3map2 minimap doc

[[File:Minimap_atcshd_example.png|thumb|200px|A basic minimap for atcshd]]

Minimaps have two purposes: help the player navigate some very large and confusing map and promote teamplay by showing the location of your teammates. They are created by the mapper and are part of the assets of a map. They follow more or less [[Feature_Proposals/Minimap|the old design document]]. Each minimap consists of a number of zones: in each region of the map a different image can be used, for example to represent the different floors of a facility.

== How to create a minimap: the quick and simple method ==

* Open the map using netradiant.
* Go in the Build menu and select Customize.
* Search for the minimap command line and set the number after -size to a large value (e.g. 512).
* Go in the Build menu and build the minimap.
* Note the numbers in the log window appearing after texcoord_size
* Put the resulting tga file in the minimaps/ folder.
* Create a file minimaps/<name of your map>.minimap and write it using the following template (by replacing 1, 2, 4 and 5 by the first, second, fourth and fifth number appearing after texcoord_size):
{
zone {
bounds -100000 -100000 -100000 100000 100000 100000
image "minimaps/<mapname>" 1 2 4 5
}
}
* Load your map and enjoy that magnificient minimap.

== How to create a minimap: tutorial using q3map2 ==

q3map2 can create minimaps from the .map file. These minimaps basically show the solid walls by checking how much solid brush is under each pixel: a wall has a big intersection with the vertical line but a floor not so much.

=== Configuring netRadiant ===

Before you start generating images you probably want to change the options given to q3map2 and make sure the image size is at least 512. To do that go on the Build menu and select Customize. Below is a very simple sample configuration for a minimap build.

[[File:Minimap_customize_options.png]]

You can use the q3map2 minimap options list below to customize the output. A good default build line is

Whatever, need to find out

=== Creating the images ===

Running the minimap build at this point will create a single minimap image for the whole map. You might want to create several images either because the maps is too cluttered (many intricated levels) either because the map is too large.

[[File:Minimap_atcshd_cutted.png|thumb|200px|atcshd with the center missing and a filled door]]

If you simply want to cut the minimap in several part, first try to make a bigger image (image with a size of 2048 should work in the engine) with a bigger ''globalScale'' parameter in your minimap config file. If you aren't happy with the result, try using the ''minmax'' switch for the minimap build to render a smaller part; make sure the different images overlap so that there is a smooth transition ingame.

When the map is too cluttered, the only solution is too cut parts of it and make differents zones for the different levels of your map. To do this remove all the parts you don't want to see and fill the "holes" left in you map with a solid brush (to avoid leaks).

=== Creating the minimap file ===

== Minimap file manual ==

A minimap file has the following structure (with at least one zone block)

{
<zone blocks or global parameters>
}

With each zone block with the following structure

zone {
<zone-specific parameters>
}

The zone are used to show different images in different regions of the map. When a player gets outside the bounds of the zone he is currently on, zones will be searched in the order defined in the file to choose the new image. If no zone fits then the last one defined will be used. This way you can define a default zone by putting at the end of the minimap file the following zone block:

zone {
bounds 0.0 0.0 0.0 0.0 0.0 0.0
<other parameters>
}

=== Global parameters ===

==== backgroundColor ====

backgroundColor <float r> <float g> <float b> <float a>

Chooses the color of the background of the map. Defaults to opaque black. If the map has been generated by q3map2 you most probably to leave it to opaque black. You can use a transparent background but it won't play well with semi-transparent maps; you'd better use a binary transparency and a semi-transparent background color.

==== globalScale ====

globalScale <float ratio>

Multiplies the size of the minimap and all the minimap objects by the given ratio: it is a sort of global zoom of the map. Defaults to 1.0.

=== Zone-specific parameters ===

Each zone block must have a bounds and image parameter or an error will be generated.

==== bounds ====

bounds <float xmin> <float ymin> <float zmin> <float xmax> <float ymax> <float zmax>

Defines in which "box volume" this zone is in effect. The arguments are world units and must be in that order (xmin < xmax, ...)

==== image ====

image <filename> <float xmin> <float ymin> <float xmax> <float ymax>

Defines which image to use and what rectangular area that image represents in the world. The four position arguments are in world units; they are the X and Y bounds of a brush that would cover the whole minimap. The filename should ideally be without the file extension (you could theoretically use a shader name too).

==== scale ====

scale <float ratio>

When the player is inside the zone, multiplies the size of the minimap and all the minimap objects by the given ratio. Defaults to 1.0.

== q3map2 minimap options ==

The q3map2 commandline looks like this in netRadiant:

[q3map2] -minimap <switches> "[MapFile]"

=== "Color" switches ===

==== autolevel ====

-autolevel

Tries to find automatically the right contrast and brightness values to use. Defaults to off.

==== boost ====

-boost <float b>

Changes the gamma of the resulting image using the following formula color' = color / ((b - 1) * color + 1). Defaults to 1.0. (the pass is made before the contrast/sharpen pass)

==== contrast ====

-contrast <float c>

Changes the contrast of the resulting image using the following formula color' = color * c + sharpen. Defaults to 1.0. (the pass is made after the boost pass)

==== noautolevel ====

-noautolevel

Will not try to find automatically the right contrast and brightness values to use. Defaults to on.

==== sharpen ====

-sharpen <float s>

Changes the brightness of the resulting image using the following formula color' = color * contrast + s. Defaults to 1.0. (the pass is made after the boost pass)

=== Output control switches ===

==== black ====

-black

Writes the resulting minimap as a black TGA file with levels of transparency. (It was not tested yet, maybe the engine will treat it as a completely black image)

==== gray ====

-gray

Writes the image as a GRAY8 TGA file.

==== o ====

-o <filename.tga>

THIS IS SET AUTOMATICALLY BY NETRADIANT. Sets the filename of the output file.

==== white ====

-white

Writes the resulting minimap as a white TGA file with levels of transparency. (It seems our engine converts it in levels of gray)

=== Region switches ===

==== border ====

-border <float ratio>

Adds borders to the image with size (image_size * ratio). Defaults to 0.0 (at least for Tremulous).

==== keepaspect ====

-keepaspect

Makes it so that the resulting image will keep the aspect ratio (a square will stay a square) by adding empty space. Defaults to on.

==== minmax ====

-minmax <float xmin> <float ymin> <float zmin> <float xmax> <float ymax> <float zmax>

Restricts the minimap to the part of the map contained in the box defined by the parameters. By default this box is the bounding box of the whole map.

==== nokeepaspect ====

-nokeepaspect

THIS IS NOT SUPPORT BY THE UNVANQUISHED MINIMAPS and included for completeness only. Allows q3map2 to not preserve the aspect ratio (in some way). Defaults to off.

==== size ====

-size <int N>

Changes the sizes of the resulting image to NxN. defaults to 512 for Tremulous.

=== Sampling switches ===

==== random ====

-random <int n>

Makes the minimap generation use random samples and sets the number of samples to take for each pixel of the minimap. Defaults to on and 1.

==== samples ====

-samples <int n>

Makes the minimap generation use ordered samples and sets the number of samples to take for each pixel of the minimap. Defaults to off and 1.

Talk:Coding convention

2013-05-22T21:07:22Z

Kangz:

I have added some conventions from the readings of the code, but I might be wrong, especially about spaces in ifs. I have noticed that some places uses writings like
if ( foo )
and some other with
if( bar )
so some confirmations could be useful.

There is not clearly defined convention for the code, although id software probably had one (doom3's is on the web). If we are to write a coding convention document, I'd rather poll everyone to see what we would like to have, instead of sticking to the old, implicit one. For example I'd change the indent style to K&R or 1TBS. Also when you use a talk page you can put a signature (<nowiki>--~~~</nowiki>) so that we know who said what. --[[User:Kangz|Kangz]] ([[User talk:Kangz|talk]])

Tutorials/Minimap

2013-05-22T07:42:58Z

Kangz: Write a part of the full tutorial

File:Minimap atcshd example.png

2013-05-22T07:41:28Z

Kangz: The basic minimap created by q3map2 for atcshd

The basic minimap created by q3map2 for atcshd

File:Minimap atcshd cutted.png

2013-05-22T07:37:12Z

Kangz: AtcsHD opened in radiant with the bunker part missing and the hole in the geometry filled with a brush

AtcsHD opened in radiant with the bunker part missing and the hole in the geometry filled with a brush