How AoE2 random map scripts work

An .rms file is a plain text recipe. When a game starts, the engine reads the recipe and builds a new map from it. This guide explains how a modern Definitive Edition script is organised, based on reading the official scripts that ship with the game.

The big picture

A script has two parts: a header that sets up names and options, and up to seven sections, each marked with a tag in angle brackets:

<PLAYER_SETUP>
<LAND_GENERATION>
<ELEVATION_GENERATION>
<CLIFF_GENERATION>
<TERRAIN_GENERATION>
<CONNECTION_GENERATION>
<OBJECTS_GENERATION>

Scripts do not always store these sections in the same order. Fortress, for example, puts elevation and cliffs after objects.

The header: names and options

Two commands do most of the work in the header:

  • #const NAME 123 gives a number a name. The first definition of a name wins, so an override has to come before any later definition.
  • #define NAME turns on a flag that the script can test later with if NAME.

This is how one script can produce many looks. A modern map defines names like BASE_TERRAIN and BASE_FOREST, and each biome gives them different terrain numbers. The rest of the script only uses the names, so it does not need to know which biome was rolled.

Randomness

A start_random block chooses one option by percentage:

start_random
  percent_chance 50 #define POND_GENERATION
end_random

That example is how Black Forest decides whether to add ponds, so there is a 50% chance each game. One limit matters here: you cannot nest one start_random inside another. To make a second choice depend on the first, use if blocks around separate random blocks. Arabia does exactly this for its forests.

What each section does

PLAYER_SETUP

Decides how players are placed. Most maps use random_placement. Maps with locked positions use direct_placement.

LAND_GENERATION

Sets the base terrain of the whole map, then creates large areas with create_land and player homes with create_player_lands. Reserving a home here is the reason that a Town Center normally does not appear inside a forest.

ELEVATION and CLIFF

Raise hills with create_elevation and add cliff lines.

TERRAIN_GENERATION

Paints forests, patches and details with create_terrain. The setting set_avoid_player_start_areas keeps forest away from starts.

CONNECTION_GENERATION

Cuts paths between lands, such as shallows across water or roads through a forest.

OBJECTS_GENERATION

Places Town Centers, villagers, resources, animals and relics, usually with create_object blocks.

Include files do the heavy lifting

A modern script is often more of a conductor than an orchestra. It sets flags, then pulls in shared logic from the game:

#define GOLD_PRIMARY
#define STONE_PRIMARY
#include_drs includes/starting_resources.inc

Files such as town_centres.inc, villagers.inc, scouts.inc, starting_resources.inc, huntable.inc and relics.inc hold the real placement rules. The standard scout, for example, comes from scouts.inc and not from the map's own script.

The default sizes in starting_resources.inc show how a "normal" start is defined: 6 forage bushes, a primary gold mine of 7 tiles with secondary and tertiary mines of 4, and a primary stone mine of 5 with a secondary of 4.

Map coordinates

Positions are percentages of the map, not tile numbers. So 0 0 is the west (left) corner, 99 0 is the north (top) corner, 0 99 is the south corner and 99 99 is the east corner. In Definitive Edition, a position can be a decimal number, so every tile can be addressed. The Map Painter depends on this.

Where to go next

Read the common mistakes guide before you write your own blocks. To see real scripts without writing one, generate a map in the Map Scripter and read the preview. For a full command reference, the community's Definitive RMS Guide on the official Age of Empires forums is the best resource.