0 A.D. Modding Guide
Introduction
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](http://webchat.quakenet.org/?channels=0ad-dev). 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 distributed with, or as part of, 0 A.D. are located within the game's installation directory, under binaries/data/mods/
.
User created mods should be located in a user's mods directory. The exact location differs depending on which Operating System you're running:
- On Windows (Vista or newer):
C:\Users\{name_of_user}\Documents\My Games\0ad\mods\
- On OSX:
~/Library/Application Support/0ad/mods/
- On Linux:
~/.local/share/0ad/mods/
(may be found in GUI via Home/.local/share/0ad/mods/)
(Mods acquired via the mod.io interface will be stored here by 0 A.D.)
Each mod is contained within its own folder, which should have the same name as the mod. Thus, a mod named my_awesome_mod
would be placed in the folder ./0ad/mods/my_awesome_mod/
.
This folder then contains all files belonging to the mod, either as a collection of subfolders and files:
Or, once ready for distribution, packaged as a single .zip
or .pyromod
file:
Files are expected in certain locations, so a mod should follow the same structure as the public
mod included with the game. See the mod layout or Finding Your Way Around pages for more details.
How to install mods?
Mod files can be directly opened with 0 A.D. for installation or updating. .pyromod
files should be associated with 0 A.D., if not or if the mod is a .zip
file you can install that way: right-click on them and open them with 0 A.D.
For those preferring the command line, that operation is equivalent to running
pyrogenesis modfile.pyromod
# or
pyrogenesis modfile.zip
You will then land in the mod selection screen, described in the next section.
Advanced only
You can manually place mods into your mods folder but you have to ensure the folder and zip base name match the mod name in mod.json. If you extract the mod so you can further work on it beware a properly packaged mod is a zip-bomb. You can also clone a repository if such exists or create a symlink to such in an other place.
How are mods used?
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=mod -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.:
Textures
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]source:/ps/trunk/binaries/data/mods/public/audio 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]source:ps/trunk/binaries/data/mods/public/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 description",
"dependencies": ["0ad=0.0.23"]
}
- A mod is identified by the directory name.
- A mod must define the "name", "version", "label", "description" and "dependencies" property.
- The "url" property is optional.
- The property "name" can consist alphanumeric characters, underscore and dash.
- The name is used for version comparison of mod dependencies.
- The property "version" may only contain numbers and up to two periods.
- The property "label" is a human-readable name of the mod.
- The property "description" is a human-readable summary of the features of the mod.
- The property "url" is reference to a website about the mod.
- The property "dependencies" is an array of strings. Each string is either a modname or a mod version comparison.
- A mod version comparison is a modname, followed by an operator (=, <, >, <= or >=), followed by a mod version. This allows mods to express upwards and downwards compatibility.
For details of how the dependency checking is done please read the function comments in [modmod.js]source:ps/trunk/binaries/data/mods/mod/gui/modmod/modmod.js.
License
0 A.D. is released as open source: you can freely use, copy, modify and distribute the game's source code and data files, as long as you include attribution to Wildfire Games and let anyone freely modify and distribute any of your own modifications to the game's files.
Source: https://trac.wildfiregames.com/browser/ps/trunk/LICENSE.txt
Most art files are released under CC-BY-SA-3.0, while most code is released under GPLv2. You can use the link above (LICENSE.txt) to see exactly what asset is released under what license. So if you copy art/ code originating from Wildfire Games (e.g. from 0 A.D.), you need to specify the correct license and explicitly mention which files are licensed under it. A simple .txt file listing these files is sufficient, again you can see how in the link above (LICENSE.txt).
Although this is not really necessary, it is common practice to include the relevant licence files in your mod (e.g license_gpl-2.0.txt).
You can publish art or code under any license if you created it yourself. Make sure that files that are not yours or Wildfire Games are properly licensed.
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 -mod=public -mod=mymod -archivebuild=binaries/data/mods/mymod -archivebuild-output=mymod.pyromod -archivebuild-compress
On windows you'll have to be careful with dots and '/' the command will be more like:
binaries\system\pyrogenesis.exe -mod=mod -mod=public -mod=mymod -archivebuild="binaries\data\mods\mymod" -archivebuild-output="mymod.pyromod" -archivebuild-compress
This produces the distributable mymod.pyromod in your working directory. If users now install it as explained [#Howtoinstallmods above], they can run it with the "-mod=mymod" command line argument as explained [#Howaremodsused above].
You may want to publish your mod on the mod.io platform. If you do so, your mod will be available in the 0 A.D. mod downloader. To avoid security issues, we take some extra validation steps: follow the guide on the forums.
Tutorials
- 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)