Table of Contents
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.
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.
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.
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.
Internationalization and Localization files for the engine.
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.
Contains some non-mod data and scripts used by the test suite.
Some data associated with tools separate from the engine itself, like Atlas and font builder.
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.
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.
Some utilities for the build process.
A tool for generating the error and exception codes used in the game.
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).
Icons and data files for the game's installer.
Utility for outputting the current game build's revision number.
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)
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.
Contains a script for building OS X dependencies, see BuildInstructions#OSX.
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
- 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/
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/
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 (
.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.
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.
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.
Defines GUI (graphical user interface) classes for 2D objects with which the user interacts during the game (buttons, text, lists, minimap, etc.)
Internationalization and Localization support for the engine.
Low-level code for the engine, including abstractions of specific systems by OS and architecture.
Contains code to support using the XmPP-based multiplayer lobby.
Defines classes for typical mathematical operations.
Contains code related to the cxxtest suite.
Defines classes for supporting multiplayer, networked games with a server-client architecture.
Precompiled headers for faster compilation of the game.
Contains miscellaneous code, useful throughout the engine. (Short for "Pyrogenesis" - the name of the engine)
Defines classes for rendering 3D things during the game. These are the implementations used in the rendering loop.
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.
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 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.
Tools for packaging the game.
Some entity tools, the most useful is checkrefs.pl, which scans a lot of game data for duplicate and missing references.
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
Tools for Internationalization and Localization.
Scripts for opening the logs folder on Windows.
Web client for the game's built-in profiler.
Extracts profiling data from replays, for graphing purposes. See EngineProfiling.
Generates basic square and circle selection overlay textures by parsing all the entity XML files and reading their Footprint components (see script for details).
Utility to sort the component definitions of entity templates into alphabetical order.
For a more recent tool written in Python, see Phabricator.
Scripts for the multiplayer lobby.
TODO - DESCRIBE THE OTHERS