This page describes the structure of the game's source code, as found in the official SVN repository. For instructions on getting the code and building on your particular platform see Build Instructions.

Finding your way around

After obtaining the game's source code, you will find the following base directories:

• binaries : Contains the game's data, scripts, and Windows executables.
• build : Tools for generating the workspaces needed to build the game.
• docs : Placeholder for documentation.
• libraries : Libraries (third-party software) needed to build the game.
• source : Source code for the engine and associated tools.

All these are covered in more depth below.

binaries

This directory contains everything that gets released to the end-user. This is the only part that an artist or designer needs to modify. The game is run from within this directory and it includes prebuilt executables for Windows users. Custom builds also end up here for Windows, Linux and OS X.

In Windows, the game is run by opening pyrogenesis.exe and the Atlas scenario editor is with Atlas.bat (which invokes "pyrogenesis.exe -editor"). These files can be found in the binaries\system\ directory and are regularly updated on SVN as the game engine changes.

data

This directory contains data distributed to all users of the game. However, data created during games is stored in separate locations, depending on the user's OS, see GameDataPaths for those locations.

config

Contains the default configuration file default.cfg, a simple text file containing pairs of key = value entries. To make changes to the configuration, the user should create or modify local.cfg or user.cfg files in their user data directory (see above). Also contains a list of hot key definitions which can be used in the config files.

mods

This contains the game data and is of primary interest to the game's artists, developers and the modding community. The official mod is in the public directory. Mods may be placed in a .zip archive or left as loose files. They can be selectively loaded by users, for a different game experience.

See the mod layout page for details.

tests

Contains some non-mod data and scripts used by the test suite.

tools

Some data associated with tools separate from the engine itself, like Atlas and font builder.

system

Binares and required libraries for the game are found here. For Windows users, the game's executables (EXEs) and libraries (DLLs) can be found here along with the game's tools. Similarly for developers building the game themselves, the binaries will end up here.

build

This directory is most useful for developers wishing to build the game themselves. This section will briefly describe the directory, see Build Instructions for more details on building the game for your OS.

autobuild2

TODO

bin

Some utilities for the build process.

coverage

TODO

dehydra

Some analysis scripts for Dehydra, a tool for custom static analysis of C++ code.

errorlist

A tool for generating the error and exception codes used in the game.

premake

Building the game is eased by an automated tool called ​Premake, which creates platform-specific workspaces for developers. Premake uses scripts written in ​Lua. Windows, Linux, and OS X are the supported environments, as are a few major IDEs (namely Visual C++ and Xcode).

resources

Icons and data files for the game's installer.

svn_revision

Utility for outputting the current game build's revision number.

workspaces

Build workspaces and the scripts for generating them are found here. Windows users should run update-workspaces.bat while Linux/OS X users should run update-workspaces.sh (see BuildInstructions)

libraries

These are the third-party libraries currently stored in the repository; they are not necessarily used in the final game. Here are some descriptions of the libraries and where they can be downloaded. Note: as of r13148, these are organized approximately by OS.

osx

Contains a script for building OS X dependencies, see BuildInstructions#OSX.

source

Source code of modified libraries and some that may not be available in package managers. It is shared for OS X, Windows, and *nix.

• cxxtest: CxxTest is a JUnit/CppUnit/xUnit-like framework for C/C++. It is focussed on being a lightweight framework that is well suited for integration into embedded systems development projects. ​http://cxxtest.tigris.org/
• enet: ENet's purpose is to provide a relatively thin, simple and robust network communication layer on top of UDP (User Datagram Protocol). The primary feature it provides is optional reliable, in-order delivery of packets. ​http://enet.bespin.org/
• fcollada: FCollada is a C++ library which offers support for COLLADA interoperability. ​http://collada.org/mediawiki/index.php/FCollada
• nvtt: The NVIDIA Texture Tools is a collection of image processing and texture manipulation tools, designed to be integrated in game tools and asset conditioning pipelines. The primary features of the library are mipmap and normal map generation, format conversion and DXT compression. ​http://code.google.com/p/nvidia-texture-tools/
• spidermonkey: Mozilla's JavaScript engine written in C/C++. JavaScript is the game's scripting language of choice (game logic, AIs, random maps, etc). ​http://www.mozilla.org/js/spidermonkey/
• valgrind: Valgrind is an instrumentation framework for building dynamic analysis tools. There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail ​http://valgrind.org/

win32

Headers and prebuild static libs for win32 developers. Not used for *nix or OS X.

