What is Automapping?

Automapping is an advanced tool to automatically search certain combinations of tiles across layers in a map and to replace these parts with another combination. This allows the user to draw structures quickly and Automapping will generate a complex scenario from them, which would have taken much more time if manually crafted.

The goal of Automapping is that you only need to draw within one layer and everything else is setup for you. This brings some advantages:

  • Working speed - you need less time to setup a map.

  • Less errors - the main reason is to reduce the error rate. If you have setup the rules properly, there are no hidden errors.

Setting it Up

The Automapping feature looks for a text file called ‘rules.txt’ in the folder where the current map is located. Each line in this text file is either

  • a path to a rulefile

  • or a path to another textfile which has the same syntax (i.e. in another directory)

  • or is a comment which is indicated by # or //

A rulefile is a standard map file, which can be read and written by tiled (*.tmx). In one rulefile there can be multiple defined rules.

An Automapping rulefile consists of 4 major parts:

  1. The definition of regions describes which locations of the rulemap are actually used to create Automapping rules.

  2. The definition of inputs describes which kind of pattern the working map will be searched for.

  3. The definition of outputs describes how the working map is changed when an input pattern is found.

  4. The map properties are used to fine-tune the input pattern localization and the output of all rules within this rules file.

Defining the Regions

Up to three special layers can be used to define the input and output region of each rule:

  • A layer called regions defines the shared input and output region for each rule. Using this layer can save some work when the input and output regions are entirely or mostly the same.

  • A layer called regions_input defines just the input region for each rule.

  • A layer called regions_output defines just the output region for each rule.

Since both input and output regions need to be defined, there must be both a regions_input and a regions_output layer if there is no regions layer.

It does not matter which tiles are used to define the regions. So either use any tile or no tile at a coordinate to indicate if that coordinate belongs to a rule or if it doesn’t. Any tiles placed on input or output layers outside of the respective region are ignored.

If multiple rules are defined in one rulemap file, the regions must not be adjacent. That means there must be at least one tile of unused space in between two rules. If the regions are adjacent (coherent) then both regions are interpreted as one rule.


If the output tiles are not adjacent to the matching input tiles, the output region can be used to connect the two parts of the rule, since empty output tiles are ignored by default.

Multiple Rules in One Rulefile

Multiple rules are possible in one rulemap. However, if you want to have the rules applied in a certain sequence, you should use multiple rulefiles and define the sequence within the rules.txt file. As of now there also is a certain sequence within one rulemapfile. Generally speaking the regions with small y value come first. If there are regions at the same y value, then the x value is taken into account. On orthogonal maps this ordering scheme is the same as for reading in most western countries (Left to right, top to bottom). The order within one rulemap may be changed later, once tiled is capable of utilizing multiple threads/processors. So if you want to rely on a certain sequence, use different rulemaps and order these in the rules.txt

Definition of Inputs

Inputs are generally defined by tile layers which name follows this scheme:


where the [not] and [index] are optional. After the first underscore there will be the name of the input layer. The input layer name can of course include more underscores.

The name determines which layer on the working map is examined. So for example the layer input_Ground will check the layer called Ground in the working map for this rule. input_test_case will check the layer test_case in the working map for this rule.

Multiple layers having the same name and index is explicitly allowed and is intended. Having multiple layers of the same name and index , will allow you to define different possible tiles per coordinate as input.

The index is used to create complete different input conditions. All layers having the same index are taken into account for forming one condition. Each of these conditions are checked individually.

  1. index must not contain an underscore.

  2. index must not start with not.

  3. index may be empty.

If there are tiles in the standard input layers one of these tiles must be there to match the rule. The optional [not] inverts the meaning of that layer. So if there are inputnot layers, the tiles placed on them, must not occur in the working map at the examined region to make a rule match. Within one rule you can combine the usage of both input and inputnot layers to make rules input conditions as accurate as you need or as fuzzy as you need.


Empty tiles within input or inputnot layers are normally ignored. However, when there are no inputnot layers and all of the input layers contain an empty tile at a given location, it has a special meaning. In this case, it only matches on any tiles that are not empty, and that also are not one of the other input tiles used in the same rule. This can be useful, because normally to achieve this logic you could need a lot of inputnot layers. It is used in the Basic Shoreline example.

