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 123gives a number a name. The first definition of a name wins, so an override has to come before any later definition.#define NAMEturns on a flag that the script can test later withif 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.