Technical Documentation

From Unvanquished
Revision as of 08:21, 18 April 2013 by Velociostrich (Talk | contribs) (Add information for new people, misc. cleanup)

Jump to: navigation, search

If you have a question that is not answered here, you can always hop on the programming sub-forums or IRC.

Getting Started

If you have not already, go get the code, read up on your options for development environments, and 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:

There are also very detailed instructions on 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 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 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 guidelines for contributing code as well as documentation on coding conventions.


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

  • librocket — 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.
  • bots2 — New bot code, using behavior trees.

Language Oddities

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

Source Code & Data Structure

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

Program Entry Point

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

Lag Compensation

Daemon uses Neil "haste" Toronto's Unlagged mod.

Data Files

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

Game Logic

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


Buildable information is encapsulated in the cg_buildables array (declared in src/gamelogic/cgame/cg_main.c)

Constants used to define gamelogic variables are in src/gamelogic/game/tremulous.h.


  • buildableInfo_t — Encapsulates data associated with buildables (sounds, animations, etc.).
  • buildable_t — An enumeration of all buildable types.
  • buildableAttributes_t — Encapsulates gameplay information associated with buildables. There is an array of these called bg_buildableList.


Server game state initialization occurs in G_InitGame() in src/gamelogic/game/g_main.c.

Particle & Trail System

For now, please see the Tremulous documentation.

GL3 Renderer

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


  • There is some (highly experimental and untested) Direct X code mixed in the modern OpenGL renderer code.

Shaders are implemented as subclasses of the GLShader class. All are defined in src/engine/rendererGL/gl_shader.h.

  • Compiled GLSL shader files (located in the hard-coded location "glsl/" with the .bin filename extension) are read by GLShader::LoadShaderBinary().
  • All possible parameters (what OpenGL calls "uniform variables") that may be passed to a shader are enumerated in the shaderProgram_t structure in src/engine/rendererGL/tr_local.h.
  • Shaders with duplicate functionality is achieved with multiple inheritance. E.g., gl_genericShader is of type GLShader_generic* which derives from the following classes:
    • GLShader
    • u_ColorMap
    • u_ColorTextureMatrix
    • u_ViewOrigin
    • u_AlphaTest
    • u_ModelMatrix
    • u_ModelViewProjectionMatrix
    • u_ColorModulate
    • u_Color
    • u_BoneMatrix
    • u_VertexInterpolation
    • u_PortalPlane
    • GLDeformStage
    • GLCompileMacro_USE_ALPHA_TESTING
  • GLSL shaders may be found in main/glsl/. Please see the full article for a complete listing.

Helper Classes

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

Uniform Variables

Uniform variables are enumerated in the shaderProgram_t structure in src/engine/rendererGL/tr_local.h, and are controlled by classes beginning with the u_ prefix:

  • u_BoneMatrix — Provides the convenience method SetUniform_BoneMatrix.

Compile Macros

  • GLCompileMacro_TWOSIDED
  • GLCompileMacro_EYE_OUTSIDE
  • GLCompileMacro_USE_SHADOWING
  • GLCompileMacro_USE_GBUFFER


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

Alternatively, OpenGL API reference documentation is available online:

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



General Game Development