Random Map Scripting Links and FAQ

You recently downloaded an RMS and don’t know what to do with it? You want to design your own RMS and don’t know where to start? You’re working on an RMS and you have some questions that you want to ask? You are wondering what 'RMS' even stands for?

You have come to the right place!

>First you will find the answers to general questions related to using RM scripts in your game.
>Below that are frequently asked questions about RM scripting.
>At the end of this post you will find links to relevant guides, tutorials, forum posts and tools.

Feel free to ask any questions you might have in this thread or by starting up a new thread in the AI & RM Scripting Forum!


***General Questions***

Q: What does RMS stand for?
RMS stands for Random Map Script.

Q: What is a random map script?
A random map script is a text file (with the extension *.rms) containing a set of instructions which are used to randomly generate a map. When you play Black Forest or Arabia, the game uses that random map script to generate a map for you to play on and it almost never looks exactly the same.
This should not be confused with scenarios which are designed in the in-game scenario editor and will usually look exactly the same every time you play them.
It is possible to create your own custom random map scripts and to play on ones created by other people.

Q: Where can I download RM scripts?
The Blacksmith here at AoKH has a large collection of RM scripts. You can also check out the Steam Workshop if you have the HD Edition. More recently, a site called AoE2Map was created, which has a lot of new maps. A few maps are also at AoEZone.

Q: I’ve downloaded an RMS; where should I put it?
If you are playing the CD version of the game:
Microsoft Games\Age of Empires II\Random

If you are playing the HD Edition on Steam:
Steam\SteamApps\common\Age2HD\resources\_common\random-map-scripts

If you are locally playing a mod for the UserPatch; for example WololoKingdoms:
Microsoft Games\Age of Empires II\Games\WololoKingdoms\Script.Rm

AoC + Voobly + Wololo Kingdoms:
Microsoft Games\Age of Empires II\Voobly Mods\AOC\Data Mods\WololoKingdoms\Script.Rm

HD + Voobly (using the Compatibility Patch):
Steam\steamapps\common\Age2HD\Random

HD + Voobly + Wololo Kingdoms:
Steam\steamapps\common\Age2HD\Voobly Mods\AOC\Data Mods\WololoKingdoms\Script.Rm

Q: How do I choose a custom RMS in-game?
In the lobby, choose Random Map from the Game dropdown menu. Then choose Custom from the Map Style dropdown menu. Then choose the RMS you want from the Location dropdown menu. RM scripts are automatically transferred to other players in multiplayer, unless they already have map with exactly the same name (in which case that needs to be removed/deleted first).

Q: How do I open/edit an RMS file?
All you need is a text editor. Notepad will do just fine if all you want to do is look at the script or make simple edits. If you plan on spending a significant amount of time working with RM scripts, then a more advanced text editor and/or syntax highlighting will help you out. You can read about those in the Links & Resources section of this post.


***Scripting Questions***
These are the types of questions that you might have if you are writing or editing RM scripts.

Q: How do I make my own RMS?
Take a look at the guides and tutorials in the Links & Resources section.

Q: Why is my map completely blank?
Perhaps you have an incomplete comment somewhere at the top of your script. Something like this for example: /* MY AWESOME MAP*/
The space is missing between MAP and */ so the whole rest of the script is ignored.
You might also have some sort of random statement that is missing end_random or a conditional statement missing endif.
It could also be that you are missing the closing brackets } somewhere.

Q: Where can I get the RM scripts for the standard maps in the game?
If you are playing the CD version of the game:
Go to Microsoft Games\Age of Empires II\Data and open up gamedata.drs (AoK) and gamedata_x1.drs (AoC) using a text editor like notepad. You can now copy out any scripts you want to use.

If you are playing the HD Edition on Steam:
Go to Steam\SteamApps\common\Age2HD\resources\_common\drs and choose the gamedata_x1 (AoC) or gamedata_x2 (DLC) folders. You will find all the map scripts in those folders as *.rms files.

Q: What does #include_drs do?
#include statements are used by the internal maps in the gamedata and don't need to be in your custom maps.
If you want, you can refer to existing *.inc files to have them included in your script. Only do this with the default *inc files, because custom files will not be transferred with your script in multiplayer.

Q: Can I use triggers in an RMS?
No. Triggers are used in scenarios, which are created in the in-game scenario editor. RM scripts are created externally using a text editor and cannot contain triggers.

Q: How can I test my script in the scenario editor?
If you are using the HD Edition on Steam or the Userpatch for the CD version, then all you need to do is choose your map from Random Map location in the scenario editor. You can then hit generate a whole bunch of times to test your map. You can also choose a specific map seed and then test the effect of changing small parts of your script. There is no need to close the game while testing – all you need to do is save changes to your script in the text editor you are using.

