The JSDebugger did not have keybindings for the different debugging actions like Step, Step-Into, Continue, Break, etc. And that’s what we added. Though this was child’s play, it certainly feels amazing to have actually contributed something. Oh, it does not stop there! Its committed in SVN revision #14014! :D
Check it out –> Ticket #2208.

The first thing to know is that 0 A.D. uses a lot of wrappers and home grown entities like a string class, filesystem class, a compressor, parsers for parsing game related files, thread managers, etc. All such classes can be found in source/ps directory (ps stands for pyrogenesis, the name of the game engine). But what interests us, lies in the source/simulation2 directory. This contains all the core components that are used by the Engine to communicate with the simulation aspects of the game. So what do we have here?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

(0ad)source@svn : simulation2$ tree
.
|-- components/
|-- docs/
|-- helpers/
|-- scripting/
|-- serialization/
|-- system/
|-- tests/
|-- MessageTypes.h
|-- Simulation2.cpp
|-- Simulation2.h
`-- TypeList.h

7 directories, 4 files

Majority of the code here resides in the components/ directory. This has most of the major components (as the dir name suggests) required for running handling the simulation, including code which runs the scripts written in JS. Most of the components are implemented with an supposed-to-be-interface class which the actual component class inherits. Example, CCmpAIManager inherits ICmpAIManager; where the first letter represents a class or interface respectively. (more info on the coding guidelines and conventions can be seen here)

Since our main target is the AI, let’s try to understand how the AI begins. A lot of components are registered in the game; one of them being the AIManager component, defined in CCmpAIManager.cpp. This has the CCmpAIManager class. Before going to the details of this class, let us see something very interesting.

The source uses SpiderMonkey to bind C++ and JS. The C++ source exposes a variable called Engine to the JS runtime, which is an instance of the ScriptInterface class. This is created in the singleton ScriptingHost class. The singleton object creating is handled through a Singleton base class. So what’s the result? The JS runtime can now access the C++ routines through the Engine object (which internally is an object of ScriptInterface).
The next step would be to attach routines to this Engine object so that they’d be exposed to the JS runtime and this is done through the RegisterFunction function, in the file NativeWrapperDecls.h which registers a C++ function with the Engineobject. So if a function named Foo is registered, then this function can be accessed in JS as Engine.Foo(). Ain’t it a beauty??!

So, we have a function Script_QueryInterface of the CComponentManager class registered with the Engine object with the name QueryInterface. What this does is give an object of the queried interface. So to obtain an object of the AIManager component, (whose interface is ICmpAIManager and implemented in CCmpAIManager; henceforth, we’ll call this AIManager) all we need to do is use Engine.QueryInterface. To specify that we require the AIManager component, the ID is passed as the second argument to this function. The ID of each component is declared as an enum in source/simulation2/system/Components.h. This is exactly what the script InitGame.js#L13 does. So there it is! The JS runtime’s access to the Engine’s AIManager through the JS object cmpAIManager; this object is the gateway for all communication between C++ and JS (those related to AI)

Now lets unwind our discussion stack. “How does the AI start?” was the question we started off with. Understand that cmpAIManager is an object of the AIManager component. This component has a function – AddPlayer, defined in CCmpAIManager. If you check InitGame.js#L20, this function is called through the cmpAIManager. The CAIWorker class implements the worker thread for the AIManager. An object of this class is stored in CCmpAIManager as m_Worker. The AIWorker class has an AddPlayer function. This is called by the AIManager’s AddPlayer function. You can observe this here.
The CAIWorker.AddPlayer function initializes the AI by calling the appropriate AI module (The directory of the AI-bot which contains all the relevant AI scripts. The order of functions that are called go like this -
The AIManager.AddPlayer[1] calls the AIWorker.AddPlayer[2]. This first initializes the AI by calling AIPlayer.Initialize[3] which in turn calls AIPlayer.LoadScripts[4]. This function is responsible for loading the AI module by using ScriptInterface.LoadGlobalScriptFile[5] which physically loads and executes the script file using SpiderMonkey bindings.

And there you go! The AI module is loaded! So, while setting up the game, if you select the AI bot as Aegis Bot for an AI Player, then the aegis module will load. Make a note of the file _init.js[6] in the module. This file loads modules which are to be loaded before the rest of the current module is loaded. For example, the Aegis Bot requires Common API v3 to be loaded (you can have a look at the Common API v3 module here). Also note that Engine.IncludeModule is registered to CAIPlayer::IncludeModule[7] (which can be seen here) which again calls the AIPlayer.LoadScripts[8] function.

Phew! Learning how the JS is executed is one exhausting task! See you in the next post. Bye!

Also, you can access the doxygen generated doc of the game’s source available here. This documentation will be regularly updated and will be referred to throughout the blog.

If you build the game on your own, using the source, you typically get a binary pyrogenesis in the binaries/system directory and the game will be using data or scripts present in binaries/data/mods/public; unless the game is compiled with some flags specifying the binary, data or lib directories while setting up the workspace (info can be found here).

So let’s begin! When the game is run, it starts off by performing some initializations.

1. The thread on which the game started is marked as the main thread and its named “main”. [GameSetup.cpp:827]
2. The current time is noted so that elapsed time can be counted from this point. [GameSetup.cpp:838]
3. The profiler is initialized and started. The profiler is used for analysing framerate fluctuations or glitches and temporal relationships between threads. [GameSetup.cpp:842]
4. The locales are set for the game execution depending on the OS. [GameSetup.cpp:844]

After this is done, the game is then ready to start running. Now,

1. The command line arguments are interpreted (if any given). [main.cpp:446]
2. A virtual file system is created and the game’s cache and data are loaded. [main.cpp:465]
3. The game is now started and the graphics initialized. [main.cpp:504]
4. The input handlers are initialized and set. [main.cpp:506]

By now the game is up and running and the profiler would be capturing every frame. When the game is quit, the shutdown sequence starts. You can see all this starting from source/main.cpp and related files. There’s just too much code to inline in the post!

While this certainly gives a fair idea of how the game begins, its worth noting some classes and features available in the source.

The Core Engine modules are placed in source/ps/ directory and they are used all over the source. A few of them are –

1. ArchiveBuilder: Used to package mod files into distributable archives.
2. Console: The in-game scripting console.
3. ConfigDB: Manage configuration variables for the game.
4. CStr: A string wrapper designed to provide better string handling.
5. Filesystem: A class to provide filesystem-like functionality to the API which makes it easier to access files for the game.
6. GameSetup/CmdLineArgs: A class to parse the command line arguments.
7. GameSetup/Paths: Wrapper class for OS Paths used in the game.

… and many more! You can have a look at the directory to view all the files in it. Our work isn’t done yet! Our initial focus has been on the AI which we’ll be covering next.

To be continued …

This post is aimed to give you an overview of some aspects of developing 0 A.D. Although these details are available in the wiki, they are not yet structured in an understandable way. Here, we gather many wiki articles and also provide some information on how the game is structured.

What does the root directory contain?

Let’s have an overview of it first.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

(0ad)source@svn : /$ tree
.
|-- binaries/
|-- build/
|-- docs/
|-- libraries/
|-- source/
|-- license_dbghelp.txt
|-- license_gpl-2.0.txt
|-- license_lgpl-2.1.txt
|-- LICENSE.txt
`-- README.txt

