|Version 14 (modified by historic_bruno, 14 months ago) (diff)|
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, some data saved during games is stored in a separate location, depending on the user's OS:
- Windows: local user data is stored in %appdata%\0ad\ (and %localappdata%\0ad\ for cache and logs, when available)
- Linux: local user data is stored in ~/.local/shared/0ad/ and ~/.config/0ad/
- Mac OS X: local user data is stored in ~/Library/Application Support/0ad/ and ~/Library/Caches/0ad/
A typical user data directory is arranged like this:
- cache: Game data cached for more efficient access.
- config (see below)
- screenshots: PNG and BMP screenshots from the game.
- logs: Logs files and crash dumps.
- sim_log: Includes data for precisely replaying a simulation.
Screenshots, logs, config files, and crash dumps generally end up in these directories.
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.
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. For official releases, the mod is compressed into a ZIP file. Mods can be selectively loaded by users, for a different game experience.
See the mod layout page for details.
Some data associated with tools separate from the engine itself, like Atlas and font builder.
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.
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.
Some analysis scripts for Dehydra, a tool for custom static analysis of C++ code.
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.
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.
- 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/
- 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
- 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/
- 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/
- 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/
- 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/
- 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 (.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.
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.)
Low-level code for the engine, including abstractions of specific systems by OS and architecture.
Defines classes for typical mathematical operations.
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.
OBSOLETE! This code is no longer used and contains the old simulation source code, for reference only and will be deleted at some point.
Defines a few classes to abstract sound management from the lower-level snd_mgr.
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.
The autobuild utility compiles the Windows executable that is included in the SVN repository.
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\.
Utility to sort the component definitions of entity templates into alphabetical order.
Utility to convert textures to DDS format.
TODO - DESCRIBE THE OTHERS