Version 35 (modified by elexis, 6 years ago) ( diff )

Clarify licensing.

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. 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/

(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:

Example of a mod folder - collection of files

Or, once ready for distribution, packaged as a single .zip or .pyromod file:

Example of a mod folder - packaged

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?

You can place mods manually into the mods folder as described above. However, mod files can be directly opened with 0 A.D., which copies the data to those locations automatically. .pyromod files should be associated with 0 A.D. depending on your operating system, but you can also install .zip files 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.

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.:

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 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.22"]
}
  • 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.

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.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=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 above, they can run it with the "-mod=mymod" command line argument as explained 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.

Licensing

The code of 0 A.D's is licensed under GPL v2 or a later version.

So mods that modify this code must be licensed under a GPL v2+ compatible license.

While it is situational whether newly added files count as a modification of the code of 0 A.D., if a mod copies and modifies a file of that code, it certainly is affected by the GPL.

Have a quick look at our LICENSE.txt file for example. Add a custom LICENSE.txt to your mod folder to explain the licensing when redistributing the mod and list all copyright holders whose work you have reused.

If you reuse or modify our art files, notice most them are licensed under a Creative Commons license and not GPL. If you distribute copies or modifications of other peoples art files, make sure you have permission to do so and mention the terms of the permission in the license file. This allows other people to determine whether and how they can reuse and modify these files of your mod.

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)

Attachments (3)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.