wiki:Modding_Guide
Last modified 13 months ago Last modified on 2013-04-02 22:46:54

(Note: under construction!)

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 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?

At some point we plan to have a graphical menu for selecting mods. For now, 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.:

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)
  • 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.

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.