Unvanquished - User contributions [en-gb]

Technical Documentation

2021-07-10T19:27:03Z

The White Lion: /* Source Code Tree and File Descriptions */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src/</code> - engine source code
*** <code>shared/</code>
*** <code>server/</code>
**** <code>sg_api</code> - contains definitions for the VM to engine function-procedures
**** <code>CommonProxies</code> - proxy interface to the VM, has trap calls for sending messages to the VM
*** <code>common/</code>
**** <code>Cvar</code> - the proxy interface for console variables
**** <code>Debugger</code> - contains a routine to detect if a debugger is attached to the process
**** <code>FileSystem</code> - interface to use the host filesystem through the VM
**** <code>KeyIdentification</code> - contains an association table (unordered map) that links a keyboard key value with a string descriptor
**** <code>LineEditData</code> - ?
**** <code>Log</code> - filesystem logging
**** <code>IPC/</code>
***** <code>Common</code> - common definitions for all IPC methods
***** <code>Command</code> - the inter-process communication command buffer
***** <code>Channel</code> - contains the inter-process communication namespace and engine-VM messaging functions
***** <code>Primitives</code> - routines for the IPC VM-engine socket
**** <code>CM/</code> - related to game collisions and map loading
***** <code>cm_local</code>
***** <code>cm_patch</code>
***** <code>cm_polylib</code>
***** <code>cm_public</code>
**** <code>Color</code> - related to colors
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
***** <code>q_shared.cpp</code> - stateless support routines that are included in each code module
***** <code>q_math</code> - stateless support routines that are included in each code module, related to math operations
***** <code>q_Unicode</code> - Unicode & UTF-8 handling
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
***** <code>sv_sgame</code> - interface to the game module
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - the sources for the game-logic modules, both Client and Server
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib/</code> - directory containing sources for bot AI
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>Components/</code> - directory containing the sources for the CBSE entity components
***** <code>AcidTubeComponent</code> - code for Acid Tube entity component
***** <code>AlienBuildableComponent</code> - code for alien buildable entity component
***** <code>AlienClassComponent</code> - code for alien class entity component
***** <code>ArmourComponent</code> - the armour entity component class
***** <code>ArmouryComponent</code> - the armory entity component class
***** <code>BarricadeComponent</code> - the code for the barricade entity component
***** <code>BoosterComponent</code> - the booster component entity component class
***** <code>BuildableComponent</code> - code for the buildable entity component class
***** <code>DeferredFreeingComponent</code> - code for the deferred freeing component
***** <code>DrillComponent</code> - code for the drill entity component
***** <code>EggComponent</code> - code for the egg entity component
***** <code>HealthComponent</code> - the health component for a CBSE entity
***** <code>HiveComponent</code> - the hive component for a CBSE entity
***** <code>HumanBuildableComponent</code> - the human buildable component for a CBSE entity
***** <code>HumanClassComponent</code> - the human class component for a CBSE entity
***** <code>IgnitableComponent</code> - the ignitable component for a CBSE entity
***** <code>KnockbackComponent</code> - the knockback component for a CBSE entity
***** <code>LeechComponent</code> - the leech component for a CBSE entity
***** <code>MainBuildableComponent</code> - the main buildable component for a CBSE entity
***** <code>MedipadComponent</code> - the medi pad component for a CBSE entity
***** <code>MGTurretComponent</code> - the MG turret component for a CBSE entity
***** <code>MiningComponent</code> - the mining component for a CBSE entity
***** <code>OvermindComponent</code> - the overmind component for a CBSE entity
***** <code>ReactorComponent</code> - the reactor component for a CBSE entity
***** <code>RocketpodComponent</code> - the rocket pod component for a CBSE entity
**** <code>CBSE</code> - the files containing the core entity declarations and definitions
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>Assert</code> - daemon engine specific assert code
**** <code>Clustering</code> - has code related to the (literal) clustering of base buildables
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
**** <code>sg_api</code> - contains the interface for the server game-logic module to handle messages received from the VM
**** <code>Entities</code> - contains helper routines for CBSE entity components
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
**** <code>parse</code> - parsing game script files
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The game-logic modules are themselves programs and have a main entrance function of <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function. This main function is the first function called in the program and begins the initialization process. The virtual machine starts game-logic module execution by creating a sub-process via the operating system with a call to the function ''CreateProcessW()'' (see daemon/src/engine/framework/VirtualMachine.cpp at line 152 inside the function ''InternalLoadModule'').

The server game is not started until a map is loaded.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

'''The Game Frame:'''
The game frame is a single moment or instant of the game. For the client, the game frame is a single render frame of the game. Gameplay and game objects are processed on a frame basis, the game is updated to the current frame and then presented to the player as an immediate moment in the game. This is the purpose of the function G_RunFrame, as in Game_RunFrame. This function does all '''''game updates''''' for console variables, for game entities, and entity events, and etc. See the function definition for G_RunFrame of sg_main.cpp for implementation details.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-10T18:15:14Z

The White Lion: /* Program Ignition and Initialization */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src/</code> - engine source code
*** <code>shared/</code>
*** <code>server/</code>
**** <code>sg_api</code> - contains definitions for the VM to engine function-procedures
**** <code>CommonProxies</code> - proxy interface to the VM, has trap calls for sending messages to the VM
*** <code>common/</code>
**** <code>Cvar</code> - the proxy interface for console variables
**** <code>Debugger</code> - contains a routine to detect if a debugger is attached to the process
**** <code>FileSystem</code> - interface to use the host filesystem through the VM
**** <code>KeyIdentification</code> - contains an association table (unordered map) that links a keyboard key value with a string descriptor
**** <code>LineEditData</code> - ?
**** <code>Log</code> - filesystem logging
**** <code>IPC/</code>
***** <code>Common</code> - common definitions for all IPC methods
***** <code>Command</code> - the inter-process communication command buffer
***** <code>Channel</code> - contains the inter-process communication namespace and engine-VM messaging functions
***** <code>Primitives</code> - routines for the IPC VM-engine socket
**** <code>CM/</code> - related to game collisions and map loading
***** <code>cm_local</code>
***** <code>cm_patch</code>
***** <code>cm_polylib</code>
***** <code>cm_public</code>
**** <code>Color</code> - related to colors
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
***** <code>q_shared.cpp</code> - stateless support routines that are included in each code module
***** <code>q_math</code> - stateless support routines that are included in each code module, related to math operations
***** <code>q_Unicode</code> - Unicode & UTF-8 handling
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - the sources for the game-logic modules, both Client and Server
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib/</code> - directory containing sources for bot AI
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>Components/</code> - directory containing the sources for the CBSE entity components
***** <code>AcidTubeComponent</code> - code for Acid Tube entity component
***** <code>AlienBuildableComponent</code> - code for alien buildable entity component
***** <code>AlienClassComponent</code> - code for alien class entity component
***** <code>ArmourComponent</code> - the armour entity component class
***** <code>ArmouryComponent</code> - the armory entity component class
***** <code>BarricadeComponent</code> - the code for the barricade entity component
***** <code>BoosterComponent</code> - the booster component entity component class
***** <code>BuildableComponent</code> - code for the buildable entity component class
***** <code>DeferredFreeingComponent</code> - code for the deferred freeing component
***** <code>DrillComponent</code> - code for the drill entity component
***** <code>EggComponent</code> - code for the egg entity component
***** <code>HealthComponent</code> - the health component for a CBSE entity
***** <code>HiveComponent</code> - the hive component for a CBSE entity
***** <code>HumanBuildableComponent</code> - the human buildable component for a CBSE entity
***** <code>HumanClassComponent</code> - the human class component for a CBSE entity
***** <code>IgnitableComponent</code> - the ignitable component for a CBSE entity
***** <code>KnockbackComponent</code> - the knockback component for a CBSE entity
***** <code>LeechComponent</code> - the leech component for a CBSE entity
***** <code>MainBuildableComponent</code> - the main buildable component for a CBSE entity
***** <code>MedipadComponent</code> - the medi pad component for a CBSE entity
***** <code>MGTurretComponent</code> - the MG turret component for a CBSE entity
***** <code>MiningComponent</code> - the mining component for a CBSE entity
***** <code>OvermindComponent</code> - the overmind component for a CBSE entity
***** <code>ReactorComponent</code> - the reactor component for a CBSE entity
***** <code>RocketpodComponent</code> - the rocket pod component for a CBSE entity
**** <code>CBSE</code> - the files containing the core entity declarations and definitions
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>Assert</code> - daemon engine specific assert code
**** <code>Clustering</code> - has code related to the (literal) clustering of base buildables
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
**** <code>sg_api</code> - contains the interface for the server game-logic module to handle messages received from the VM
**** <code>Entities</code> - contains helper routines for CBSE entity components
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
**** <code>parse</code> - parsing game script files
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The game-logic modules are themselves programs and have a main entrance function of <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function. This main function is the first function called in the program and begins the initialization process. The virtual machine starts game-logic module execution by creating a sub-process via the operating system with a call to the function ''CreateProcessW()'' (see daemon/src/engine/framework/VirtualMachine.cpp at line 152 inside the function ''InternalLoadModule'').

