Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
This document describes the map format
11 that was first released with
OpenRA will load maps from the map directories specified in the
MapPackages section of
mod.yaml. Maps can either be packaged as a zip file (named with the
.oramap file extension), or left as an unpacked directory.
The map package (oramap or directory) contains:
map.yamldefines the map metadata, player information, actors, and rule overrides.
map.bindefines the map tiles, height information (for mods that use terrain height), and harvestable resource data.
map.pngcontains the map preview that is used by the game UI and external tools.
- (optional) Additional yaml files that may be referenced from
map.yamlcontaining custom rules, sequences, etc.
- (optional) lua files that may be referenced from
map.yamlor external rule files, containing map scripts.
- (optional) Custom artwork and sounds that may be referenced from
map.yamlor external rule files.
map.yaml consists of a number of yaml sections, described below.
Denotes the version of the map format that this map uses. OpenRA will only load maps of the latest supported format. The
--upgrade-map utility command can be used to update older format maps to the latest supported format.
The id of the mod that the map is created for. This must match one of the entries in the
MapCompatibility list in
mod.yaml for the map to be loaded.
The map title that is shown in the game UI.
The map author that is shown in the game UI.
The tile set that the map uses. Must match one of the tile sets that are referenced via
The size of the internal data arrays. Do not edit by hand. The
--resize-map utility command can be used to resize the map data.
The visible area of the map, specified as
left, top, width, height in map-cell coordinates relative to the top-left cell. A 1-cell cordon is required on each side between the visible area and the edge of the map. Mods that specify a non-zero terrain-height must specify a top-cordon of
<maximum terrain heigh> + 1.
Defines where the map is visible/used by OpenRA. Accepts values
Lobby for regular maps,
MissionSelector for single player missions, or
Shellmap for the scripted menu backgrounds.
Maps that define
Visibility: MissionSelector are expected to define a custom map preview with a size matching the conventions for the specific mod, as well as a
Rules section override defining the
MissionData world trait with the map briefing and other mission data.
A list of categories that are used for sorting maps in the map chooser. The first category is treated as the map's game type, which is shown in several parts of the game UI.
This is an optional section (it is not saved to map.yaml if it is not defined) that will disable automatic
map.png creation if it is set to
Enable this option if you choose to include a custom map preview.
A list of
PlayerReference nodes, each defining a player in the map. Each player "slot" must have an associated player reference, and additional references exist for "map" players such as Neutral (for trees, civilians, tech buildings, etc) and Creeps (for hostile actors such as Visceroids in the Tiberian Dawn mod).
A list of
PlayerReference properties are available:
|Name||The internal name/id for this player|
|Bot||The default bot type assigned to this player|
|StartingUnitsClass||Overrides the starting units class used by this player|
|AllowBots||Allow bots to be selected for this player|
|Playable||Allow players or bots to be assigned to this player in the lobby|
|Required||Require a player or bot to be assigned to this slot in the lobby|
|OwnsWorld||Used for the "Neutral" player. Must always be defined on "Neutral" and never on another player|
|Spectating||Designate a player slot for spectators. DO NOT USE|
|NonCombatant||Designate the player as a non-combatant player (affects tooltips and victory conditions|
|Faction||The default faction for this player|
|LockFaction||Prevent the default faction from being changed in the lobby|
|Color||The default color for this player|
|LockColor||Prevent the default color from being changed in the lobby|
|Spawn||The default spawn point (0: random, >= 1 for spawn >= A) for this player|
|LockSpawn||Prevent the default spawn from being changed in the lobby|
|Team||The default team for this player (0: no team)|
|LockTeam||Prevent the default team from being changed in the lobby|
|Allies||A list of other player names that are considered allies by this player|
|Enemies||A list of other player names that are considered enemies by this player|
A list of
ActorReference nodes, each defining an actor on the map.
ActorReference is defined by a key: value pair. Keys are arbitrary, but must be unique, and are exposed to scripts via the
NamedActors lua api. The value is the internal actor type for the actor.
Child nodes then denote initial state that are used when creating the actor. These properties are defined by mods (so it's not possible to provide a definitive list), but some common ones are listed below:
|Owner||Required: defines the
|Location||The cell location of the actor on the map|
|CenterPosition||The world position of the actor on the map (only used for actors that don't use the
|Facing||The facing of the actor. 0 corresponds to North, and larger values rotate anticlockwise to 255|
|Subcell||The subcell index used by infantry and other actors with the
|Health||The initial actor health as a percent of its full health|
Rules, Sequences, VoxelSequences, Weapons, Voices, Music, Notifications, Translations
These sections are optional (they are not saved to map.yaml if they aren't used) and allow the map to override the default mod rules (/sequences/etc) with custom modifications.
Overrides can be specified in two ways, which are best demonstrated by example:
Rules: cnc|rules/campaign-palettes.yaml, rules.yaml World: LuaScript: Scripts: gdi01.lua
Filenames listed after the
: are treated as external rule includes. They may either refer to mod-defined files (such as
cnc|rules/campaign-palettes.yaml), or to yaml files that are included inside the map package (e.g.
Inline rule overrides may also be included as child nodes, as demonstrated with the
LuaScript world override.
Previous map formats also included the Videos and Options sections. These have been removed and their settings moved to the appropriate traits:
MissionData(Description and videos)
MapOptions(Tech level, difficulties, short game)
Shroud(Fog, Shroud, Explored Map)
MapBuildRadius(Build off Allies' Conyards)
Upgrading the map format
Previous OpenRA releases (up to release-20151224) used to upgrade maps on the first launch. Starting with playtest-20160403, this is no longer the case. To upgrade your map now, you have two options:
- Manually update it using the OpenRA utility, or
- Upload it to the OpenRA Resource Center and use its map upgrade capability.
To upgrade your map using the utility, run the following command:
./OpenRA.Utility.exe MOD --upgrade-map /path/to/your/map <version of OpenRA the map was made for>,
./OpenRA.Utility.exe ra --upgrade-map mods/ra/maps/forest-path.oramap 20151224.
Upgrading the map will also automatically run the upgrade rules.