How OpenRA Map Tilesets Work - guidebee/OpenRA GitHub Wiki

How OpenRA Map Tilesets Work

The tileset system in OpenRA is how the game defines and renders the terrain that makes up the game world. Looking at the file mods/ra/tilesets/desert.yaml, it's a definition of the desert tileset used in the Red Alert mod.

Core Components of a Tileset

1. General Information

At the top of the file, you'll find general information about the tileset:

General:
    Name: Desert
    Id: DESERT
    EditorTemplateOrder: Terrain, Debris, Road, Cliffs, Water Cliffs, Beach, River, Bridge
    HeightDebugColors: 880000
  • Name: The human-readable name of the tileset
  • Id: A unique identifier used internally
  • EditorTemplateOrder: Defines the order of categories in the map editor
  • HeightDebugColors: Colors used for debugging terrain height

2. Terrain Types

The Terrain section defines the different types of terrain in the tileset:

TerrainType@Beach:
    Type: Beach
    TargetTypes: Ground
    Color: B09C78

Each terrain type has:

  • Type: Identifier (like "Beach", "Clear", "Water")
  • TargetTypes: Determines what can target/traverse this terrain (Ground, Water, etc.)
  • AcceptsSmudgeType: Some terrain types can have craters or scorch marks
  • Color: Used for the minimap representation
  • RestrictPlayerColor: Prevents player colors from being applied to this terrain

3. Templates

The largest part of the tileset file is the Templates section, which defines all the terrain tiles:

Template@255:
    Id: 255
    Images: clear1.des
    Size: 1,1
    PickAny: True
    Categories: Terrain
    Tiles:
        0: Clear
        1: Clear
        # etc.

Each template has:

  • Id: A unique identifier (usually a number)
  • Images: The sprite sheet(s) used for this template
  • Size: The size in grid cells (1,1 for a single tile, 2,2 for a 2×2 cell template, etc.)
  • PickAny: If true, randomly selects one of the defined tiles during map creation
  • Categories: Grouping for the map editor
  • Tiles: Mapping of frame indices to terrain types

How Tilesets Work Behind the Scenes

Loading and Initialization

  1. The DefaultTerrainLoader loads the tileset YAML file into a DefaultTerrain object
  2. It parses all terrain types and templates, creating data structures to map between tile indices and terrain properties
  3. The DefaultTileCache loads all the sprite images and creates the visual representations of tiles

Terrain Representation

A map tile is represented by a TerrainTile structure containing:

  • Type: References a template ID
  • Index: Specifies which tile within the template to use

For example, a TerrainTile(255, 3) would refer to the 4th tile (index 3) of template 255.

Rendering Process

  1. The TerrainRenderer is responsible for drawing the map terrain
  2. For each cell on the map, it:
    • Looks up the TerrainTile value
    • Gets the appropriate sprite from the DefaultTileCache
    • Renders it at the correct position with the correct palette

Special Features

  1. Height and Ramps: Tiles can have height values and ramp types, creating elevated terrain and slopes
  2. Variants: Some tiles have multiple visual variants but the same gameplay properties
  3. Multiple Sheets: Templates can reference multiple image sheets for variants or animations
  4. Depth Information: Some tilesets have depth information for isometric rendering

Practical Usage

When creating a map, you place these templates on the grid. The engine handles:

  1. Converting between pixel coordinates and tile coordinates
  2. Determining terrain type for movement and targeting
  3. Rendering the correct sprites based on tile position and adjacency
  4. Minimap visualization using the defined colors

The tileset system allows for diverse terrain with different gameplay properties while maintaining a consistent visual style and structured data organization.

Technical Implementation Details

  • Tiles are stored in a CellLayer<TerrainTile> grid
  • The renderer uses a TerrainSpriteLayer for efficient drawing
  • Custom terrain can be applied on top of the base tileset (e.g., for buildable terrain)
  • The system supports different grid types (rectangular or isometric)

This modular approach allows OpenRA to support the varied tilesets from the original Command & Conquer games while providing a flexible framework for custom content.

Example from desert.yaml

Here's a snippet from the desert tileset definition showing various terrain types and templates:

General:
	Name: Desert
	Id: DESERT
	EditorTemplateOrder: Terrain, Debris, Road, Cliffs, Water Cliffs, Beach, River, Bridge
	HeightDebugColors: 880000

Terrain:
	TerrainType@Clear:
		Type: Clear
		AcceptsSmudgeType: Crater, Scorch
		Color: 976F4070
	TerrainType@Water:
		Type: Water
		Color: 5078A0
		TargetTypes: Water
	TerrainType@Rock:
		Type: Rock
		TargetTypes: Ground
		Color: 5F4C36
		RestrictPlayerColor: true
	TerrainType@Road:
		Type: Road
		AcceptsSmudgeType: Crater, Scorch
		Color: 7C7470
		TargetTypes: Ground

Templates show how specific terrain tiles are defined with their visual representation and gameplay properties:

Templates:
	Template@255:
		Id: 255
		Images: clear1.des
		Size: 1,1
		PickAny: True
		Categories: Terrain
		Tiles:
			0: Clear
			1: Clear
			2: Clear
			3: Clear
⚠️ **GitHub.com Fallback** ⚠️