The server game is not started until a map is loaded.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

'''The Game Frame:'''
The game frame is a single moment or instant of the game. For the client, the game frame is a single render frame of the game. Gameplay and game objects are processed on a frame basis, the game is updated to the current frame and then presented to the player as an immediate moment in the game. This is the purpose of the function G_RunFrame, as in Game_RunFrame. This function does all '''''game updates''''' for console variables, for game entities, and entity events, and etc. See the function definition for G_RunFrame of sg_main.cpp for implementation details.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-10T16:55:38Z

The White Lion: /* Program Ignition and Initialization */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src/</code> - engine source code
*** <code>shared/</code>
*** <code>server/</code>
**** <code>sg_api</code> - contains definitions for the VM to engine function-procedures
**** <code>CommonProxies</code> - proxy interface to the VM, has trap calls for sending messages to the VM
*** <code>common/</code>
**** <code>Cvar</code> - the proxy interface for console variables
**** <code>Debugger</code> - contains a routine to detect if a debugger is attached to the process
**** <code>FileSystem</code> - interface to use the host filesystem through the VM
**** <code>KeyIdentification</code> - contains an association table (unordered map) that links a keyboard key value with a string descriptor
**** <code>LineEditData</code> - ?
**** <code>Log</code> - filesystem logging
**** <code>IPC/</code>
***** <code>Common</code> - common definitions for all IPC methods
***** <code>Command</code> - the inter-process communication command buffer
***** <code>Channel</code> - contains the inter-process communication namespace and engine-VM messaging functions
***** <code>Primitives</code> - routines for the IPC VM-engine socket
**** <code>CM/</code> - related to game collisions and map loading
***** <code>cm_local</code>
***** <code>cm_patch</code>
***** <code>cm_polylib</code>
***** <code>cm_public</code>
**** <code>Color</code> - related to colors
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
***** <code>q_shared.cpp</code> - stateless support routines that are included in each code module
***** <code>q_math</code> - stateless support routines that are included in each code module, related to math operations
***** <code>q_Unicode</code> - Unicode & UTF-8 handling
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - the sources for the game-logic modules, both Client and Server
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib/</code> - directory containing sources for bot AI
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>Components/</code> - directory containing the sources for the CBSE entity components
***** <code>AcidTubeComponent</code> - code for Acid Tube entity component
***** <code>AlienBuildableComponent</code> - code for alien buildable entity component
***** <code>AlienClassComponent</code> - code for alien class entity component
***** <code>ArmourComponent</code> - the armour entity component class
***** <code>ArmouryComponent</code> - the armory entity component class
***** <code>BarricadeComponent</code> - the code for the barricade entity component
***** <code>BoosterComponent</code> - the booster component entity component class
***** <code>BuildableComponent</code> - code for the buildable entity component class
***** <code>DeferredFreeingComponent</code> - code for the deferred freeing component
***** <code>DrillComponent</code> - code for the drill entity component
***** <code>EggComponent</code> - code for the egg entity component
***** <code>HealthComponent</code> - the health component for a CBSE entity
***** <code>HiveComponent</code> - the hive component for a CBSE entity
***** <code>HumanBuildableComponent</code> - the human buildable component for a CBSE entity
***** <code>HumanClassComponent</code> - the human class component for a CBSE entity
***** <code>IgnitableComponent</code> - the ignitable component for a CBSE entity
***** <code>KnockbackComponent</code> - the knockback component for a CBSE entity
***** <code>LeechComponent</code> - the leech component for a CBSE entity
***** <code>MainBuildableComponent</code> - the main buildable component for a CBSE entity
***** <code>MedipadComponent</code> - the medi pad component for a CBSE entity
***** <code>MGTurretComponent</code> - the MG turret component for a CBSE entity
***** <code>MiningComponent</code> - the mining component for a CBSE entity
***** <code>OvermindComponent</code> - the overmind component for a CBSE entity
***** <code>ReactorComponent</code> - the reactor component for a CBSE entity
***** <code>RocketpodComponent</code> - the rocket pod component for a CBSE entity
**** <code>CBSE</code> - the files containing the core entity declarations and definitions
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>Assert</code> - daemon engine specific assert code
**** <code>Clustering</code> - has code related to the (literal) clustering of base buildables
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
**** <code>sg_api</code> - contains the interface for the server game-logic module to handle messages received from the VM
**** <code>Entities</code> - contains helper routines for CBSE entity components
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
**** <code>parse</code> - parsing game script files
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The game-logic modules are themselves programs and have a main entrance function of <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function. This main function is the first function called in the program and begins the initialization process. The virtual machine starts game-logic module execution by creating a sub-process via the operating system with a call to the function ''CreateProcessW()'' (see daemon/src/engine/framework/VirtualMachine.cpp at line 152 inside the function ''InternalLoadModule'').

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

'''The Game Frame:'''
The game frame is a single moment or instant of the game. For the client, the game frame is a single render frame of the game. Gameplay and game objects are processed on a frame basis, the game is updated to the current frame and then presented to the player as an immediate moment in the game. This is the purpose of the function G_RunFrame, as in Game_RunFrame. This function does all '''''game updates''''' for console variables, for game entities, and entity events, and etc. See the function definition for G_RunFrame of sg_main.cpp for implementation details.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-09T05:22:17Z

The White Lion: /* sg_main.cpp */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src/</code> - engine source code
*** <code>shared/</code>
*** <code>server/</code>
**** <code>sg_api</code> - contains definitions for the VM to engine function-procedures
**** <code>CommonProxies</code> - proxy interface to the VM, has trap calls for sending messages to the VM
*** <code>common/</code>
**** <code>Cvar</code> - the proxy interface for console variables
**** <code>Debugger</code> - contains a routine to detect if a debugger is attached to the process
**** <code>FileSystem</code> - interface to use the host filesystem through the VM
**** <code>KeyIdentification</code> - contains an association table (unordered map) that links a keyboard key value with a string descriptor
**** <code>LineEditData</code> - ?
**** <code>Log</code> - filesystem logging
**** <code>IPC/</code>
***** <code>Common</code> - common definitions for all IPC methods
***** <code>Command</code> - the inter-process communication command buffer
***** <code>Channel</code> - contains the inter-process communication namespace and engine-VM messaging functions
***** <code>Primitives</code> - routines for the IPC VM-engine socket
**** <code>CM/</code> - related to game collisions and map loading
***** <code>cm_local</code>
***** <code>cm_patch</code>
***** <code>cm_polylib</code>
***** <code>cm_public</code>
**** <code>Color</code> - related to colors
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
***** <code>q_shared.cpp</code> - stateless support routines that are included in each code module
***** <code>q_math</code> - stateless support routines that are included in each code module, related to math operations
***** <code>q_Unicode</code> - Unicode & UTF-8 handling
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - the sources for the game-logic modules, both Client and Server
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib/</code> - directory containing sources for bot AI
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>Components/</code> - directory containing the sources for the CBSE entity components
***** <code>AcidTubeComponent</code> - code for Acid Tube entity component
***** <code>AlienBuildableComponent</code> - code for alien buildable entity component
***** <code>AlienClassComponent</code> - code for alien class entity component
***** <code>ArmourComponent</code> - the armour entity component class
***** <code>ArmouryComponent</code> - the armory entity component class
***** <code>BarricadeComponent</code> - the code for the barricade entity component
***** <code>BoosterComponent</code> - the booster component entity component class
***** <code>BuildableComponent</code> - code for the buildable entity component class
***** <code>DeferredFreeingComponent</code> - code for the deferred freeing component
***** <code>DrillComponent</code> - code for the drill entity component
***** <code>EggComponent</code> - code for the egg entity component
***** <code>HealthComponent</code> - the health component for a CBSE entity
***** <code>HiveComponent</code> - the hive component for a CBSE entity
***** <code>HumanBuildableComponent</code> - the human buildable component for a CBSE entity
***** <code>HumanClassComponent</code> - the human class component for a CBSE entity
***** <code>IgnitableComponent</code> - the ignitable component for a CBSE entity
***** <code>KnockbackComponent</code> - the knockback component for a CBSE entity
***** <code>LeechComponent</code> - the leech component for a CBSE entity
***** <code>MainBuildableComponent</code> - the main buildable component for a CBSE entity
***** <code>MedipadComponent</code> - the medi pad component for a CBSE entity
***** <code>MGTurretComponent</code> - the MG turret component for a CBSE entity
***** <code>MiningComponent</code> - the mining component for a CBSE entity
***** <code>OvermindComponent</code> - the overmind component for a CBSE entity
***** <code>ReactorComponent</code> - the reactor component for a CBSE entity
***** <code>RocketpodComponent</code> - the rocket pod component for a CBSE entity
**** <code>CBSE</code> - the files containing the core entity declarations and definitions
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>Assert</code> - daemon engine specific assert code
**** <code>Clustering</code> - has code related to the (literal) clustering of base buildables
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
**** <code>sg_api</code> - contains the interface for the server game-logic module to handle messages received from the VM
**** <code>Entities</code> - contains helper routines for CBSE entity components
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
**** <code>parse</code> - parsing game script files
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

