Mod manifest - OpenRA/OpenRA GitHub Wiki
Mod manifest
The mod manifest is contained in a single file called mod.yaml in the mod's top-level directory. It contains metadata about the mod, as well as a list of files that make up the rest of the mod definitions, such as the UI chrome, actor rules and sequence definitions, to name only a few.
The game will look for the mod.yaml files in all sub-directories or oramod packages found in the system mod directory (wherever the game was installed) or the user support directory:
- Windows:
%APPDATA%\OpenRA\Logs\or%USERPROFILE%\Documents\OpenRA\Logs\(older installations) - Mac OSX:
~/Library/Application Support/OpenRA/Logs/ - Linux:
~/.config/openra/Logsor~/.openra/Logs/(older installations)
This article aims to explain the different entries, as well as the special syntax used to refer to files in the "virtual filesystem" used by OpenRA.
mod.yaml Entries
| Entry | Purpose |
|---|---|
| Metadata | Defines basic properties like the name, version and author(s) of the mod. |
| RequiresMods | Lists the name and version of the mods required for this mod to run, if any. |
| Assemblies | This lists the .dlls with the game code that the mod makes use of. |
| ContentInstaller | Used to enable installation of game data from CD or the internet. |
| Packages | Lists paths and archives that contain the mod data and game files. Also sets up handy shortcuts. |
| MapFolders | A list of the directories where maps can be found. |
| SupportMapsFrom | A list of mods whose maps are compatible with this mod. Does not automatically load maps from those mods. |
| Missions | Lists one or more yaml files that in turn list all of the maps that should show up in the single-player missions window. |
| MapGrid | Defines the layout of the map coordinate system and the cells used by the game. |
| TileSets | Lists one or more yaml files that define the available tilesets usable by maps, e.g. snow, temperate, interior and so on. |
| Rules | Lists one or more yaml files that define the actors that make up units, buildings, decorations and so on in the game. |
| Sequences | Lists one or more yaml files that set up the artwork for all the actors. |
| Weapons | Lists one or more yaml files that define the weapons and warheads used in-game. |
| Chrome | Lists one or more yaml files that create graphics usable for the UI from spritesheets. |
| ChromeLayout | Lists one or more yaml files that define the UI layout. |
| ChromeMetrics | Lists one or more yaml files that define default colors, fonts, text sizes etc. for the UI. |
| Fonts | Lists one or more yaml files that define all of the available fonts that can be used by the UI. |
| Cursors | Lists one or more yaml files that define all the available cursors. |
| LoadScreen | Sets up the load screen used for the transition between the menu and in-game. |
| SoundFormats | Lists all required sound formats. |
| Voices | Lists one or more yaml files that define all sounds used for unit voices. |
| Notifications | Lists one or more yaml files that define all sounds generated by the UI. |
| Music | Lists one or more yaml files that define the available music tracks. |
| Translations | Lists one or more yaml files that define the available languages. |
| SpriteFormats | Lists all required sprite formats. |
| SpriteSequenceFormat | Can be used to define additional per-tileset file extensions for graphics files. |
| ServerTraits | Lists all the traits that should only run on the server. |
| GameSpeeds | Defines the different game speeds available for selection in the lobby. |
| ColorValidator | Used for color validation in the multiplayer lobby. |
Metadata
The Metadata block defines some basic properties that are shown in the mod chooser.
| Property | Type | Purpose |
|---|---|---|
| Title | string | The name of the mod. |
| Version | string | The version of the mod |
| Description | string | The description of the mod. This text will be shown in the mod chooser next to the preview image. |
| Author | string | The author(s) of the mod. |
| Hidden | bool | Whether the mod should be shown in the mod chooser. |
RequiresMods
RequiresMods lists all the other mods that this mod requires to be installed to be run. Each list entry is a key-value pair, with the key being the id of the mod (like "ra", for example), and the value being the required version.
If you don't require any mods, it is still good practice to mention the modchooser here, with the version set to whatever OpenRA version your mod works with.
Example:
RequiresMods:
ra: playtest-20160424
modchooser: playtest-20160424
Assemblies
The Assemblies block lists all the game logic .dlls that your mod needs to work, one per each line. You will very likely need at least the OpenRA.Mods.Common.dll, since it contains the bulk of the game logic.
Example:
Assemblies:
common|OpenRA.Mods.Common.dll
ts|OpenRA.Mods.TS.dll
Packages
The Packages section lists all of the locations (archives and directories) that contain the mod's game data files. These locations will be used as a "search path" whenever a filename is referenced in the mod's yaml files. It can also setup handy shortcuts that make path references less verbose.
Each entry is a single line. It can contain either a single path specification, or a key-value pair, where the key is a path specification and the value is a shortcut (called an "explicit mount" or "explicit package") that can from then on be used to refer to that path.
A path spec can take several forms, and there are several characters with a special meaning. These will be explained now.
The most simple form of a path spec is just a filename. The file will be searched for in all other packages that have been declared up to that point, so there is no need to use a full path. Prepending a ~ in front of a filename makes that file optional. If a required file cannot be found, the game will crash immediately when the mod loads.
Sometimes it is necessary to refer to specific locations of an OpenRA installation. A single . points to the mod's installation directory (where the mod.yaml file is located). Paths beginning with ./ are interpreted relative to the game's installation directory, whereas a ^ is a shorthand for the user's support directory.
Different mods can also be referenced using the $ character. It will probably make sense to add mods that get referenced like that to RequiredMods.
For mod packages and locations that contain the same filenames as other ones, it's useful to setup explicit mounts. These can be used as a shorthand notation to make path references less verbose, and also cause filename lookups to prefer the explicit package over others. Only if the file cannot be found in that explicit package will others be consulted.
List of special characters:
| Character | Meaning |
|---|---|
| . | Refers to the mod's main directory (where mod.yaml is located). |
| ./ | Paths starting with ./ are relative to the game directory (where the game is installed). |
| ~ | Indicates that the path is optional. |
| ^ | Points to the user support directory (see the table on top of this page) |
| $ | Indicates a reference to a mod package (e.g. $ra means "wherever the ra mod is installed"). |
| | | Used to denote references to explicit packages (e.g. "ra|missions.yaml") |
Example for a fictional XY mod:
Packages:
.
~^Contents/xy
./mods/common: common
$ra: ra
$xy: xy
MAIN.MIX
~VIDEOS.MIX
ra|bits
xy|bits