OpenRA maps are complex structures that define the game world, including terrain, actors (units and buildings), rules, and gameplay mechanics. They combine binary data for terrain with YAML-based configuration for rules and actors. This document provides a detailed explanation of the OpenRA map format, focusing on terrain, height data, tiles, and rules.

A map in OpenRA consists of several key components:

1. map.yaml - Contains metadata and references to map components
2. map.bin - Binary file storing terrain, resource, and height data
3. rules.yaml - Custom rules specific to the map (optional)
4. Various other optional YAML files for custom definitions

OpenRA currently uses map format version 12, with backward compatibility for version 11. The format version is specified in the map.yaml file:

MapFormat: 12

This version number is checked during map loading to ensure compatibility.

The map.yaml file is the main configuration file for a map and contains several key sections:

MapFormat: 12
RequiresMod: ra
Title: Example Map
Author: Map Creator
Tileset: TEMPERAT
MapSize: 128,128
Bounds: 1,1,126,126
Visibility: MissionSelector
Categories: Mission

Players: # Player definitions
  PlayerReference@Neutral:
    Name: Neutral
    OwnsWorld: true
    NonCombatant: true
  PlayerReference@Creeps:
    Name: Creeps
    NonCombatant: true
  # Additional player definitions...

Actors: # Actor definitions
  Actor1:
    Location: 40,65
    Owner: Neutral
    Type: mpspawn
  # Additional actor definitions...

Rules: # Custom rules
  rules.yaml: # Map-specific rules

The Players section defines all players in the map, including:

• Neutral (for terrain features)
• Creeps (for hostile wildlife)
• Playable factions
• AI opponents

Each player definition includes properties like name, faction, starting resources, and alliances.

The Actors section defines all initial actors (units, buildings, etc.) on the map. Each actor includes:

• Location (cell coordinates)
• Owner (player name)
• Type (references an actor definition from rules)
• Additional custom properties

The terrain in OpenRA is composed of tiles arranged on a grid. Each tile is defined by:

• Type: A unique identifier for the tileset template (ushort)
• Index: Specifies which variant of the tile to use (byte)

These are stored in the TerrainTile structure:

public struct TerrainTile
{
    public ushort Type;
    public byte Index;
}

The tile data is stored in the map.bin file in binary format. The file begins with a header containing format information, followed by sections for tile data, height data, and resource data.

Tilesets define the visual appearance and properties of terrain. Each map specifies its tileset in the map.yaml file:

Tileset: TEMPERAT

Tilesets are defined in the mod rules and include:

• Terrain templates (different tile shapes)
• Terrain types (properties like movement speed, buildability)
• Visual assets (sprites for different tiles)

OpenRA supports two grid types:

1. Rectangular: Traditional square grid (like Command & Conquer)
2. RectangularIsometric: Isometric grid (like Red Alert 2)

The grid type affects coordinate projection and visual appearance, and is defined as a global mod property.

OpenRA supports 3D terrain with variable heights:

• Height values range from 0 to Grid.MaximumTerrainHeight (defined in mod rules)
• Each cell has a height value stored as a byte in map.bin
• The CellHeightStep property defines the world units per height level

Ramps connect different height levels:

• Defined by a byte value in the map.bin file
• The Ramp value references a specific ramp type from the MapGrid.Ramps array
• Different ramp types include flat terrain, gentle slopes, and steep cliffs
• Ramps have properties like orientation and corner heights

The height system requires a projection system to convert between logical map coordinates and visual screen coordinates:

• CPos: Cell Position - logical grid coordinates (x, y, layer)
• MPos: Map Position - 2D coordinates used for the internal map
• PPos: Projected Position - 2D coordinates accounting for height
• WPos: World Position - 3D coordinates in world space (x, y, z)

This projection is handled by methods like ProjectCellInner in the Map class, which calculates how a cell with a certain height should be displayed on screen.

Resources (like ore in Red Alert) are stored in the map.bin file in the resources section. Each cell can contain:

• Resource type (ore, gems, etc.)
• Resource density

This data is stored in the ResourceTile structure:

public struct ResourceTile
{
    public byte Type;
    public byte Density;
}