'''The Game Frame:'''
The game frame is a single moment or instant of the game. For the client, the game frame is a single render frame of the game. Gameplay and game objects are processed on a frame basis, the game is updated to the current frame and then presented to the player as an immediate moment in the game. This is the purpose of the function G_RunFrame, as in Game_RunFrame. This function does all '''''game updates''''' for console variables, for game entities, and entity events, and etc. See the function definition for G_RunFrame of sg_main.cpp for implementation details.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-09T05:09:58Z

The White Lion: /* sg_main.cpp */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src/</code> - engine source code
*** <code>shared/</code>
*** <code>server/</code>
**** <code>sg_api</code> - contains definitions for the VM to engine function-procedures
**** <code>CommonProxies</code> - proxy interface to the VM, has trap calls for sending messages to the VM
*** <code>common/</code>
**** <code>Cvar</code> - the proxy interface for console variables
**** <code>Debugger</code> - contains a routine to detect if a debugger is attached to the process
**** <code>FileSystem</code> - interface to use the host filesystem through the VM
**** <code>KeyIdentification</code> - contains an association table (unordered map) that links a keyboard key value with a string descriptor
**** <code>LineEditData</code> - ?
**** <code>Log</code> - filesystem logging
**** <code>IPC/</code>
***** <code>Common</code> - common definitions for all IPC methods
***** <code>Command</code> - the inter-process communication command buffer
***** <code>Channel</code> - contains the inter-process communication namespace and engine-VM messaging functions
***** <code>Primitives</code> - routines for the IPC VM-engine socket
**** <code>CM/</code> - related to game collisions and map loading
***** <code>cm_local</code>
***** <code>cm_patch</code>
***** <code>cm_polylib</code>
***** <code>cm_public</code>
**** <code>Color</code> - related to colors
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
***** <code>q_shared.cpp</code> - stateless support routines that are included in each code module
***** <code>q_math</code> - stateless support routines that are included in each code module, related to math operations
***** <code>q_Unicode</code> - Unicode & UTF-8 handling
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - the sources for the game-logic modules, both Client and Server
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib/</code> - directory containing sources for bot AI
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>Components/</code> - directory containing the sources for the CBSE entity components
***** <code>AcidTubeComponent</code> - code for Acid Tube entity component
***** <code>AlienBuildableComponent</code> - code for alien buildable entity component
***** <code>AlienClassComponent</code> - code for alien class entity component
***** <code>ArmourComponent</code> - the armour entity component class
***** <code>ArmouryComponent</code> - the armory entity component class
***** <code>BarricadeComponent</code> - the code for the barricade entity component
***** <code>BoosterComponent</code> - the booster component entity component class
***** <code>BuildableComponent</code> - code for the buildable entity component class
***** <code>DeferredFreeingComponent</code> - code for the deferred freeing component
***** <code>DrillComponent</code> - code for the drill entity component
***** <code>EggComponent</code> - code for the egg entity component
***** <code>HealthComponent</code> - the health component for a CBSE entity
***** <code>HiveComponent</code> - the hive component for a CBSE entity
***** <code>HumanBuildableComponent</code> - the human buildable component for a CBSE entity
***** <code>HumanClassComponent</code> - the human class component for a CBSE entity
***** <code>IgnitableComponent</code> - the ignitable component for a CBSE entity
***** <code>KnockbackComponent</code> - the knockback component for a CBSE entity
***** <code>LeechComponent</code> - the leech component for a CBSE entity
***** <code>MainBuildableComponent</code> - the main buildable component for a CBSE entity
***** <code>MedipadComponent</code> - the medi pad component for a CBSE entity
***** <code>MGTurretComponent</code> - the MG turret component for a CBSE entity
***** <code>MiningComponent</code> - the mining component for a CBSE entity
***** <code>OvermindComponent</code> - the overmind component for a CBSE entity
***** <code>ReactorComponent</code> - the reactor component for a CBSE entity
***** <code>RocketpodComponent</code> - the rocket pod component for a CBSE entity
**** <code>CBSE</code> - the files containing the core entity declarations and definitions
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>Assert</code> - daemon engine specific assert code
**** <code>Clustering</code> - has code related to the (literal) clustering of base buildables
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
**** <code>sg_api</code> - contains the interface for the server game-logic module to handle messages received from the VM
**** <code>Entities</code> - contains helper routines for CBSE entity components
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
**** <code>parse</code> - parsing game script files
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

'''The Game Frame:'''
The game frame is a single moment or instant of the game. For the client, the game frame is a single render frame of the game. Gameplay and game objects are processed on a frame basis, the game is updated to the current frame and then presented to the player as an immediate moment in the game. This is the purpose of the function G_RunFrame, as in Game_RunFrame. This function does all game updates for console variables, for game entities, and entity events, and etc. See the function definition for G_RunFrame of sg_main.cpp for implementation details.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-08T17:12:50Z

The White Lion: /* sg_main.cpp */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src/</code> - engine source code
*** <code>shared/</code>
*** <code>server/</code>
**** <code>sg_api</code> - contains definitions for the VM to engine function-procedures
**** <code>CommonProxies</code> - proxy interface to the VM, has trap calls for sending messages to the VM
*** <code>common/</code>
**** <code>Cvar</code> - the proxy interface for console variables
**** <code>Debugger</code> - contains a routine to detect if a debugger is attached to the process
**** <code>FileSystem</code> - interface to use the host filesystem through the VM
**** <code>KeyIdentification</code> - contains an association table (unordered map) that links a keyboard key value with a string descriptor
**** <code>LineEditData</code> - ?
**** <code>Log</code> - filesystem logging
**** <code>IPC/</code>
***** <code>Common</code> - common definitions for all IPC methods
***** <code>Command</code> - the inter-process communication command buffer
***** <code>Channel</code> - contains the inter-process communication namespace and engine-VM messaging functions
***** <code>Primitives</code> - routines for the IPC VM-engine socket
**** <code>CM/</code> - related to game collisions and map loading
***** <code>cm_local</code>
***** <code>cm_patch</code>
***** <code>cm_polylib</code>
***** <code>cm_public</code>
**** <code>Color</code> - related to colors
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
***** <code>q_shared.cpp</code> - stateless support routines that are included in each code module
***** <code>q_math</code> - stateless support routines that are included in each code module, related to math operations
***** <code>q_Unicode</code> - Unicode & UTF-8 handling
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - the sources for the game-logic modules, both Client and Server
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib/</code> - directory containing sources for bot AI
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>Components/</code> - directory containing the sources for the CBSE entity components
***** <code>AcidTubeComponent</code> - code for Acid Tube entity component
***** <code>AlienBuildableComponent</code> - code for alien buildable entity component
***** <code>AlienClassComponent</code> - code for alien class entity component
***** <code>ArmourComponent</code> - the armour entity component class
***** <code>ArmouryComponent</code> - the armory entity component class
***** <code>BarricadeComponent</code> - the code for the barricade entity component
***** <code>BoosterComponent</code> - the booster component entity component class
***** <code>BuildableComponent</code> - code for the buildable entity component class
***** <code>DeferredFreeingComponent</code> - code for the deferred freeing component
***** <code>DrillComponent</code> - code for the drill entity component
***** <code>EggComponent</code> - code for the egg entity component
***** <code>HealthComponent</code> - the health component for a CBSE entity
***** <code>HiveComponent</code> - the hive component for a CBSE entity
***** <code>HumanBuildableComponent</code> - the human buildable component for a CBSE entity
***** <code>HumanClassComponent</code> - the human class component for a CBSE entity
***** <code>IgnitableComponent</code> - the ignitable component for a CBSE entity
***** <code>KnockbackComponent</code> - the knockback component for a CBSE entity
***** <code>LeechComponent</code> - the leech component for a CBSE entity
***** <code>MainBuildableComponent</code> - the main buildable component for a CBSE entity
***** <code>MedipadComponent</code> - the medi pad component for a CBSE entity
***** <code>MGTurretComponent</code> - the MG turret component for a CBSE entity
***** <code>MiningComponent</code> - the mining component for a CBSE entity
***** <code>OvermindComponent</code> - the overmind component for a CBSE entity
***** <code>ReactorComponent</code> - the reactor component for a CBSE entity
***** <code>RocketpodComponent</code> - the rocket pod component for a CBSE entity
**** <code>CBSE</code> - the files containing the core entity declarations and definitions
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>Assert</code> - daemon engine specific assert code
**** <code>Clustering</code> - has code related to the (literal) clustering of base buildables
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
**** <code>sg_api</code> - contains the interface for the server game-logic module to handle messages received from the VM
**** <code>Entities</code> - contains helper routines for CBSE entity components
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
**** <code>parse</code> - parsing game script files
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