• boost: Boost provides free peer-reviewed portable C++ source libraries. The emphasis is on libraries which work well with the C++ Standard Library. ​http://www.boost.org/
• cryptopp: Crypto++ Library is a free C++ class library of cryptographic schemes. ​http://www.cryptopp.com/
• libcurl: curl is a command line tool for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP. curl supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, kerberos...), file transfer resume, proxy tunneling and a busload of other useful tricks. ​http://curl.haxx.se/
• libjpg: libjpeg is a library written entirely in C which contains a widely-used implementation of a JPEG decoder, JPEG encoder and other JPEG utilities. This library is maintained by the Independent JPEG Group. ​http://www.ijg.org/
• libpng: libpng is the official PNG (portable network graphics) reference library. It supports almost all PNG features, is extensible, and has been extensively tested for over 15 years. ​http://www.libpng.org/
• libxml2: Libxml2 is the XML C parser and toolkit developed for the Gnome project (but usable outside of the Gnome platform), it is free software available under the MIT License. XML itself is a metalanguage to design markup languages, i.e. text language where semantic and structure are added to the content using extra "markup" information enclosed between angle brackets. ​http://xmlsoft.org/
• openal: Platform independent audio driver, equivalent to OpenGL in audio terms. OpenAL is a cross-platform 3D audio API appropriate for use with gaming applications and many other types of audio applications. ​http://www.openal.org/
• opengl: OpenGL is an API for 2D and 3D graphics applications. OpenGL fosters innovation and speeds application development by incorporating a broad set of rendering, texture mapping, special effects, and other powerful visualization functions. Developers can leverage the power of OpenGL across all popular desktop and workstation platforms, ensuring wide application deployment. ​http://www.opengl.org/
• sdl: Simple Directmedia Layer is a cross-platform multimedia library designed to provide low level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, and 2D video framebuffer. ​http://www.libsdl.org/
• vorbis: Ogg Vorbis is a completely open, patent-free, professional audio encoding and streaming technology with all the benefits of Open Source. ​http://www.vorbis.com/
• wxwidgets: (This directory is empty, as wxWidgets is not included in the SVN. It is only needed for developers who plan to build Atlas, according to the Build Instructions) wxWidgets is a class library that allows you to compile graphical C++ programs on a range of different platforms. wxWidgets defines a common API across platforms, but uses the native graphical user interface (GUI) on each platform, so your program will take on the native 'look and feel' that users are familiar with. ​http://www.wxwidgets.org/
• zlib: zlib is designed to be a free, general-purpose, legally unencumbered -- that is, not covered by any patents -- lossless data-compression library for use on virtually any computer hardware and operating system. ​http://zlib.net/

source

This directory contains the source code of the engine and associated tools. It is almost exclusively written in C/C++. It should be noted that our convention is to place both header/include files (.h) and source files (.c/.cpp) in the same directory (see also: Coding conventions).

As there are many subdirectories, they will not all be listed here. However this may serve as a brief introduction to the codebase.

collada

Libraries to convert COLLADA assets to the engine's proprietary format. COLLADA is the format for adding new 3D models and animations to the game and is supported by a number of free and commercial 3D modeling programs. See ​Art Design for more details.

graphics

Defines classes for maintaining data about what the user sees in the game world, such as objects, textures, terrain, shaders, and particles. Also includes map handling.

gui

Defines GUI (graphical user interface) classes for 2D objects with which the user interacts during the game (buttons, text, lists, minimap, etc.)

lib

Low-level code for the engine, including abstractions of specific systems by OS and architecture.

lobby

Contains code to support using the XmPP-based multiplayer lobby.

maths

Defines classes for typical mathematical operations.

mocks

Contains code related to the cxxtest suite.

network

Defines classes for supporting multiplayer, networked games with a server-client architecture.

pch

Precompiled headers for faster compilation of the game.

ps

Contains miscellaneous code, useful throughout the engine. (Short for "Pyrogenesis" - the name of the engine)

renderer

Defines classes for rendering 3D things during the game. These are the implementations used in the rendering loop.

scripting

Parts of the C++ - JavaScript interface are defined here.

simulation2

Defines classes used by the new simulation. Components that implement engine logic are included here, as well as serialization and helper classes. Note that some components are implemented in JavaScript and optionally define both JavaScript and C++ interfaces (those components are included by mods, within the binaries\data directory).

soundmanager

Contains code for the new sound manager, its helper classes and JavaScript interfaces.

third_party

Contains code from third party libraries that are built as part of 0 A.D. Unlike the rest of source/ they are not written by WFG and may have different (but compatible) licensing.

tools

This directory contains a number of tools which are to be considered largely separate of the game engine. Of these Atlas is the most useful to modders and developers.

atlas

Atlas is the name of the Scenario Editor used to create maps for the game. Atlas is not merely a data editor but uses the engine for rendering and simulation, to accurately reproduce the way maps will be handled in the game. As such the Atlas UI runs in a separate thread from the engine, messages are passed between threads to synchronize behavior.

• AtlasFrontends: Contains a few stand-alone tools based on Atlas, the most useful of which is Actor Editor.
• AtlasObject: Defines some helper classes for manipulating XML and JSON data in Atlas.
• AtlasScript: Defines a minimal interface for scripting in Atlas, using SpiderMonkey.
• AtlasUI: Define classes for the Atlas UI, which will be run in its own thread.
• DatafileIO: Old code used by the AoE3Ed tool.
• GameInterface: Defines the message passing and handling behavior of Atlas.

autobuild/2

The autobuild utility compiles the Windows executable that is included in the SVN repository.

fontbuilder2

This utility builds the font textures seen in the game's UI, from font style definitions and a list of characters to include. The source fonts are located in binaries\data\tools\fontbuilder\.

templatessorter

Utility to sort the component definitions of entity templates into alphabetical order.

TODO - DESCRIBE THE OTHERS