If you do not use the HD Edition or the UP, it is still possible to test in the scenario editor, but it requires modifying the gamedata_x1.drs file by replacing one of the standard map scripts with your own custom one. MAKE SURE YOU BACK UP YOUR GAMEDATA FILE BEFORE DOING THIS. This utility can be used to help you with this.

Q: How do I use mossy roads/ snowy roads/ farm terrains etc.?
You first need to define them using their terrain constants, like this for example:

#const ROAD_MOSS 39
#const ROAD_SNOW 38

Then you can use them like any other terrain. Lists of these terrain constants are found in the Updated New RMS Guide and also in the RMS constants section below.

Q: Why are certain objects not appearing?
This can be due to a multitude of reasons such as typos, incomplete comments, too narrow constraints on the min and max distances, or specifying a base terrain that isn’t in your map. If objects towards the end of your script are not appearing, it could be due to the excessive use of min_distance_group_placement. It keeps away objects created by the same create_object command, and by all future create_object commands! Consider using temp_min_distance_group_placement if you need to scatter objects very far apart. temp_min_distance_group_placement only applies to the current create_object command.

Q: What does temp_min_distance_group_placement do?
It is like min_distance_group_placement, but only keeps objects away from other objects created in the same create_object command and not future ones. In the standard maps it is almost only used for relics, but you can use it for other objects too. It can be used alongside min_distance_group_placement.

Q: How do I make a large central lake like in the Baltic map?
You could add this to your <LAND_GENERATION> section, for example:

 create_land
{
  terrain_type WATER
  land_percent 25
  left_border 20
  right_border 20
  top_border 20
  bottom_border 20
  land_position 50 50  
}

Q: How do I make rivers?
A basic way to make rivers is like this:

base_terrain WATER
create_player_lands
{
  terrain_type GRASS
  land_percent 100
  other_zone_avoidance_distance 8
}

Q: How can I make the players start closer to the edge/closer to the center?
Closer to the center is easy: just add border attributes to your create_player_lands

Closer to the edge is much harder. Decreasing the base_size allows player lands to be closer to the edges, but it does not guarantee that it will happen.

Q: Why is my map crashing?
This can be due to any number of reasons. Here are a few examples:
-Using #const to define something which doesn’t exist and then attempting to place it.
-Attempting to use DLC objects in AoC.
-Giving the map a name that is longer than 20 characters (this bug is fixed in the HD Edition and the UserPatch).
-Using 100 as the second number for land_position.
-Using 99 as a zone number for lands
-Having a large amount of jungle terrain in small clumps on your map.
-Having a very large number of connections.
-Using more than 99 distinct create_object commands.
-Using a top_border that is bigger than the other borders for player lands.

As you can see, crashes can happen for all kinds of reasons – including ones not listed above. If you are experiencing crashes, comment out your entire map and then gradually uncomment the script part by part to localize the source of the crash. If you have many comments in your script, it may be simpler to start with a new blank script and copy and paste in your script part by part to localize the source of the crash. If you can’t work out why your script is crashing feel free to make a thread here and ask someone to look over it for you.

Q: Why is weird stuff happening with my if branches?
There is a bug where comments are NOT ignored, if they are within logical branches of conditionals (if, elseif, else) and random code (percent_chance) that aren't chosen. Currently, this has been fixed only for if in the UserPatch 1.5 while all other versions of the game suffer from this bug, and UP 1.5 still has the same problem with percent_chance. So be very careful about comments in these locations.
This especially problematic when creating map packs!

Q: How can I easily locate typos and syntax errors in my script?
Syntax highlighting will help you spot mistakes easily. Check out the Syntax Highlighting section below for some options.

Q: What should I check before publishing my map?
There is a nice checklist here: Long version Short version

Q: How do I take full-map screenshots?
CTRL+F12
But … it doesn’t work in the HD Edition on Steam.

Q: What order is my script generated in?
The sections are used in this order:

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

You will notice that many scripts (including the standard game scripts!) do not have them written in this order. It does not matter in which order they are written, but this is the order in which the game will use your script so it makes sense to write it like this.

Q: Why is terrain avoiding cliffs?
Keep in mind that cliffs are generated before terrain (see previous question), and come with their own terrain underneath them (see next question), therefore spacing_to_other_terrain_types will also include the spacing to the cliff terrain! Read more about this in All About Cliffs.