If this special case is not the desired behavior, there are a few possible workarounds:

  • Adding an empty inputnot layer. This disables the special behavior, causing empty tiles to be ignored.

  • Defining the regions_input and regions_ouput separately, reducing your input region such that it does not contain empty tiles.

  • Setting the StrictEmpty boolean property on the input layer to true. This causes the empty tiles to only match against empty tiles.

Definition of Outputs

Outputs are generally defined by layers whichs name follows this scheme:


which is very similar to the input section. At first there must be the word output. Then optionally an [index] may occur. After the first underscore there will be the name of the target layer. The target layer name can of course include more underscores.

All layers of the same index are treated as one possible output. So the intention of indexes in the outputs of rules is only used for random output.

The indexes in the output section have nothing to do with the indexes in the input section, they are independent. In the output section they are used for randomness. In the input section they are used to define multiple possible layers as input. So when there are multiple indexes within one rule, the output will be chosen fairly (uniformly distributed) across all indexes. So a dice will be rolled and one index is picked. All of the output layers carrying this index will be put out into the working map then.

Note that the output is not being checked for overlapping on itself. This can be achieved by setting the map property NoOverlappingRules to true.

Map Properties

The following map properties can be used to customize the behavior of the rules in a rulefile:


This map property is a boolean property: it can be true or false. If rules of this rulefile get applied at some location in your map, this map property determines if all other tiles are deleted before applying the rules. Consider a map where you have multiple layers. Not all layers are filled at all places. In that case all tiles of all layers should be cleared, so afterwards there are only the tiles which are defined by the rules. Since when not all tiles are cleared before, you will have still tiles from before at these places, which are not covered by any tile.


This map property is a number: 1, 2, 3 … It determines how many tiles around your changes will be checked as well for redoing the Automapping at live Automapping.

Since Tiled 1.2

This map property determines whether rules can match even when their input region falls partially outside of a map. By default it is false for bounded maps and true for infinite maps. In some cases it can be useful to enable this also for bounded maps. Tiles outside of the map boundaries are simply considered empty unless one of either OverflowBorder or WrapBorder are also true.

Tiled 1.0 and 1.1 behaved as if this property was true, whereas older versions of Tiled have behaved as if this property was false.

Since Tiled 1.3

This map property customizes the behavior intended by the MatchOutsideMap property. When this property is true, tiles outside of the map boundaries are considered as if they were copies of the nearest inbound tiles, effectively “overflowing” the map’s borders to the outside region.

When this property is true, it implies MatchOutsideMap. Note that this property has no effect on infinite maps (since there is no notion of border).

Since Tiled 1.3

This map property customizes the behavior intended by the MatchOutsideMap property. When this property is true, the map effectively “wraps” around itself, making tiles on one border of the map influence the regions on the other border and vice versa.

When this property is true, it implies MatchOutsideMap. Note that this property has no effect on infinite maps (since there is no notion of border).

If both WrapBorder and OverflowBorder are true, WrapBorder takes precedence over OverflowBorder.


This map property is a boolean property: A rule is not allowed to overlap on itself.

These properties are map wide, meaning it applies to all rules which are part of the rulemap. If you need rules with different properties you can use multiple rulemaps.

Layer Properties

The following properties are supported on a per-layer basis:


This layer property is a boolean property. It can be added to input and inputnot layers to customize the behavior for empty tiles within the input region.

In “StrictEmpty” mode, empty tiles in the input region match empty tiles in the set layer. So when an “input” layer contains an empty tile within the input region, this means an empty tile is allowed at that location. And when an “inputnot” layer contains an empty tile within the input region, it means an empty tile is not allowed at that location.


Abstract Input Layer Examples

Having Multiple Input Layers with the Same Name

Assume the following 3 tile layers as input, which possible inputs are there in the working map?

Tile layer


tiles 1 and 2


tiles 3 and 4


tiles 5 and 6


The following parts would be detected as matches for this rule:

tiles 1 and 2 tiles 3 and 2 tiles 5 and 2
tiles 1 and 4 tiles 3 and 4 tiles 5 and 4
tiles 1 and 6 tiles 3 and 6 tiles 5 and 6

Input Layers Using Different Indexes

