0 A.D. Modding Guide


If you're looking for how to play 0 A.D. or are not otherwise familiar with it, see the Getting Started page.

This guide is intended for users who have experience playing 0 A.D. and want to take that knowledge to the next level by "modding" or modifying the game. As 0 A.D. is still in alpha stages and under constant development, the documentation is also in early stages. Features are likely to change drastically, even the process for modding is subject to change. Those interested in modding the game at this point will almost need to be "developers" in the sense of solving problems and researching the means of modding, and will often need to be familiar with multiple facets of the game. Also at this stage, completing the game's core functionality is a priority, so well made mods could become part of the official game, if the contributor desires.

The best resources for modding advice are the forums (there is a subforum dedicated to modding) and IRC: #0ad-dev on QuakeNet. But some of the most common questions or problems will hopefully be answered here.

What can be modded?

0 A.D. has been designed from the beginning for ease of modding. Not just art and sound, but also the code which makes the game come to life. All the textures, 3D models, animations, sounds, fonts, and scenarios found in the game are packaged into "mods" (modifications). Additionally, a large amount of the game's logic (written in JavaScript) is packaged in mods. Some of the software behind 0 A.D. is called the Pyrogenesis "engine", written in C++. The engine does not change with mods. The game itself is actually one or more mods bundled together with the engine. As 0 A.D. is free open source software, the engine can certainly be modified by those interested, but we don't call this a "mod" in the strict sense because it might break compatibility with existing content.

Where are the mods?

Mods are located in the game's installation directory (or relative to checkout for SVN users). Typically mods are located in binaries/data/mods/, but you can also add them to the mods (data) directory as noted in GameDataPaths. A mod is defined by a folder inside the mods directory with the relevant files inside of it. Files are expected in certain locations, so a mod should follow the same structure as the public mod included with the game. Mods can be archived into a .zip file for compression and ease of distribution.

See the mod layout or Finding Your Way Around pages for more details.

How are mods used?

The game has a mod selection screen, which can be accessed through the main menu: Tools & Options > Mod Selection

Mod Selection screen in Alpha 17

Or if you prefer, mods can be selected via command line arguments. You can run the game with the -mod option, like so:

pyrogenesis.exe -mod=public -mod=mymod -mod=anothermod ...

This will load the public mod first, then add all files from mymod, then adding all files from anothermod (replacing all already present files) and so on.

The mod mod is currently always loaded by default. Any files or folders in the public mod might be replaced or added to in a new mod. In fact by replacing the main menu page, it's possible to achieve a totally different game experience, without reusing any of the public mod (though it would require a lot of work).

Which tools are needed?

Say you have an awesome idea for a 0 A.D. mod. What else do you need (besides the game)? There are many choices depending on your focus. Do you want to add textures? Or maybe you want to modify AI scripts? The following list gives a few tools that are handy for modding 0 A.D.:


Many consider Photoshop to be the gold standard for editing images, but there are other choices. GIMP is a popular, free image editing tool which supports a wide range of features and formats. The main required features for modding 0 A.D. textures are the ability to handle PNG images including alpha transparency and, for older textures, a plugin for DDS format (textures are automatically converted from PNG to DDS by the engine, but PNG is a more widely supported format).

3D models and animations

0 A.D. supports the COLLADA format for importing new models into the game, whether static or animated. A number of 3D modeling suites support COLLADA, but only a few are used in practice and have been confirmed to work with the game:

  • 3DS Max: commercial, professional-quality suite.
  • Blender: free, open source alternative. COLLADA support varies from one version to another, we recommend 2.6+ for animations.

Sound effects and music

The game uses OGG Vorbis, a widely supported encoding format, for music and sound effects. Sound effects are "grouped" which allows the game to adjust volume, pitch, and other parameters, and to play them randomly. Groups are defined by XML data files placed next to the sound files (see the audio mod directory for examples).

Scripts and data files

Many text editors exist for editing basic text and scripts, so this mostly boils down to platform and user preference. The main features to look for in an editor are syntax highlighting, handling of different line endings and encodings, customizable tabbing, and anything else that makes life easier. Some choices:

  • Eclipse: heavy duty IDE supporting many languages
  • Notepad++: Windows text editor with enhanced features (the Notepad included with Windows is a very poor choice)
  • Unix-based tools (e.g. vim, GNU Emacs)

Additionally, if you want to mod the latest greatest version of the game, you might consider getting the latest data from SVN. For Windows users we provide a precompiled version of the game in SVN, so programming/compiling knowledge is not required. Still you will be expected to have a working knowledge of Windows, file management, and basic troubleshooting. See the build instructions for details on acquiring the latest version of the game for your OS.

How to make your mod show up in the mod selection screen

You need to add a mod.json file to your mod folder. See the public (0 A.D.) mod's mod.json file for a real world example of an standalone mod.

The following is a (nearly minimal) sample:

    "name": "samplemod",
    "version": "1.2.34",
    "label": "Sample Mod",
    "description": "This is an example discription",
    "dependencies": ["0ad=0.0.19"]

There are also the url and type properties which are optional. name must be unique and must not contain whitespace. dependencies is an array that contains the name of mods it depends on, optionally with version constraints (<,<=,==,>=,>) and the versions of the dependency.

For details of how the dependency checking is done please read the function comments in modmod.js.

Distributing your mods

The pyrogenesis binary also has an archive builder, to compile your mod into a zip file and pre-cache your textures (so users don't see grey textures on the first run). The zip isn't compressed by default, but if your mod becomes big, and you don't compress it afterwards (i.e. to distribute with an autoinstaller exe), it's advised to compress your mod with the archive builder.

The command line arguments to build the archive look as following:

binaries/system/pyrogenesis -mod=mod -archivebuild=binaries/data/mods/mymod -archivebuild-output=mymod.zip -archivebuild-compress

This produces the distributable mymod.zip in your working directory. If users now install it like the distributed public mod (i.e. under mods/mymod/mymod.zip), they can run it with the "-mod=mymod" command line argument as explained above.


  • Basic3DImplementation - Instructions on how to create a simple, static 3D model in Blender, texture it with GIMP, and import it into 0 A.D. as a new actor.
  • CreatingNewUnits - A simple beginner's guide about setting up a mod and editing actors and templates.
  • Modding GUI and Simulation - A guide on how to best mod the scripts of the game without ending in a maintenance hell.
  • Modding Resources - A Guide to Modding Resources (for now, adding and removing resources)
Last modified 2 days ago Last modified on Jul 23, 2017, 12:55:40 AM

Attachments (1)

Download all attachments as: .zip