Q: How do I get rid of the bits of grass that generate next to cliffs?
Cliffs are placed on a special terrain. This terrain is #16 and looks exactly like GRASS. It does not have a predefined name, so you need to define it to use it or replace it.
Example:

#const GRASS_CLIFFS 16
create_terrain ICE
{
  base_terrain GRASS_CLIFFS
  land_percent 100
  number_of_clumps 99999
  spacing_to_other_terrain_types 0
}

This will replace all (or most) of your cliff grass with ice. You may want to do this on a wintry map, for example. On a desert map you may want to replace it with DESERT or DIRT if it looks out of place to have bits of grass there.

Q: How do I store numeric variables?
You cannot. This will NOT work:

#const NUM 10
number_of_objects NUM

Q: How can I check if someone is running the DLC Expansions in the HD Edition?
You can check for any of the predefined constants from Rise of the Rajas. Constants from African Kingdoms and the Forgotten are always true, because they are listed in random_map.def for both sets of gamedata, but RoR constants are only in the expansion gamedata.

if DLC_MANGROVEFOREST #define DLC_AVAILABLE endif

DLC_AVAILABLE will now be true if a match is launched using the expansions dataset.

Q: Why is my map suddenly covered in mangrove shallows/ snowy roads/baobab forest?
You are running the Wololo Kingdoms mod for the UserPatch. This replaces some of the existing terrains.
Terrain 11 (formerly dirt2) is now mangrove shallows, but you can use terrain 27 (foundation dirt) to get the same look.
Terrain 38 (formerly snow road) is now cracked dirt, but terrain 33 is now snow road, so you can use that.
Terrain 33 (formerly snow dirt) is now snow road but you can use terrain 36 (foundation snow) to get the same look.
Terrain 20 (formerly oak forest) is now mangrove forest, but you can use terrain 10 (forest) to get the same look.
Terrain 16 (formerly cliff grass) is now baobab forest, but you can use terrain 0 (grass) for the same look, or pick a new look for the cliff terrain.
Terrain 41 (formerly buggy and unused) is now acacia forest.
Example for how to deal with this:

if UP_EXTENSION if DLC_MANGROVEFOREST #define WOLOLOKINGDOMS endif endif /* check the game version */
if WOLOLOKINGDOMS
#const road_type 33
#const dirt_type 36
else
#const road_type 38
#const dirt_type 33
endif

This will make it so that road_type is always snowy road, and dirt_type is always dirt snow.
You only need to worry about this with terrains that require #const or for situations in which you use #const (seasonal or regional variations). The predefined names have been automatically switched, so you can use those without worry. Also note that the constant IDs for many of the objects are altered as well, so use predefined names whenever possible if you are working with WololoKingdoms. You can find the new constant IDs manually by opening up the WK gamedata_x1.drs with a text editor. It is all listed right at the top.

UserPatch 1.5 Questions

Q: How can I check if the game is using UP 1.5?
If UserPatch 1.5 is the game version, then UP_EXTENSION will be defined, so you just do if UP_EXTENSION

Q: How can I directly place players in specific positions?
You can specify direct_placement instead of random_placement and then use land_position.
Example:

#const AT_PLAYER 0
#const AT_COLOR 1
#const AT_TEAM 2
<PLAYER_SETUP>
direct_placement
<LAND_GENERATION>
create_land
{
number_of_tiles 1000
terrain_type GRASS
assign_to AT_TEAM 2 0 0
land_position 50 80
}

This will assign this specific land to a random member of the second team. Note that you must have a separate create_land for every player that this map should support.

Q: How do I make a Regicide King of the Hill map?
You can add a guard_state to the King. Here is an example for how to set this up:

#const AMOUNT_GOLD 3
#const ATTR_SET 0
#const GAIA_SET_PLAYER_DATA -10    
#const DATA_MODE_FLAGS 1
guard_state KING AMOUNT_GOLD 0 1 /* don't lose your king */
effect_amount GAIA_SET_PLAYER_DATA DATA_MODE_FLAGS ATTR_SET 3 /* spies + treason with regicide */

Make sure to place a king, and the map will now trigger defeat if you lose your king, even if you are in some other game mode, such as KoTH.

Q: How do I make Zipped RMS (ZR@mapname)?
Follow these instructions

Q: Can I spawn unique units based on a player's civilization?
Yes! Use the UNIQUE_UNIT and ELITE_UNIQUE_UNIT definitions

#const ELITE_UNIQUE_UNIT -2
#const UNIQUE_UNIT -1
create_object UNIQUE_UNIT {
  set_place_for_every_player
}

Definitive Edition Questions

