Map Format

Map format

This document describes the map format 11 that was first released with playtest-20160403.

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.yaml defines the map metadata, player information, actors, and rule overrides.
• map.bin defines the map tiles, height information (for mods that use terrain height), and harvestable resource data.
• map.png contains the map preview that is used by the game UI and external tools.
• (optional) Additional yaml files that may be referenced from map.yaml containing custom rules, sequences, etc.
• (optional) lua files that may be referenced from map.yaml or external rule files, containing map scripts.
• (optional) Custom artwork and sounds that may be referenced from map.yaml or external rule files.

map.yaml

map.yaml consists of a number of yaml sections, described below.

MapFormat

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.

RequiresMod

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.

Title

The map title that is shown in the game UI.

Author

The map author who is shown in the game UI.

Tileset

The tile set that the map uses. Must match one of the tile sets that are referenced via mod.yaml.

MapSize

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.

Bounds

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.

Visibility

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.

Categories

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.

LockPreview

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 True. Enable this option if you choose to include a custom map preview.

Players

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

Actors

A list of ActorReference nodes, each defining an actor on the map.

An 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:

Name	Description
Owner	Required: defines the PlayerReference name of the actor's owner. Map actors (e.g. trees and rocks) should be owned by the "Neutral" player.
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 Mobile trait)
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 Mobile trait that define SharesCell: true
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. rules.yaml).

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)
• CrateSpawner (Crates)
• MapBuildRadius (Build off Allies' Conyards)
• PlayerResources (Starting cash)
• SpawnMPUnits (Starting units)
• MapCreeps (Viceroids, Worms)
• DeveloperMode (Cheats)

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:

1. Manually update it using the OpenRA utility, or
2. 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>,

e.g.

./OpenRA.Utility.exe ra --upgrade-map mods/ra/maps/forest-path.oramap 20151224.

Upgrading the map will also automatically run the upgrade rules.