How OpenRA Map Tilesets Work - guidebee/OpenRA GitHub Wiki
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.
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
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
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
- The
DefaultTerrainLoader
loads the tileset YAML file into aDefaultTerrain
object - It parses all terrain types and templates, creating data structures to map between tile indices and terrain properties
- The
DefaultTileCache
loads all the sprite images and creates the visual representations of tiles
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.
- The
TerrainRenderer
is responsible for drawing the map terrain - 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
- Looks up the
- Height and Ramps: Tiles can have height values and ramp types, creating elevated terrain and slopes
- Variants: Some tiles have multiple visual variants but the same gameplay properties
- Multiple Sheets: Templates can reference multiple image sheets for variants or animations
- Depth Information: Some tilesets have depth information for isometric rendering
When creating a map, you place these templates on the grid. The engine handles:
- Converting between pixel coordinates and tile coordinates
- Determining terrain type for movement and targeting
- Rendering the correct sprites based on tile position and adjacency
- 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.
- 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.
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