Q: What new RMS features does Age of Empires 2: Definitive Edition include?
There is currently no official dolcumentation (yet). However, I have a community made document that covers what we have figured out so far. This is very much a work-in-progress.


***Links & Resources***
If you find additional resources, please let me know!


Full Guides

Updated New Random Map Scripting Guide by: Zetnus
An updated Guide that fixes errors and omissions in earlier guides and provides information about the new scripting commands available in the UserPatch and the HD Edition DLC expansions. Currently does not cover UserPatch 1.5 features yet.

A guide for creating maps by: HenkDeSuperNerd
A work-progress that currently covers the basics and also stuff including ZRmaps and direct_placement, but is still unfinished.

YouTube Tutorials by: Mike Hasselbach (TheMadCADer)
Well-made videos that provide lots of useful information. Also take a look at his Terrain Reference Sheet.


Tutorials

Land generation in Age of Empires II by: HenkDeSuperNerd
An unfinished, but very in-depth, look at how lands are actually generated.

creating new forest-types using User-Patch by: HenkDeSuperNerd
Use UP 1.5 to upgrade trees and ultimately change the appearance and functionality of forests.

Checking Your Map by: RF_Gandalf
A guide to all the things you should check before publishing your map. Originally posted on the now defunct MrFixItOnline. Possibly worth a read if you are new to RM scripting.
Available as a full guide and as a concise checklist.

RMS Step by Step Tutorial by: Vauxhall (Bryan Tighe)
A walkthrough for creating a simple map. Also includes reference info from the RMSG (but also carries over inaccuracies from the RMSG). Was published on various now defunct sites but is still hosted here as well as on various internet archives like this one.

How Connection Generation Really Works by: Bryan
Some connection theory for you. This was originally part of Bryan's RMS Tutorial, but isn't included in the versions linked.

RMS Mountain Making Tips By: Lengo67
A tutorial about trying to make nice mountains with elevation generation.

All about Cliffs by: Zetnus
A tutorial that guides you through learning everything there is to know about cliffs.

Custom Beaches by: Zetnus
Learn how to get non-standard beaches in your map. Mainly useful in the Definitive Edition.

Unequal Player Starts
Unequal Player Starts - part 2 by: Zetnus
Tutorials about creating unequal starting situations using the assign_to_player attribute.

Random Map Advanced Skills by: yesgqt
A tutorial in Chinese covering various advanced RMS techniques, such as moats, cliff placement, fancy forests, wall tricks, unequal starts, water elevation, etc.


Syntax Highlighting and Text Editors
Yes, you can write your script in just about any text editor, but if you pick some of these choices, you can use community-created features like syntax highlighting – which is very helpful for finding typos.


For Notepad++
Notepad++ is free and can be downloaded here: https://notepad-plus-plus.org/

Zetnus's RMS syntax for Notepad++
Shameless self-promotion, but this is one includes the pre-defined DLC constants and the UP 1.5 commands, something which the other Notepad++ options don't currently include.

RMS syntax support for Notepad++ (UDL) by: Axa
An addon with syntax highlighting for free text editor Notepad++. Very comprehensive. Also available here.

RMS Language For NotePad++ by: ephestion
Another addon with rms syntax highlighting for the free text editor Notepad++. Not as advanced as the one above.


For PSPad
PSPad is available online for free and can be downloaded here: http://www.pspad.com/en/
RMS Toolkit by: chasqui
Quite a comprehensive package. Comes with syntax highlighting, auto-generation of code, context-sensitive help and various other useful features.

For Visual Studio
RMS support for Visual Studio Code by: deltaidea (Nikita Litvin)

For Sublime Text
Age of Empires 2 Random Map Scripting support for Sublime Text by: deltaidea (Nikita Litvin)

For IntelliJ
RMS plugin by: hszemi

For Atom
Language Aoe2 RMS by: twestura

For Vim
vim-aoe2-rms by: Renée Kooi

For Word
Microsoft Word is not free, but many people will have purchased it as standard office software.
RMS Creator by: chasqui
Macros auto-generate a script in Word, and offers quite a bit of scope for customizing the auto-generation. Great for beginners or casual scripters.

Standalone Editors
Might be of interest to some.

Mat's Random Map Scripting Editor by: Mat (Xtreme_Lizard)
Reasonably well-equipped features to auto-generate statements and check syntax.

RMS Scribe by: ephestion
Comes with some templates and auto-generation capabilities.


RMS Constants
These are lists of all the objects in the game that can be created if you define them using a #const statement.

Complete List (.csv) by: DiGiT
Easily searchable, because it’s all in a single spreadsheet.

