Table of Contents
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?
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.
How are mods used?
As of Alpha 17, the game has a mod selection screen, which can be accessed through the main menu: Tools & Options > Mod Selection
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=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 public 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)
- Try the game's new web-based script debugger which is a customized tool for debugging 0 A.D. scripts. With this tool, you can step through the game's UI, AI, and component scripts with ease and view variables' contents.
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.
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.