Given the following 3 input tile layers:

Tile layer


tiles 1 and 2


tiles 3 and 4


tiles 5 and 6


The last layer has an index unequal to the other indexes (which are empty). All following parts would be recognized as matches within the working map:

tiles 1 and 2 tiles 3 and 2
tiles 1 and 4 tiles 3 and 4
tiles 5 and 6

The Mana World Examples

The Mana World examples will demonstrate quite a lot of different Automapping features. At first a shoreline will be constructed, by first adding all the straight parts and afterwards another rule will correct the corners to make them also fit the given tileset. After the shoreline has been added, the waters will be marked as unwalkable for the game engine. Last but not least the grass should be made random by using 5 different grass tiles.


This is what we want to draw.


Here we have straight shorelines applied.


Here we have some corners.


And corners the other way round as well.


Here all unwalkable tiles are marked.


If you look closely at the grass, you’ll see they are now randomized.

Basic Shoreline

This example will demonstrate how a straight shoreline can easily be setup between shallow water grass tiles. In this example we will only implement the shoreline, which has grass in southern and water in northern direction.

So basically the meaning we will define in the input region is: All tiles which are south of a water tile and are not water tiles themselves, will be replaced by a shoreline tile

Tile layer








The region in which this Automapping rule should be defined is of 2 tiles in height and 1 tile in width. Therefore we need a layer called regions and it will have 2 tiles placed to indicate this region.

The input layer called input_Ground is depicted in the middle. Only the upper tile is filled by the water tile. The lower tile contains no tile. It is not an invisible tile, just no tile at all.

And whenever there is no tile in a place within the rule regions in an input layer, what kind of tiles will be allowed there? There will be allowed any tiles except all used tiles within all input layer with the same index and name.

Here we only have one tile layer as an input layer carrying only the water tile. Hence at the position, where no tile is located, all tiles except that water tile are allowed.

The output layer called output_Ground shows the tile which gets placed, if this rule matches.

Corners on a Shore Line

This example is a continuation of the previous example. Now the corners of the given shoreline should be implemented automatically. Within this article we will just examine the bent in corner shoreline in the topleft corner. The other shoreline corners are constructed the same way. So after the example is applied, we would like to have the corners of the shoreline get suitable tiles. Since we rely on the other example being finished, we will put the rules needed for the corners into another new rulefile. (which is listed afterwards in rules.txt)

../../_images/pattern1.png ../../_images/pattern2.png ../../_images/pattern3.png
../../_images/pattern4.png ../../_images/pattern5.png ../../_images/pattern6.png
../../_images/pattern7.png ../../_images/pattern8.png ../../_images/pattern9.png

The shoreline may have some more corners nearby, which means there may be more different tiles than the straight corner lines. In the figure we see all inputs which should be covered.

Both the tiles in the top right corner and in the lower left corner are directly adjacent to the desired (slightly transparent) tile in the top left corner.

We can see 3 different tiles for the lower left corner, which is straight shore line, bent inside and bent outside shore lines.

Also we see 3 different inputs for the top right corner, which also is straight, bent in or out shore line.

Input and Output Regions

So with this rule we want to put the bent in shore line tile in the top left corner, we don’t care which tile was there before. Also we don’t care about the tile in the lower right corner. (probably water, but can be any decorative watertile, so just ignore it).

../../_images/regions_input.png ../../_images/regions_output.png ../../_images/regions_united.png

Therefore we will need different input and output regions. In the figure we can see the both tile layers regions input and regions output. The input section covers just these two tiles as we discussed. The output region covers just the single tile we want to output. Though the input and output region do not overlap, the united region of both the input and the output region is still one coherent region, so it’s one rule and works.

Output regions can be larger than absolutely required, since where there are no tiles in an output region, the tiles in the working map are not overwritten but just kept as is, hence each output region could also be sized as the united region of both the output and input region.

Input Layers

Now we want to put all the nine possible patterns we observed as possible input for this rule. We could of course define nine different layers input1_Ground up to input9_Ground

Nine TileLayers?! What a mess, we’ll do it a better way.

Also, consider having not just 3 possible tiles at the 2 locations but 4. Then we would need 4*4=16 tilelayers to get all conditions. Another downside of this comes with more needed locations: Think of more than 2 locations needed to construct a ruleinput. So for 3 locations, then each location could have the 3 possibilites, hence you need 3*3*3 = 27 tilelayers. It’s not getting better…