'''The Game Frame:'''
The game frame is a moment or instant in the server game simulation, the current game state for all non-player entities, everything that happens is processed by the program frame by frame, the server updates the game state of all non-player entities in order. The function G_RunFrame advances all non-player objects in the game.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-08T17:04:45Z

The White Lion: /* Source Code Tree and File Descriptions */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src/</code> - engine source code
*** <code>shared/</code>
*** <code>server/</code>
**** <code>sg_api</code> - contains definitions for the VM to engine function-procedures
**** <code>CommonProxies</code> - proxy interface to the VM, has trap calls for sending messages to the VM
*** <code>common/</code>
**** <code>Cvar</code> - the proxy interface for console variables
**** <code>Debugger</code> - contains a routine to detect if a debugger is attached to the process
**** <code>FileSystem</code> - interface to use the host filesystem through the VM
**** <code>KeyIdentification</code> - contains an association table (unordered map) that links a keyboard key value with a string descriptor
**** <code>LineEditData</code> - ?
**** <code>Log</code> - filesystem logging
**** <code>IPC/</code>
***** <code>Common</code> - common definitions for all IPC methods
***** <code>Command</code> - the inter-process communication command buffer
***** <code>Channel</code> - contains the inter-process communication namespace and engine-VM messaging functions
***** <code>Primitives</code> - routines for the IPC VM-engine socket
**** <code>CM/</code> - related to game collisions and map loading
***** <code>cm_local</code>
***** <code>cm_patch</code>
***** <code>cm_polylib</code>
***** <code>cm_public</code>
**** <code>Color</code> - related to colors
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
***** <code>q_shared.cpp</code> - stateless support routines that are included in each code module
***** <code>q_math</code> - stateless support routines that are included in each code module, related to math operations
***** <code>q_Unicode</code> - Unicode & UTF-8 handling
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - the sources for the game-logic modules, both Client and Server
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib/</code> - directory containing sources for bot AI
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>Components/</code> - directory containing the sources for the CBSE entity components
***** <code>AcidTubeComponent</code> - code for Acid Tube entity component
***** <code>AlienBuildableComponent</code> - code for alien buildable entity component
***** <code>AlienClassComponent</code> - code for alien class entity component
***** <code>ArmourComponent</code> - the armour entity component class
***** <code>ArmouryComponent</code> - the armory entity component class
***** <code>BarricadeComponent</code> - the code for the barricade entity component
***** <code>BoosterComponent</code> - the booster component entity component class
***** <code>BuildableComponent</code> - code for the buildable entity component class
***** <code>DeferredFreeingComponent</code> - code for the deferred freeing component
***** <code>DrillComponent</code> - code for the drill entity component
***** <code>EggComponent</code> - code for the egg entity component
***** <code>HealthComponent</code> - the health component for a CBSE entity
***** <code>HiveComponent</code> - the hive component for a CBSE entity
***** <code>HumanBuildableComponent</code> - the human buildable component for a CBSE entity
***** <code>HumanClassComponent</code> - the human class component for a CBSE entity
***** <code>IgnitableComponent</code> - the ignitable component for a CBSE entity
***** <code>KnockbackComponent</code> - the knockback component for a CBSE entity
***** <code>LeechComponent</code> - the leech component for a CBSE entity
***** <code>MainBuildableComponent</code> - the main buildable component for a CBSE entity
***** <code>MedipadComponent</code> - the medi pad component for a CBSE entity
***** <code>MGTurretComponent</code> - the MG turret component for a CBSE entity
***** <code>MiningComponent</code> - the mining component for a CBSE entity
***** <code>OvermindComponent</code> - the overmind component for a CBSE entity
***** <code>ReactorComponent</code> - the reactor component for a CBSE entity
***** <code>RocketpodComponent</code> - the rocket pod component for a CBSE entity
**** <code>CBSE</code> - the files containing the core entity declarations and definitions
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>Assert</code> - daemon engine specific assert code
**** <code>Clustering</code> - has code related to the (literal) clustering of base buildables
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
**** <code>sg_api</code> - contains the interface for the server game-logic module to handle messages received from the VM
**** <code>Entities</code> - contains helper routines for CBSE entity components
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
**** <code>parse</code> - parsing game script files
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-08T16:56:23Z

The White Lion: /* Source Code Tree and File Descriptions */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src/</code> - engine source code
*** <code>shared/</code>
**** <code>CommonProxies</code> - proxy interface to the VM, has trap calls for sending messages to the VM
*** <code>common/</code>
**** <code>Cvar</code> - the proxy interface for console variables
**** <code>Debugger</code> - contains a routine to detect if a debugger is attached to the process
**** <code>FileSystem</code> - interface to use the host filesystem through the VM
**** <code>KeyIdentification</code> - contains an association table (unordered map) that links a keyboard key value with a string descriptor
**** <code>LineEditData</code> - ?
**** <code>Log</code> - filesystem logging
**** <code>IPC/</code>
***** <code>Common</code> - common definitions for all IPC methods
***** <code>Command</code> - the inter-process communication command buffer
***** <code>Channel</code> - contains the inter-process communication namespace and engine-VM messaging functions
***** <code>Primitives</code> - routines for the IPC VM-engine socket
**** <code>CM</code> - related to game collisions and map loading
***** <code>cm_local</code>
***** <code>cm_patch</code>
***** <code>cm_polylib</code>
***** <code>cm_public</code>
**** <code>Color</code> - related to colors
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
***** <code>q_shared.cpp</code> - stateless support routines that are included in each code module
***** <code>q_math</code> - stateless support routines that are included in each code module, related to math operations
***** <code>q_Unicode</code> - Unicode & UTF-8 handling
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - the sources for the game-logic modules, both Client and Server
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib/</code> - directory containing sources for bot AI
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>Components/</code> - directory containing the sources for the CBSE entity components
***** <code>AcidTubeComponent</code> - code for Acid Tube entity component
***** <code>AlienBuildableComponent</code> - code for alien buildable entity component
***** <code>AlienClassComponent</code> - code for alien class entity component
***** <code>ArmourComponent</code> - the armour entity component class
***** <code>ArmouryComponent</code> - the armory entity component class
***** <code>BarricadeComponent</code> - the code for the barricade entity component
***** <code>BoosterComponent</code> - the booster component entity component class
***** <code>BuildableComponent</code> - code for the buildable entity component class
***** <code>DeferredFreeingComponent</code> - code for the deferred freeing component
***** <code>DrillComponent</code> - code for the drill entity component
***** <code>EggComponent</code> - code for the egg entity component
***** <code>HealthComponent</code> - the health component for a CBSE entity
***** <code>HiveComponent</code> - the hive component for a CBSE entity
***** <code>HumanBuildableComponent</code> - the human buildable component for a CBSE entity
***** <code>HumanClassComponent</code> - the human class component for a CBSE entity
***** <code>IgnitableComponent</code> - the ignitable component for a CBSE entity
***** <code>KnockbackComponent</code> - the knockback component for a CBSE entity
***** <code>LeechComponent</code> - the leech component for a CBSE entity
***** <code>MainBuildableComponent</code> - the main buildable component for a CBSE entity
***** <code>MedipadComponent</code> - the medi pad component for a CBSE entity
***** <code>MGTurretComponent</code> - the MG turret component for a CBSE entity
***** <code>MiningComponent</code> - the mining component for a CBSE entity
***** <code>OvermindComponent</code> - the overmind component for a CBSE entity
**** <code>CBSE</code> - the files containing the core entity declarations and definitions
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>Assert</code> - daemon engine specific assert code
**** <code>Clustering</code> - has code related to the (literal) clustering of base buildables
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
**** <code>Entities</code> - contains helper routines for CBSE entity components
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
**** <code>parse</code> - parsing game script files
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-08T05:49:21Z

