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/Logs or ~/.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.

The Metadata block defines some basic properties that are shown in the mod chooser.

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

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

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:

Example for a fictional XY mod:

Packages:
	.
	~^Contents/xy
	./mods/common: common
	$ra: ra
	$xy: xy
	MAIN.MIX
	~VIDEOS.MIX
	ra|bits
	xy|bits