Mod manifest

Oliver Brakmann edited this page Jul 8, 2016 · 7 revisions
Clone this wiki locally

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 the system mod directory (wherever the game was installed) or the user support directory:

OS Path to the support directory
Windows My Documents\OpenRA\mods\<mod name>
Mac OSX ~/Library/Application Support/OpenRA/mods/<mod name>
Linux ~/.openra/mods/<mod name>

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