The White Lion: /* Source Code Tree and File Descriptions */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src/</code> - engine source code
*** <code>common/</code>
**** <code>IPC/</code>
***** <code>Common</code> - common definitions for all IPC methods
***** <code>Command</code> - the inter-process communication command buffer
***** <code>Channel</code> - contains the inter-process communication namespace and engine-VM messaging functions
**** <code>CM</code> - related to game collisions and map loading
***** <code>cm_local</code>
***** <code>cm_patch</code>
***** <code>cm_polylib</code>
***** <code>cm_public</code>
**** <code>Color</code> - related to colors
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
*****<code>q_shared.cpp</code> - stateless support routines that are included in each code module
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib</code>
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>Components/</code>
***** <code>AcidTubeComponent</code> - code for Acid Tube entity component
***** <code>AlienBuildableComponent</code> - code for alien buildable entity component
***** <code>AlienClassComponent</code> - code for alien class entity component
***** <code>ArmourComponent</code> - the armour entity component class
***** <code>ArmouryComponent</code> - the armory entity component class
***** <code>BarricadeComponent</code> - the code for the barricade entity component
***** <code>BoosterComponent</code> - the booster component entity component class
***** <code>BuildableComponent</code> - code for the buildable entity component class
**** <code>CBSE</code> - the files containing the basic entity code for Unvanquished and
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>Assert</code> - daemon engine specific assert code
**** <code>Clustering</code> - has code related to the (literal) clustering of base buildables
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-08T05:06:25Z

The White Lion: /* Source Code Tree and File Descriptions */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src</code> - engine source code
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
*****<code>q_shared.cpp</code> - stateless support routines that are included in each code module
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib</code>
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>AcidTubeComponent</code> - code for Acid Tube entity component
**** <code>AlienBuildableComponent</code> - code for alien buildable entity component
**** <code>AlienClassComponent</code> - code for alien class entity component
**** <code>ArmourComponent</code> - the armour entity component class
**** <code>ArmouryComponent</code> - the armory entity component class
**** <code>Assert</code> - daemon engine specific assert code
**** <code>BarricadeComponent</code> - the code for the barricade entity component
**** <code>BoosterComponent</code> - the booster component entity component class
**** <code>BuildableComponent</code> - code for the buildable entity component class
**** <code>CBSE</code> - the files containing the basic entity code for Unvanquished and
***** <code>CBSE.h</code> - connects a source files to the CBSE backend and provides all needed types to CBSE
***** <code>CBSEBackend</code> - has the declaration of the base entity, implementation of the base components, and helper routines to access entities and components
***** <code>CBSEComponents.h</code> - files with all game entity component headers
***** <code>CBSEEntities.h</code> - specific entity declarations
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-08T04:56:31Z

The White Lion: /* Source Code Filesystem Tree Structure */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Tree and File Descriptions==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src</code> - engine source code
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
*****<code>q_shared.cpp</code> - stateless support routines that are included in each code module
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>botlib</code>
***** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
***** <code>bot_convert</code> - procedures for the conversation
***** <code>bot_local</code> - server-local variable definitions, struct definitions, and forward declarations for the bot AI
***** <code>bot_navdraw</code> - code for drawing bot AI navmesh for debug purposes
***** <code>bot_types</code> - code that defines data types for bot AI code
**** <code>AcidTubeComponent</code> - code for Acid Tube entity component
**** <code>AlienBuildableComponent</code> - code for alien buildable entity component
**** <code>AlienClassComponent</code> - code for alien class entity component
**** <code>ArmourComponent</code> - the armour entity component class
**** <code>ArmouryComponent</code> - the armory entity component class
**** <code>Assert</code> - daemon engine specific assert code
**** <code>BarricadeComponent</code> - the code for the barricade entity component
**** <code>BoosterComponent</code> - the booster component entity component class
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-08T04:30:55Z

The White Lion: /* Source Code Filesystem Tree Structure */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src</code> - engine source code
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
*****<code>q_shared.cpp</code> - stateless support routines that are included in each code module
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent</code> - code for Acid Tube entity component
**** <code>AlienBuildableComponent</code> - code for alien buildable entity component
**** <code>AlienClassComponent</code> - code for alien class entity component
**** <code>ArmourComponent</code> - the armour entity component class
**** <code>ArmouryComponent</code> - the armory entity component class
**** <code>Assert</code> - daemon engine specific assert code
**** <code>BarricadeComponent</code> - the code for the barricade entity component
**** <code>BoosterComponent</code> - the booster component entity component class
**** <code>bot_api</code> - forward function declarations related to the bot artificial intelligence code
**** <code>bot_convert</code> - procedures for the conversation
**** <code>sg_active</code> - process server-local game events and server-local client effects
**** <code>sg_client</code> - server-local functions for a client
**** <code>sg_entities</code> - server functions for server-local game entities
**** <code>sg_main</code> - core server game functions
**** <code>sg_utils</code> - misc utility functions for game module
**** <code>sg_team</code> - function-procedures related to game teams
**** <code>sg_local</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn</code> - contains the declarations of the spawn functions for various game map entities
**** <code>sg_session</code> - code for client session data
**** <code>sg_physics</code> - game physics code
**** <code>sg_admin</code> - server admin management code
**** <code>sg_namelog</code> - record client names that connect to the server
*** <code>shared/</code>
**** <code>bg_public</code> - definitions shared by both the server game and client game modules
**** <code>bg_local</code> - local definitions for the bg (both games) files
**** <code>bg_gameplay</code> - gameplay related macro constants and external variable linkage
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-07T17:23:46Z

The White Lion: /* Source Code Filesystem Tree Structure */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> - data submodule
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> - engine submodule
** <code>src</code> - engine source code
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> - common code: utility functions, typedefs, macros, and the like
***** <code>q_shared.h</code> - included first by ALL program modules. A user mod should never modify this file.
*****<code>q_shared.cpp</code> - stateless support routines that are included in each code module
**** <code>renderer/</code> - renderer
***** <code>glsl_source/</code> - OpenGL shader code
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> - code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_client.cpp</code> - server-local functions for a client
**** <code>sg_entities.cpp</code> - server functions for server-local game entities
**** <code>sg_main.cpp</code> - core server game functions
**** <code>sg_utils.cpp</code> - misc utility functions for game module
**** <code>sg_team.cpp</code> - function-procedures related to game teams
**** <code>sg_local.h</code> - header file with more header inclusions
**** <code>sg_svcmds</code> - this file holds commands that can be executed by the server console, but not remote clients
**** <code>sg_spawn.h</code> - contains the declarations of the spawn functions for various game map entities
*** <code>shared/</code>
**** <code>bg_public.h</code> - definitions shared by both the server game and client game modules
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-06T03:59:36Z

The White Lion: /* sg_main.cpp */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_client.cpp</code> - server-local functions for a client
**** <code>sg_entities.cpp</code> - server functions for server-local game entities
**** <code>sg_main.cpp</code> - core server game functions
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

A special structure with server game level information is inside this file, the <code>level_locals_t level</code> variable.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Some Important Server Functions:'''
*<code>G_InitGame</code> - this function initializes the server game
*<code>G_SpawnClients</code> - spawns the clients into the server game
*<code>G_RunFrame</code> - executes the server game frame
*<code>G_RunThink</code> - executes the thinking code of the server game entities
*<code>ExitLevel</code> - changes the server game level after the intermission

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-06T03:52:41Z

The White Lion:

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_client.cpp</code> - server-local functions for a client
**** <code>sg_entities.cpp</code> - server functions for server-local game entities
**** <code>sg_main.cpp</code> - core server game functions
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==sg_main.cpp==
The file src/sgame/sg_main.cpp deserves its own section since there are a lot of core server game functions and important variables inside this file.

sg_main contains the proxy console variables, the game-logic modules cannot access the console variables directly so they are accessed via a proxy interface.

'''Important server functions:'''
*<code>G_InitGame</code>:

<code>

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-06T02:40:10Z

The White Lion: /* Source Code Filesystem Tree Structure */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_client.cpp</code> - server-local functions for a client
**** <code>sg_entities.cpp</code> - server functions for server-local game entities
**** <code>sg_main.cpp</code> - core server game functions
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-06T02:29:25Z

The White Lion: /* Game Logic */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_entities.cpp</code> - server functions for server-local game entities
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-06T02:28:45Z

The White Lion: /* Game Logic */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_entities.cpp</code> - server functions for server-local game entities
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

'''Game Objects or Entities:'''
Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''Gameplay:'''
Gameplay code is all the code that makes the entities do things and defines game rules and defines game events and defines game behaviors. There is a lot of code in this category and only a little some of the code will be used as an example.
Gameplay is server-local, meaning gameplay effects happens on the server. For example, the combat mechanics and behaviors of the game Unvanquished are defined in the file src/sgame/sg_combat.cpp. When a player dies the function ''G_PlayerDie'' is called and this function handles game events related to the death of a player, such as adding credit to a client's score and broadcasting a notification to the clients saying a player has died. Another example of gameplay code is the player movement code, contained inside of the file src/shared/bg_pmove.cpp. When a player moves their player character with their keyboard that input is transmitted to the server as a client command and the server calls the functions inside bg_pmove.cpp to apply the movement change to the player character game entity in the game level simulated by the game server, a client is changing the position and orientation of their associated player character entity on the server.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-06T02:10:36Z

