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, use in-game options or create/modify local.cfg in the user data directory (see Manual_Settings). The presence of dev.cfg indicates a developer version of the game, not a release package, which changes how mods are handled.
keys.txt is a list of hotkey definitions which can be used in the config system.
l10n
Internationalization and Localization files for the engine.
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
Binaries 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.
bin
Some utilities for the build process.
coverage
TODO
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, organized roughly by OS; they are not necessarily used in the final game. Here are some descriptions of the libraries and where they can be downloaded.
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-4.4: CxxTest is a JUnit/CppUnit/xUnit-like framework for C/C++. It is focused on being a lightweight framework that is well suited for integration into embedded systems development projects. http://cxxtest.com/
- 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. https://github.com/castano/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). https://developer.mozilla.org/en-US/docs/Mozilla/Projects/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/
- 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/
- gloox: gloox is a rock-solid, full-featured Jabber/XMPP client library, written in clean ANSI C++. It makes writing spec-compliant clients easy and allows for hassle-free integration of Jabber/XMPP functionality into existing applications. http://camaya.net/gloox/
- iconv: iconv is a computer program and a standardized application programming interface (API) used to convert between different character encodings.
- icu: ICU is a mature, widely used set of C/C++ and Java libraries providing Unicode and Globalization support for software applications. http://site.icu-project.org/
- 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/
- 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/
- miniupnpc: The MiniUPnP project offers software which supports the UPnP Internet Gateway Device (IGD) specifications. http://miniupnp.free.fr/
- 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/
- sdl2: 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.)
i18n
Internationalization and Localization support for the engine.
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.
scriptinterface
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.
dist
Tools for packaging the game.
entity
Some entity tools, the most useful is checkrefs.pl, which scans a lot of game data for duplicate and missing references.
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\.
i18n
Tools for Internationalization and Localization.
openlogsfolder
Scripts for opening the logs folder on Windows.
profiler2
Web client for the game's built-in profiler.
replayprofile
Extracts profiling data from replays, for graphing purposes. See EngineProfiling.
selectiontexgen
Generates basic square and circle selection overlay textures by parsing all the entity XML files and reading their Footprint components (see script for details).
templatessorter
Utility to sort the component definitions of entity templates into alphabetical order.
For a more recent tool written in Python, see Phabricator.
XpartaMuPP
Scripts for the multiplayer lobby.
TODO - DESCRIBE THE OTHERS