So let’s try a smart way: All input layers have the same name, so at each position any of the three different tiles is valid.

Tile layer








Output Layer

The output is straight forward, since only one tile is needed. No randomness is needed, hence the index is not needed to be varied, so it’s kept empty. The desired output layer is called Ground, so the over all name of the single output layer will be output_Ground. The correct tile is placed at the correct location with this layer.


The Other Corners on a Shore Line

This is for corners bent the other way round. Basically it has the same concepts, just other tiles.

Tile layer














Adding Collision Tiles

The Mana World uses an extra tile layer called Collision to have information about whether a player is able to walk on certain tiles or not. That layer is invisible to the player, but the game engine parses it, whether there is a tile or there is no tile.

So we need to decide for each position if a player can walk there and put a tile into the Collision layer if it is unwalkable.

As input layer we will parse the Ground layer and put collision tiles where the player should not walk.

Actually this task is a bunch of rules, but each rule itself is very easy:

Tile layer








In the above regions layer we have 14 different rules, because there are 14 incoherent regions in the regions layer. That’s 9 different water tiles, which should be unwalkable and 5 different grass tiles which will be placed randomly in the next example.

As input we will have one of all the used tiles and as output there is either a tile in the Collision layer or not.

Do we need the rules with clean output? No, it is not needed for one run of Automapping. But if you are designing a map, you will likely add areas with collision and then remove some parts of it again and so on.

So we need to also remove the collision tiles from positions, which are not marked by a collision any more. This can be done by adding the map property DeleteTiles and setting it to true. Then all the parts in the Collision layer will be erased before the Automapping takes place, so the collision tiles are only placed at real unwalkable tiles and the history of if there has been a collision tile placed is neglected.

Random Grass Tiles

In this example we will shuffle all grass tiles, so each grass tile will be replaced with a randomly chosen tile.

As input we will choose all of our grass tiles. This is done by having each tile in its own input layer, so each grass tile gets accepted for this rule.

As output we will also put each grass tile into one output layer. To make it random the index of the output layers needs to be different for each layer.

The following rule might look the same, but there are different grass tiles. Each grass tile is in both one of the input and one of the output layers (the order of the layers doesn’t matter).

Tile layer
























An Alternating Wall

This example will demonstrate how a wall as a transition between a walkable area and the non-walkable black void can easily be setup. As input a dedicated set layer will be used.

Vertically the tiles are alternating A dedicated set layer

In my opinion a dedicated set layer is much easier to use for the rough draft, but for adding details such as collision information on decorative tiles the input should use the decoration.

The structure of the input, output and region layer is very similar to the example of the straight shoreline in The Mana World examples. The main difference is the different size. Since the wall contains multiple tiles in height, the height of the rule layers are different as well. Vertically the tiles are also alternating. As you can see in the following figure, every second tile displaying the base board of the wall has a notch for example.

Tile layer








Hence the region in which this Automapping rule should be defined is of 4 tiles in height and 2 tile in width. Therefore we need a layer called regions and it will have 8 tiles placed to indicate this region. In the figure the top graphics shows such a region layer.

The input layer has the following meaning:

If there are 2 vertical adjacent brown tiles in the set layer and in the 3x2 tiles above here are no brown tiles, this rule matches.

Only the lowest 2 coordinates contain the brown tile. The upper coordinates contain no tile. (It is not an invisible tile, just no tile at all.) The input layer called input_set is depicted in the middle of the figure.

The output consists of only one layer as well called output_Walls. It contains the actual wall tiles.


Vertically the tiles are alternating.


A broken version of the rule, because NoOverlappingRules was not yet set.

When trying to match the input layer to the desired set layer (right picture of the figure at the beginning of the example), you will see it matches all the way along, with no regard of the vertical adjustment.

Hence when we use the rule as discussed now, we will get not the desired result, because this rule overlaps itself. The overlapping problem is shown in figure above.

Since the overlapping is not desired, we can turn it off by adding the map property NoOverlappingRules to the rulemap and setting it to true.

Keep in mind that the map property applies for all rules on that rule map.