The White Lion: /* Game Logic */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_entities.cpp</code> - server functions for server-local game entities
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h), if this maximum is reached then the server will terminate. All active game entities are listed inside a global array (''g_entities'', see sg_main.cpp), when a new entity is created the server searches this list for the next available free entity slot and initializes this slot, the server may force an entity slot to be reallocated to a new entity though this may lead to problems according to a comment in the file sg_entities.cpp:

''Try to avoid reusing an entity that was recently freed, because it can cause the client to think the entity morphed into something else instead of being removed and recreated, which can cause interpolated angles and bad trails.''

Clients are game entities too and from 0 to (''MAX_CLIENTS'' - 1)(see daemon/src/engine/qcommon/q_shared.h) of the server global game entity array is reserved for client entities.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-06T01:50:01Z

The White Lion: /* Game Logic */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_entities.cpp</code> - server functions for server-local game entities
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

Client-local game entities are drawn as computer graphics on the player's screen, any client input related interactions with these entities are transmitted to the server as commands and the server processes these commands and invokes the gameplay code for the entity or entities.

There is an absolute maximum number of entities of 1024 (see ''MAX_GENTITIES'' macro definition of daemon/src/engine/qcommon/qshared.h)

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-06T01:41:21Z

The White Lion: /* Source Code Filesystem Tree Structure */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_entities.cpp</code> - server functions for server-local game entities
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-06T01:07:34Z

The White Lion: /* Source Code Filesystem Tree Structure */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
**** <code>sg_entities.cpp</code> - server functions for game entities
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T23:44:30Z

The White Lion: /* Source Code Filesystem Tree Structure */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> - client-local game-logic code
*** <code>sgame/</code> - server-local game-logic code
**** <code>AcidTubeComponent.h</code> - class declaration for the Acid Tube component entity
**** <code>sg_active.cpp</code> - process server-local game events and server-local client effects
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T23:07:17Z

The White Lion: /* Source Code & Data Structure */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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 Filesystem Tree Structure==

* <code>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
**** <code>sg_active.cpp</code> - process server-local game events and server-local clients
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T23:06:12Z

The White Lion: /* Source Code & Data Structure */

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
**** <code>sg_active.cpp</code> - process server-local game events and server-local clients
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T23:02:30Z

The White Lion:

{{OutOfDate}}

This Wiki page is incomplete and a work-in-progress, nonetheless there is still helpful information on this web page.

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T22:44:41Z

The White Lion: /* Game Logic */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

There are a number of CBSE (and so Unvanquished) entity related helper functions located in the file Unvanquished/src/sgame/Entities.h, and their implementation inside the cpp file.

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T20:25:23Z

The White Lion:

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T20:23:49Z

The White Lion: /* Source Code & Data Structure */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code> - game assets
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T20:21:30Z

The White Lion: /* Game Logic */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''
Buildable information is encapsulated in the <code>cg_buildables</code> array (declared in {{SourceFile|src/cgame/cg_main.cpp}})

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T20:21:15Z

The White Lion: /* Client-Side */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

'''Client-Local Game Logic:'''

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T20:20:23Z

The White Lion:

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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>.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T20:19:07Z

The White Lion: /* Game Logic */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T20:18:50Z

The White Lion: /* Game Logic */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h. The base class for Unvanquished game entities is nested inside of the base class for game entities of the original Quake III source, see <code>struct gentity_s</code> at line 111 of Unvanquished/src/sgame/sg_struct.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T20:14:54Z

The White Lion: /* Game Logic */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

'''Game Logic Categories:'''
The game code can be thought of as being separated into two distinct categories: game objects and gameplay.

Game objects are the objects that exist in the game world, they have a graphical representation (the actual game asset, such as the armory mesh model), they have hit points, and can receive damage from a source and die if their hit points reaches 0, they can heal themselves (replenish hit points), and they are created when the map loads or while the game is running (for example when a player creates a drill entity to increase build points for their team), and they can be destroyed, and etc. Entities in Unvanquished are designed to have components, a component is a C++ class with gameplay functionality that is incorporated into the basic entity itself and the basic entity acquires the functionality of the component. A component is owned by a parent entity. The base class definition for Unvanquished game entities is contained inside of Unvanquished/src/sgame/backend/CBSEBackend.h.

Here are some example component classes:

<code>class ArmouryComponentBase</code> - at line 1867 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class HealthComponentBase</code> - at line 475 of Unvanquished/src/sgame/backend/CBSEBackend.h

<code>class ThinkingComponentBase</code> - at line 359 of Unvanquished/src/sgame/backend/CBSEBackend.h

'''CBSE:''' Unvanquished uses the CBSE Toolchain to implement the game entity components. CBSE is a code generator based on Python and requires Python3 and Python3-yaml to generate the actual C++ code, and a C++ 11 compiler to compile the generated code. See https://github.com/DaemonEngine/CBSE-Toolchain for more information.

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T05:33:07Z

The White Lion: /* System Architecture */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user then updates its game-state per this input (for example, the player using their keyboard to move the character forward some distance) then transmit these input events to the Server, and to actually draw the computer graphics, and etc. The Server has the task of simulating the game itself but does not render any graphics for a user, for example game objects would exist on the Server, and the Server would tell the Client that game object exists and it should be drawn on the screen. These examples are not all functionalities the Client or Server performs. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands, for example the user moving their controlled character somewhere else in the level, these movements would be transmitted as commands to the Server to update its game state with the new player location. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the time the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are updates or changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T03:22:31Z

The White Lion: /* Program Ignition and Initialization */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The game-logic modules (client game and server game) are created as child processes by the virtual machine (see daemon/src/engine/framework/VirtualMachine.cpp) The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T01:36:54Z

The White Lion: /* Program Ignition and Initialization */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). All game-logic modules must have a main function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the modules calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T01:33:03Z

The White Lion: /* Program Ignition and Initialization */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: '''CGameVM''' and '''GameVM'''. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T01:00:25Z