Maps can define custom rules in a rules.yaml file, which can override or extend the default game rules. These rules are referenced in the map.yaml:

Rules:
    rules.yaml: # Custom rules content here

When a map is loaded, its custom rules are merged with the default game rules:

1. Default rules are loaded from the mod
2. Custom rules from the map are loaded
3. They are merged with map rules taking precedence
4. A new Ruleset object is created with the combined rules

This allows maps to:

• Modify existing units and structures
• Create new units specific to the map
• Change game mechanics
• Define custom palettes and visuals

Here's an example of custom rules from the ant mission:

Player:
    PlayerResources:
        DefaultCash: 1500
World:
    ScriptLobbyDropdown@difficulty:
        ID: difficulty
        Label: dropdown-difficulty.label
        Description: dropdown-difficulty.description
        Values:
            easy: options-difficulty.easy
            normal: options-difficulty.normal
            hard: options-difficulty.hard
        Default: normal
    LuaScript:
        Scripts: campaign.lua, utils.lua, ant-01.lua, ant-attack.lua
    MissionData:
        BackgroundVideo: antintro.vqa
        Briefing: We've lost contact with one of our outposts...

^Palettes:
    IndexedPlayerPalette@scoutant:
        BaseName: scoutant
        BasePalette: player
        RemapIndex: 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95
        PlayerIndex:
            AntMan: 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 123, 123, 123, 123
        AllowModifiers: True

This example shows:

• Starting cash modification
• Difficulty options
• Mission scripts
• Custom color palettes for the ant units

Maps can override specific actors by redefining them in rules.yaml:

E2:
    Buildable:
        Prerequisites: ~tent

MCV:
    Buildable:
        Prerequisites: ~disabled

This example makes the grenadier (E2) buildable from a tent, while disabling construction of MCVs.

Maps can include Lua scripts for custom gameplay:

World:
    LuaScript:
        Scripts: campaign.lua, utils.lua, mission1.lua

These scripts can control:

• Mission objectives
• Reinforcements and triggers
• Custom gameplay mechanics
• Cinematic sequences

Scripts interact with the game through the Lua API, which provides access to actors, terrain, and game state.

Actors are placed on the map through the Actors section in map.yaml:

Actors:
    Actor0:
        Location: 40,65
        Owner: Neutral
        Type: mpspawn
    Actor1:
        Location: 50,50
        Owner: BadGuy
        Type: 4tnk

Each actor has:

• A unique identifier
• Location (grid coordinates)
• Owner (player reference)
• Type (actor type from rules)
• Optional custom properties

When a map is loaded:

1. The Map constructor reads map.yaml
2. The map.bin file is parsed to load terrain, resources, and height data
3. Rules are loaded and merged
4. A Ruleset is created
5. The map is validated for errors
6. Actors are created in the world

This process is handled by the Map class in OpenRA.Game/Map/Map.cs.

Maps undergo validation when loaded:

• Format version is checked
• Terrain tiles are validated against the tileset
• Custom rules are checked for safety
• Actor references are verified

If validation fails, maps might fall back to default rules or show errors.

The map system is implemented across several key classes:

• Map: Main class representing a map (Map.cs)
• TerrainInfo: Defines terrain properties (TerrainInfo.cs)
• MapGrid: Defines the grid system and ramps (MapGrid.cs)
• Ruleset: Combines rules from mod and map (Ruleset.cs)
• ActorInfo: Defines actor properties (ActorInfo.cs)

The height system uses:

• CellLayer<byte> Height: Stores height values per cell
• CellLayer<byte> Ramp: Stores ramp types per cell
• Methods like UpdateRamp and UpdateProjection to maintain consistency

OpenRA's map system is sophisticated and flexible, allowing for diverse gameplay experiences. The combination of binary terrain data with YAML-based rules enables:

• Visually interesting battlefields with varied terrain
• Custom gameplay mechanics for specific maps
• Unique units and structures for special missions
• Rich mission scenarios through Lua scripting

This system powers everything from faithful recreations of classic Command & Conquer missions to entirely new gameplay experiences within the OpenRA engine.