5 directories, 5 files

binaries → This contains all of the game’s data, scripts that are executed during the game, mods and other executables (typically for windows). This is what goes to the end user.
build → This has the necessary tools and programs to set up a workspace to build the game. More instructions on how to build the game can be seen here.
docs → All documentation goes here.
libraries → Placeholder for third-party libraries used in the game. However, they may or may not be used.
source → This contains the source of the game engine and the source of other tools that are associated with the game (Eg: The scenario editor).

Are there more details available?

A more detailed information on what these directories (and their subdirectories) contain can be found here.

What resources are available for a contributor to learn more about the game?

The first is the trac wiki. This has a lot of links for all kinds of contributors – artists, programmers, etc. The next place are the game forums. One needs to register for the forums and there are 5 categories of forums available; the description of which can be seen under the link to the particular forum. And lastly, the best place to communicate is the IRC. You can join the channels#0ad and #0ad-dev in QuakeNet and jump right into a live discussion over there!

What are the languages used to implement the game design?

The source of the game is written in C++ and JS. Interesting right?
The convention is to have as much of the game’s source in JS as possible (to keep it simple) and only write the core game engine and those components which need performance in C++. This enables the game to be heavily moddable through JS.

I would like to be a developer and was wondering how to start with the game-dev. Any tips?

As we said, the trac wiki is the entry point for getting a picture of the game’s structure. The next step would be to start reading the source (which is discussed from the next post onwards). You’ll also need to know the coding guidelines and conventions that are followed so you can understand the source better and also will get you prepared when you start with the development. You would also need to learn how to build the game, which for a developer, is vital. You can then look at some tickets available on trac and try to solve a few easy ones. This actually kickstarts the development and helps you to learn more about the internal structure of the game. You can start off with a few beginner-level tickets.

What is 0 A.D. ?

0 A.D. is a historical Real Time Strategy game being developed by Wildfire Games. It all started by a collaborative effort of three modding communities in 2001/2002. You can read The Story of 0 A.D. to know the full story. The game was open sourced in July 2009 and has been quite a star in the open source gaming world.

Who we are.

We are a team of two; myself, Sathyam M Vellal and my teammate Jashwanth Reddy M and we have enrolled into “Architecture of Open Source Technologies”, an elective being offered in our college. This elective requires us to contribute to an open source community through the semester and we decided to contribute to 0 A.D.

Why 0 A.D. ?

Every open source community has its share of awesome developers and mentors. What makes this better? An open source community developing a game. Nearly half the community is online most of the day and developing some feature. What I like most about this community is the relaxed discussions they have. Its serious, yet fun and fun, yet technical. Well, if these aren’t enough, I have an excuse to play the game any time I want now! Even during class! By the way, the game has amazing graphics; have look at some screenshots and it has an incredible soundtrack!

0 A.D Docs and Info

The developer devil – Documentation. Nobody wants to write it, yet everyone wants to read it. Although 0 A.D. is not too different from others in this regard, the game is still highly structured with information present online to help a developer start his work. The root of all info is trac. And there’s always IRC for everything else.

This blog is for us to record our adventure in exploring and contributing to 0 A.D. Stay tuned for more updates!