The White Lion: /* System Architecture */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands. Quake III (and so Daemon) does this synchronization efficiently, the client receives a snapshot (a program object that contains data about the server's game state since the snapshot was sent to the client) and the client updates this snapshot with 'deltas' it receives from the server, these deltas are changes to the server game state and only these changes are transmitted.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: <code>CGameVM</code> and <code>GameVM</code>. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T00:56:41Z

The White Lion: /* System Architecture */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

'''The Virtual Machines:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: <code>CGameVM</code> and <code>GameVM</code>. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T00:55:37Z

The White Lion: /* System Architecture */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

'''The Virtual Machiness:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay. The Daemon engine and the virtual machines are in the system code category while the Unvanquished game code is in the game-logic code category.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: <code>CGameVM</code> and <code>GameVM</code>. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T00:49:21Z

The White Lion: /* System Architecture */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==
'''General:'''
The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

'''The Virtual Machiness:'''
The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

'''Code Categorization:'''
The code of Daemon and Unvanquished are 2 categories: the engine system code the game Unvanquished is based on and the actual game-logic code that defines playable game objects and gameplay.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: <code>CGameVM</code> and <code>GameVM</code>. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T00:47:07Z

The White Lion: /* Program Ignition and Initialization */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==

The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: <code>CGameVM</code> and <code>GameVM</code>. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server game-logic modules is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T00:45:04Z

The White Lion:

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==

The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

'''Initialization for Virtual Machines:'''
There are two virtual machines as parts of the Daemon and Unvanquished game systems: <code>CGameVM</code> and <code>GameVM</code>. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

'''Initialization for Game-Logic Modules:'''
The entrance into the program code for the client and server is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function.

This entry point is called by the virtual machine for the game-logic module (for example: the client virtual machine invokes '''Main''' of VMMain.cpp for the client game-logic module) and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T00:40:34Z

The White Lion: /* Program Ignition and Initialization */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==

The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

==Initialization for Virtual Machines==
There are two virtual machines as parts of the Daemon and Unvanquished game systems: <code>CGameVM</code> and <code>GameVM</code>. '''CGameVM''' is the virtual machine for the client and '''GameVM''' is the virtual machine for the server. See daemon/src/engine/client/client.h for the class declaration of the client VM and daemon/src/engine/server/server.h for the class declaration of the server VM.

The client VM is created with a call to <code>CGameVM::Start()</code> and this is called from <code>void CL_StartHunkUsers()</code> or <code>void CL_Disconnect( bool ''showMainMenu'' )</code>. See daemon/src/engine/client/cl_cgame.cpp.

The server VM is created with a call to <code>void GameVM::Start()</code> and this is called from <code>void SV_InitGameProgs()</code> and this is called from <code>void SV_SpawnServer(std::string ''pakname'', std::string ''mapname'')</code>. The server VM is created when the server game starts running. See daemon/src/engine/server/sv_init.cpp.

== Initialization for Game-Logic Modules==

The entrance into the program code for the client and server is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function. Each game-logic module has its own VM, the '''cgame''' (as in client game) and '''sgame''' (as in server game) has their own VMs. The '''cgame''' VM is the class '''CGameVM''', its class declaration is inside daemon/src/engine/client/client.h. The '''sgame''' VM is the class '''GameVM''', its class declaration is inside daemon/src/engine/server/server.h. Both VMs inherit from <code>VM::VMBase</code>. Each VM has a function called <code>Start()</code> and this is the function that actually creates a new VM (via a call to <code>Create()</code> and initiates the game-logic module.

This entry point is called by the engine's VM loader and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-05T00:15:53Z

The White Lion: /* System Architecture */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==

The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

The Daemon and Unvanquished systems are ultimately descendants of the original Quake III Arena game engine known as Id 3. The Id 3 game engine has a virtual machine incorporated into the executable program and functions as an intermediary between the actual game logic code and the engine. The game logic system interfaces with the virtual machine to invoke engine functionalities, the game code does not invoke engine functions itself, the virtual machine does that action. Communication between the game code and the engine happens via Inter-Process Communication (IPC) through special pipe files, the engine sends messages to a virtual machine and the virtual machine invokes game code functions according to the type of message it receives from the engine. The game logic sends messages to the virtual machine to invoke engine functions. The client subsystem of Daemon has its own virtual machine and the server subsystem of Daemon has its own virtual machine.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

The entrance into the program code for the client and server is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function. Each game-logic module has its own VM, the '''cgame''' (as in client game) and '''sgame''' (as in server game) has their own VMs. The '''cgame''' VM is the class '''CGameVM''', its class declaration is inside daemon/src/engine/client/client.h. The '''sgame''' VM is the class '''GameVM''', its class declaration is inside daemon/src/engine/server/server.h. Both VMs inherit from <code>VM::VMBase</code>. Each VM has a function called <code>Start()</code> and this is the function that actually creates a new VM (via a call to <code>Create()</code> and initiates the game-logic module.

This entry point is called by the engine's VM loader and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-04T23:57:57Z

The White Lion: /* Program Ignition and Initialization */

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==

The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

The entrance into the program code for the client and server is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function. Each game-logic module has its own VM, the '''cgame''' (as in client game) and '''sgame''' (as in server game) has their own VMs. The '''cgame''' VM is the class '''CGameVM''', its class declaration is inside daemon/src/engine/client/client.h. The '''sgame''' VM is the class '''GameVM''', its class declaration is inside daemon/src/engine/server/server.h. Both VMs inherit from <code>VM::VMBase</code>. Each VM has a function called <code>Start()</code> and this is the function that actually creates a new VM (via a call to <code>Create()</code> and initiates the game-logic module.

This entry point is called by the engine's VM loader and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-04T23:17:37Z

The White Lion:

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==

The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

The entrance into the program code for the client and server is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function.

This entry point is called by the engine's VM loader and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Client==
The function of the Client is to receive input events generated by the human user and transmit these events to the Server, and to draw computer generated graphics to the user's screen.

Input is received through SDL input capture, see the function <code>void IN_Frame()</code> of ''daemon/src/engine/sys/SDL_Input.cpp''.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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

2021-07-04T23:08:05Z

The White Lion:

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

===Notes===

If you are attempting to generate the Microsoft Visual Studio solution file for the Unvanquished game system make sure you have installed all Python related dependencies for cmake to generate the solution file. If cmake fails to generate the solution file because of alleged missing Python dependencies but you know you have them for a fact then check the cmake variable <code>_Python_EXECUTABLE_</code> that its value is set to the location of the Python executable of the Python installation having the dependencies, for example "C:\Program Files\Python39\python.exe" and not the Python executable obtained from the Windows App Store "C:\Program Files\WindowsApps\...". Pip would install Python dependencies for the non-Windows App Store executable.

==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>pkg/</code>
** <code>unvanquished_src.dpkdir</code> Data submodule.
*** <code>fonts/</code>
*** <code>gfx/</code>
*** <code>lights/</code>
*** <code>models/</code>
*** <code>scripts/</code>
*** <code>sound/</code>
*** <code>translation/</code>
*** <code>ui/</code>
* <code>daemon/</code> Engine submodule.
** <code>src</code> Engine source code.
*** <code>common/</code>
*** <code>engine/</code>
**** <code>audio/</code>
**** <code>botlib/</code>
**** <code>client/</code>
**** <code>crash_server/</code>
**** <code>framework/</code>
**** <code>null/</code>
**** <code>qcommon/</code> Common code: utility functions, typedefs, macros, and the like.
**** <code>renderer/</code> Renderer.
***** <code>glsl_source/</code> OpenGL shader code.
**** <code>server/</code>
**** <code>sys/</code>
*** <code>shared/</code>
**** <code>client/</code>
**** <code>server/</code>
** <code>src/</code> Code that falls outside the scope of the core engine. Client and server game codes run in separate [[virtual machines]].
*** <code>cgame/</code> Client-side game code.
*** <code>sgame/</code> Server-side game code.
*** <code>shared/</code>
*** <code>utils/</code>

==System Architecture==

The architecture of the Daemon game engine is fundamentally the Client and Server architecture. In essence the Client uses a service provided by the Server. In the case of Daemon and Unvanquished, the service is the game Unvanquished and the Client receives this game when the Client connects to the game Server. The Client and Server are two different programs executed on the computer, the Client is "daemon.exe" and the Server is "daemonded.exe". This separation into two different programs makes it possible for the Server program to be executed on a machine a part of another computer network connected to the Internet so the Server and Client does not necessarily execute on the same computer machine but the same machine can execute both Client and Server (hence 'local' game, the Client connects to the server running on the host machine "127.0.0.1").
The Client and Server do different things. The Client has the task of receiving input by the user and transmit these input events to the Server and to actually draw the computer graphics, while the Server has the task of simulating the game itself but does not render any graphics for a user. Each entity in this relationship keeps separate game states and these game states must be synchronized, whatever happens on the side of the Server game is transmitted to the Client as game updates and anything the Client needs to happen must be transmitted to the Server as client commands.

==Program Ignition and Initialization==
The engine system is compiled into a static library (.lib file) and linked into (incorporated) the client executable ("daemon.exe") (and the server executable "daemonded.exe"), this means that when the program (application) is started by double-clicking the file in the WindowsOS GUI the engine is loaded into memory.

The entry point into the game system is the function <code>ALIGN_STACK_FOR_MINGW int main(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 666 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L666]). This function is called by SDL and is macro defined as SDL_main (see SDL_main.h, lines 120-121).

Main (SDL_main) calls <code>static void Init(int ''argc'', char** ''argv'')</code> in the file System.cpp at line 525 (as of the latest Github commit for 28 June 2021 [https://github.com/DaemonEngine/Daemon/blob/b5e4eedca774adddb8f786851966def7e29680c7/src/engine/framework/System.cpp#L525]), this function initializes the engine and any error that happens here is fatal. As part of the initialization procedure, a special pipe file is created within the base game directory file tree structure, the game communicates with the engine through this pipe file, both the engine system and game system shares this pipe file to communicate data to each other.

The entrance into the program code for the client and server is the function <code>int main(int ''argc'', char** ''argv'')</code> of VMMain.cpp at line 120, this is true only if the client and server are built as executables, this code is not compiled if the client and server are compiled into dynamic link libraries (dlls). This main function is called by the Virtual Machine, all game-logic modules must implement this function.

This entry point is called by the engine's VM loader and it is not designed to be invoked directly (activating the executable by double-clicking on the exe file in WindowsOS). The main functions of the exes calls <code>static void CommonInit(Sys::OSHandle ''rootsocket'')</code> and from within this function the program enters its main (infinite) loop (<code>while(true)</code>) and this function interfaces with the virtual machine with the function <code>void VM::VMHandleSyscall(uint32_t ''id'', Util::Reader ''reader'')</code>, this function is contained within the sg_api.cpp (src/sgame/sg_api.cpp) and cg_api.cpp (src/cgame/cg_api.cpp) files.

The sg_api.cpp file contains code that receives messages from its VM and executes function callbacks depending on the type of message received. The initialization related messages are:

<code>GAME_STATIC_INIT</code>:

1.<code>VM::InitializeProxies(''milliseconds'')</code> - invokes 2 other initialization functions, <code>Cmd::InitializeProxy()</code> and <code>Cvar::InitializeProxy()</code>, to register commands with the VM and to register global static client variables (cvars).

2.<code>FS::Initialize()</code> - sends a message to the VM and the VM interfaces with the engine to initialize the filesystem.

3.<code>VM::VMInit()</code> - makes the VM allocate memory for clients and game entities and loads map collision data.

<code>GAME_INIT</code>:

1. Sets <code>g_cheats.integer</code> to the parameter value of <code>''cheats''</code>

2. <code>G_InitGame</code> - this function is called from sg_main.cpp and performs many functions, such as setting the cvars inside the VM to default values, and defines global level variables, and sets up logging, and gets server info, and loads config files, and initializes entities for the game, and loads emoticons, and etc. see <code>G_InitGame</code> of sg_main.cpp at about line 690 for more details.

The init message codes are different for cg_api.cpp, <code>CG_STATIC_INIT</code> and <code>CG_INIT</code>, the purpose of them both are the same, although there are some minor differences. See cg_api.cpp for more information. The <code>CG_INIT</code> message is generated by the engine and transmitted to the client game-logic module for processing, the message originates from src/engine/client/cl_cgame.cpp within the function <code>void CGameVM::CGameInit(int serverMessageNum, int clientNum)</code>. There is one initialization message unique to cg_api.cpp and that is <code>CG_ROCKET_VM_INIT</code>.

<code>CG_ROCKET_VM_INIT</code>:

1. <code>CG_Rocket_Init</code> - essentially starts the user interface for the game, the user interface for the game is based on libRocket.

Some information related to the VM and program ignition, from a comment in the file src/engine/framework/VirtualMachine.h:

* To better support mods the gamelogic is treated like any other asset and can
* be downloaded from a server. However it is considered untrusted code so we
* need to run it in a sandbox. We use NaCl to provide the sandboxing which
* means that the gamelogic is in another process and that we have to use IPC and
* shared memory to communicate with it.
*
* The gamelogic can be compiled to and ran from several executable formats that
* will all start at the "main" function whose first job will be to retrieve the
* root socket handle to communicate with the engine. The different executable
* formats are:
* - A native shared library loaded at runtime and started in the engine process,
* this shared lib exports a "main" function pointer which is called by the
* engine, providing a handle to the root socket in argv[1]. Because the gamelogic
* lives in the same process as the engine, any leaks in the gamelogic will be
* engine leaks. However because it is in the same process, it is easier to debug
* as the debugger doesn't automatically attach to child process.
* - An NaCl executable started in a new sandboxed process. The "main" function is
* ran first and the root socket handle is given via an environment variable. This
* is how the gamelogic is ran when we do not trust the code as it won't be able to
* access anything apart from the file handles the engine gives it. When the NaCl
* gamelogic exits the OS will clean up any leaks for us. It is also slightly slower
* than native format (no SSE and code alignment constraints).
* - A native executable started in a new process, obviously the "main" function
* is the first one ran. The root socket handle is given in argv[1]. It doesn't
* provide sandboxing like the nacl executable but the OS will still clean up any
* leak for us.
*
* When setting the cgame VM type to non-default values, make sure to use /devmap
* (rather than /map) as it is a 'CHEAT' cvar.
*
* TL;DR
* - Native DLL: no sandboxing, no cleaning up but debugger support. Use for dev.
* - NaCl exe: sandboxing, no leaks, slightly slower, hard to debug. Use for regular players.
* - Native exe: no sandboxing, no leaks, hard to debug. Might be used by server owners for perf.

==Lag Compensation==

Daemon uses Neil "haste" Toronto's [https://www.ra.is/unlagged/contents.html 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 twos areas: server-side, and client-side, user interface is part of client side. Each runs in its own [[Virtual_machines|virtual machine]].

On Quake 3 derivatives like Tremulous, there was <code>cgame.qvm</code>, <code>game.qvm</code> and <code>ui.qvm</code> (client-side, server-side, user interface).

With Dæmon Engine and Unvanquished there are <code>cgame.nexe</code> and <code>sgame.nexe</code> (client-side and server-side).

==Client-Side==

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

Constants used to define gamelogic variables are in {{SourceFile|src/shared/bg_gameplay.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/sgame/sg_main.cpp}}.

==Particle & Trail System==

For now, please see the [https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf Tremulous documentation].

==GL3 Renderer==

Source code for the modern OpenGL renderer is located in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer}}. This renderer is sometime referred to as the "GL3" renderer in opposite to the now-removed “legacy” renderer (also called “vanilla” in the past).

===Notes===

* Shaders are implemented as subclasses of the <code>GLShader</code> class. All are defined in {{SourceFile|repository=DaemonEngine/Daemon|src/engine/renderer/gl_shader.h}}.
* Each GLSL shader has their compilation and loading controlled by the single <code>GLShaderManager</code> 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 <code>r_lazyShaders</code>
* 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. For Example, <code>gl_genericShader</code> is of type <code>GLShader_generic</code> which derives from the following classes. That list may be obsolete, see <code>GLShader_generic</code> class definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} for up to date information:
** <code>GLShader</code>
** <code>u_ColorTextureMatrix</code>
** <code>u_ViewOrigin</code>
** <code>u_ViewUp</code>
** <code>u_AlphaThreshold</code>
** <code>u_ModelMatrix</code>
** <code>u_ModelViewProjectionMatrix</code>
** <code>u_ColorModulate</code>
** <code>u_Color</code>
** <code>u_Bones</code>
** <code>u_VertexInterpolation</code>
** <code>u_DepthScale</code>
** <code>GLDeformStage</code>
** <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
** <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
** <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
** <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
** <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
** <code>GLCompileMacro_USE_DEPTH_FADE</code>
** <code>GLCompileMacro_USE_ALPHA_TESTING</code>

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

* GLSL shaders may be found in <code>src/engine/renderer/glsl_source</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 <code>if ( )</code> 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 <code>shader->BindProgram()</code>.

This list may be obsolete, an updated list can be found in the <code>EGLCompileMacro</code> enum definition in {{SourceFile|repository=DaemonEngine/daemon|src/engine/renderer/gl_shader.h}} file:

* <code>GLCompileMacro_USE_BSP_SURFACE</code>
* <code>GLCompileMacro_USE_VERTEX_SKINNING</code>
* <code>GLCompileMacro_USE_VERTEX_ANIMATION</code>
* <code>GLCompileMacro_USE_VERTEX_SPRITE</code>
* <code>GLCompileMacro_USE_TCGEN_ENVIRONMENT</code>
* <code>GLCompileMacro_USE_TCGEN_LIGHTMAP</code>
* <code>GLCompileMacro_USE_LIGHT_MAPPING</code>
* <code>GLCompileMacro_USE_DELUXE_MAPPING</code>
* <code>GLCompileMacro_USE_HEIGHTMAP_IN_NORMALMAP</code>
* <code>GLCompileMacro_USE_RELIEF_MAPPING</code>
* <code>GLCompileMacro_USE_REFLECTIVE_SPECULAR</code>
* <code>GLCompileMacro_LIGHT_DIRECTIONAL</code>
* <code>GLCompileMacro_USE_SHADOWING</code>
* <code>GLCompileMacro_USE_DEPTH_FADE</code>
* <code>GLCompileMacro_USE_PHYSICAL_MAPPING</code>
* <code>GLCompileMacro_USE_ALPHA_TESTING</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 OpenGL drivers==

Some OpenGL drivers may cause Valgrind to spew out a lot of false errors. You can suppress these by using the <code>--suppressions=/path/to/file.supp</code> flag. You must pass the full path (no use of the tilde symbol). For example, the following [http://www.mediafire.com/?z6ehwrxpw2m469h file] can be used as a template for your suppression file when using the fglrx driver, keeping in mind that the location of the fglrx library may need to be changed. Note: the fglrx driver no longer exist, but the tip may apply to others drivers.

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