Export translations

Settings

Group

Language

Format

Export for off-line translation

Export in native format

Export in CSV format

{{MigrateTranslation}}
<languages />

<div lang="en" dir="ltr" class="mw-content-ltr">
The '''Automapper''' is a tool to make mapping easier for mappers. Instead of placing the round edges of freeze by hand you could make a simple [[#Rules File|automapper rule]] that applies a few rules to an entire tile layer. Every automapper is made for a specific tileset and every tileset can have multiple automappers. All automapper rules are located in your teeworlds path at ''data/editor/automap/''<ref name="Automapper">[https://forum.ddnet.org/viewtopic.php?t=2428 Automapper Tutorial]</ref><ref name="ddnet-automapperfiles">[https://github.com/ddnet/ddnet/tree/master/data/editor/automap Automapper files]</ref>.
</div>

==Rules File==

There is a ''tileset.rules'' textfile for every tileset that has an automapper. Each ''tileset.rules'' file can contain multiple automappers. The rules file loosely follows the [https://en.wikipedia.org/wiki/INI_file INI-file-format]. Inside the file every automapper starts with the line <code>[automapper_name]</code>. For example in the file ''grass_main.rules'' there is an automapper called ''Grass'' which starts at the line <code>[Grass]</code> inside the file. To use it you have to create a tilelayer with the tileset ''grass_main'' in the mapeditor. Rightclick on the [https://wiki.ddnet.org/wiki/Mapping#Layers layer] and click on ''"Auto map"''. To start automapping click ''"Grass"''.

The filename of the automapper '''has to''' follow the filename of the tileset.

Grass automapper<ref name="Grass automapper">[https://github.com/ddnet/ddnet/blob/0abb32514b6e9643154dc6bcdc4a754defbf2321/data/editor/automap/grass_main.rules#L1 Grass automapper]</ref>:

<pre>
[Default]
Index 1

#top
Index 16
Pos 0 -1 EMPTY
...
</pre>

==Processing==

The automapper will read the rules file and scan each '''position''' of the layer. If every rule of a selected tile applies, the tile will be placed at the scanned position of the automapper. If multiple tiles and their rules match, only the latest rule will apply (because it will be overwritten). [[#Syntax|Unless deactivated]], the automapper will put it's changes into a buffer first and apply them afterwards.
[[File:Indices.png|thumb|227x227px|Tileset indices overview]]

==Tile indices==

Every tileset has 16 rows and 16 columns and each tile can be addressed by its index. The index of a tile is a direct result of it's position and can be calculated by <code>index = 16 * row + column</code>, where row and column is between 0 and 15. The tile at index 0 is always considered <code>EMPTY</code>. Usually this part doesn't contain textures in tilesets. Each other tile is always considered <code>FULL</code>, even if it doesn't contain any textures and is fully transparent.

The index is used for the <code>INDEX</code> keyword of the automapper.

==Syntax==

'''Naming your automapper-rule''':

Similar to ini-files, you can create your own section for your automapper rule:

<code>[your-automapper-rule]</code>

Multiple index selections followed by rules can be part of a section.

'''Writing a comment''':

<code>#this is a comment</code>

'''Selecting a tile you want to place''':

<code>INDEX 42</code>

This '''selects''' tile 42 (meaning the 3rd row and 11th column. Multiple indices can be selected by adding an <code>OR</code> between each index:

<code>INDEX 42 OR 43</code>

'''Modifying the tile''':

<code>Index 42 XFLIP YFLIP ROTATE</code>

<code>XFLIP</code> mirrors the tile vertically and <code>YFLIP</code> mirrors the tile horizontally. <code>ROTATE</code> rotates the tile a single time by 90°.

IF you want to rotate a tile by 180°, you only need to set <code>XFLIP</code> and <code>YFLIP</code> '''but not''' <code>ROTATE</code>.

If you want to rotate by 270°, you need to set <code>XFLIP</code>, <code>YFLIP</code> and <code>ROTATE</code>.

Tile modifications are always in the same line as the selection.

'''Rule for placing the tile''':

The selected tile gets placed if '''all''' following rules apply.
A rule for placing the tile always starts with coordinates followed by a rule:

This rule selects the tile with ''X'' coordinate 0 and ''Y'' coordinate -1 '''relative to the''' [[#Processing|scanning position]] of the automapper. If the tile '''above''' the scanning position is <code>FULL</code>, the '''selected tile''' will be placed (if all following rules apply). If it's <code>EMPTY</code>, it won't be placed.

Instead of using <code>FULL</code> or <code>EMPTY</code>, you can select another tile with the <code>INDEX</code> keyword:

<code>POS 0 -1 INDEX 12</code>

If the tile above the [[#Processing|scanning position]] has index 12, it will be placed. Multiple indices can be selected by adding an <code>OR</code> between each index:

<code>POS 0 -1 INDEX 12 OR 13</code>

Similarly <code>NOTINDEX</code> can be used to exclude a tile.

'''Random rule''':

You can make a selected tile randomly apply to rules by adding a random rule:

<code>RANDOM 20%</code>

The random rule expects a value between 0% and 100%. This value represents the probability, that a tile is placed<ref name="RandomRule">[https://github.com/ddnet/ddnet/blob/0abb32514b6e9643154dc6bcdc4a754defbf2321/src/game/editor/auto_map.cpp#L312 Random rule implementation]</ref>.

If you put a ''value'' into it '''without''' a <code>%</code> symbol, the probability will not be parsed in terms of percentages, but with this formula:

<code>percentage = 1.0 / value</code>

This allows for rarer tile placements with probabilities between 0% and 1% and a ''value'' > 100.

For example <code>RANDOM 150</code> will have a probability of <code>1.0 / 150 ≈ 0.67</code> (percent).

'''Default condition rule''':

By default the game assumes, that you want to apply each rule to a full tile, meaning that the following rule is always implied:

You can deactivate this by adding the following line '''under''' the tile selection:

<code>NoDefaultRule</code>

'''NewRun''':

Adding <code>NewRun</code> in a section will make the section run an additional time for each time this keyword gets added to the section. This can be used to set some basic tiles in the first run, and more complex ones in the second.

'''NoLayerCopy''':

Adding <code>NoLayerCopy</code> in a section will cause it to run [https://en.wikipedia.org/wiki/In-place_algorithm in-place]. This can drastically improve performance, because the automapper doesn't copy it's changes into buffer memory before applying it. But it can cause unintended side effects!

==Tools==

Some tools in order to create automapper rules exist:
* [https://github.com/AssassinTee/SimpleDDNetAutomapper SimpleDDNetAutomapper] - a small UI application, which tries a more user friendly approach for very basic rules and tilesets. It does not support randomness, or <code>POS INDEX</code> rules, but <code>EMPTY</code> and <code>FULL</code>.
* [https://github.com/k2d222/twwe Teeworlds Web Editor] - Automapper edit and live-preview<ref name="twwe">[https://github.com/k2d222/twwe/blob/main/README.md#unique-features Teeworlds web editor unique features]</ref>.
* [https://github.com/Aerll/rpp rpp] - rules++ is a small experiment, aiming to make mappers utterly lazy, by unlocking the full potential of DDNet's rules. It is meant to be simple, readable and most importantly correct, everything else is irrelevant<ref name="rpp">[https://github.com/Aerll/rpp/blob/main/README.md#about rules++ about]</ref>.

==Resources==
<references />