Advanced List (.htm) by: OtmShankIiI
Much better descriptions and slightly more up-to-date than the complete list above. (This one is also "complete")

The DLC Constants (.xls) by: Zetnus
Lists the new constants from the expansions "The Forgotten" and "African Kingdoms" and "Rise of the Rajas" on Steam.

Terrain Names Spreadsheet (.xls) by: Zetnus
All the terrain constants with descriptions of the terrains and their functions. Might be useful if you are confused by the renaming of the terrains in the HD Edition scenario editor.


Reference Lists and Misc. Utilities

UserPatch Script Reference and RMS #Const Updates
The official documentation of the new UP scripting commands.
Also see Microsoft Games\Age of Empires II\Reference\Scripting for examples and take a look at UserPatchConst.rms

AgeII HD Script Reference
The official documentation of the new HD Edition scripting commands. Has some typos.

WololoKindoms Terrain Conversions
Find out what you need to change to make your map WK-compatible.

UP 1.5 Effects & How to use them in Maps by: BF_Tanks
Detailed look at many of the UP 1.5 features and how to use them

AoE2Map Snippets
A collection of bits of code using the UP 1.5 features to do cool stuff.

Random Map Scripting Q & A by: Dr. Greg Street (ES_Deathshrimp), Conquerors Lead Designer
Part I
Part II

More undocumented RM scripting commands by: Zetnus
A thread about all the commands that I found which had not been previously documented anywhere. I added those which work to the Updated New RMS Guide. However, there are others which I have not been able to properly discover the function of. If you find out how to use these, please say so!


Communities

Random Map AoE2 Discord
The place where a lot of discussion happens these days. You'll get a faster answer there than here, but it will be harder to find for people in the future.


Legacy Links
This post was getting too long, and a lot of the resources are outdated and not really of interest these days, so I have begun relegating some of the links to this section, where they aren't lost completely, but at the same time stay out of the way of things you actually should click on.


Random Map Scripting Guide (RMSG.doc) by: Ensemble Studios
The original guide to random map scripting, written by Ensemble Studios. Provided in the docs folder on your CD or in Age2HD\Docs\All if you have the HD Edition on Steam. Has many errors and omissions; so don’t trust everything written there! Contains an annotated version of the script for Coastal, which may be of interest.
New Random Map Scripting Guide by: Bultro
A completely new and more concise guide that covers many of the things left out by the original RMSG. Has been significantly updated by Zetnus to produce the Updated New RMS Guide.
Wrath's RMS tutorial 01 by: the_Wrath
A rather simple tutorial that is about land generation. Future parts of this tutorial were never published/produced.
An Introduction to Random Map Scripting by: Zetnus
This is a tutorial about the process of random map scripting, and suggested tools and resources to use, rather than talking about the actual scripting itself. Has some info about using the Steam Workshop. It's the precursor to this post that you are reading right now and I will not be keeping it up to date in the future.
Getting Started with RMS by: MrEd
An archived article with general tips for the RMS design process that contains suggestions and pitfalls to avoid. Dated, but could still worth reading.
RMS Editor 2 by: Bryan (Vauxhall)
A text editor that comes with basic script generation capabilities.
RMS Generator by: [soz]Exekutor
If you can read German, then you can read [soz]Exekutor's Tutorial zum RMSG for an introduction to this program.
RMS Editor by: PhoenixFlame
Another early rms editor. You also need the patch.
(outdated) Older constant lists (.doc and .gif for pictures) by: Raymond Tukkers
here and here.
RMS Reference by: Doskei
Two documents of commands and constants taken directly from the RMSG and intended to be printed out for reference.
Liste aller Objekte by: Reyk
German translation for the list of all pre-defined constants.
Setup Map by: scripter64
This is a utility that lets you generate your script in the Scenario Editor (by replacing one or two of the maps in the gamedata). If you are using the HD Edition or the UP, you should NOT use this because both of those already let you generate custom maps in the scenario editor. Also, this will prevent you from playing multiplayer while it active.

Concluding Thoughts

Hopefully this post was able to point you in the right direction; if not, feel free to ask here or make a new thread in this forum.

When searching past threads, keep in mind that the AI & RM Scripting forum was only created in 2008. Older threads about RM scripting can be found by searching the Scenario Design forum. Also, annoyingly, when you search for "RMS" you get lots of results about farms. So here is a tip: search for rms with a space before the rms.

Thread History:
This thread was started in 2015 by Zetnus. When I become inactive, a moderator will hopefully take over updating it as needed.

[This message has been edited by Zetnus (edited 01-12-2020 @ 12:32 PM).]