Add autotile tutorial

Modify tutorials > 2D > using tilemaps to include section on
autotiles, covering different bitmask modes and scripted binding

tutorials/2d/using_tilemaps.rst

@@ -1,7 +1,7 @@
 .. _doc_using_tilemaps:
 
 Using tilemaps
-~~~~~~~~~~~~~~
+==============
 
 Introduction
 ------------
@@ -127,8 +127,10 @@ Atlas tiles
 -----------
 
 Rather than adding individual tiles one at a time, you can define a group of
-tiles all at once using an atlas. Click "New Atlas" and drag to select the
-entire tile sheet.
+tiles all at once using an atlas. This also allows you to randomly generate
+tiles from the group.
+
+Click "New Atlas" and drag to select the entire tile sheet.
 
 .. image:: img/tileset_atlas.png
 
@@ -150,6 +152,121 @@ tiles it contains:
 In addition to saving time when defining the tiles, this can help by grouping
 similar tiles together when you're working with a large number of tiles.
 
+Random tile priorities
+~~~~~~~~~~~~~~~~~~~~~~
+
+When drawing with atlas tiles, enabling the "Use priority" option causes tiles
+to be selected at random. By default, each tile in the tileset has an equal
+likelihood of occurring. You can change the likelihood by setting different
+priorities for each tile. For example, a tile with priority 2 is twice as
+likely to be selected as a tile with priority 1, and a tile with priority 3 is
+50% more likely to be selected than a tile with priority 2.
+
+Autotiles
+---------
+
+Autotiles allow you to define a group of tiles, then add rules to control which
+tile gets used for drawing based on the content of adjacent cells.
+
+Click "New Autotile" and drag to select the tiles you wish to use. You can add
+collisions, occlusion, navigation shapes, tile priorties, and select an icon
+tile in the same manner as for atlas tiles.
+
+Tile selection is controlled by bitmasks. Bitmasks can be added by clicking
+"Bitmask", then clicking parts of the tiles to add or remove bits in the mask.
+Left-clicking an area of the tile adds a bit, right-click removes "off",
+and shift-left-click sets an "ignore" bit.
+
+Whenever Godot updates a cell using an autotile, it first creates a pattern
+based on which adjacent cells are already set. Then, it searches the autotile
+for a single tile with a bitmask matching the created pattern. If no matching
+bitmask is found, the "icon" tile will be used instead. If more than one
+matching bitmask is found, one of them will be selected randomly, using the
+tile priorities.
+
+The rules for matching a bitmask to a pattern depend on the tileset's autotile
+bitmask mode. This can be set in the "Inspector" tab, under the "Selected Tile"
+heading. Allowed values are "2x2", "3x3 (minimal)", and "3x3".
+
+All "on" and "off" bits must be satisfied for a bitmask to match, but "ignore"
+bits are ignored.
+
+2x2
+~~~
+
+In 2x2 mode, each bitmask contains four bits, one for each corner.
+
+Where a bit is "on", all cells connected to that corner must be filled using
+the same autotile, in order for the bitmask to match.
+For example, if the top-left bit is set, the cell directly above,
+directly left, and diagonally above-left must be filled.
+
+Where a bit is "off", at least one cell connected to that corner must not be
+set using the same autotile.
+
+At least one bit must be set for the tile to be used, so a total of 15 tiles
+would be needed to provide exactly one tile for each arrangement that this mode
+can test for.
+
+2x2 mode can only match cells that are part of a 2-by-2 block - cells with no
+neighbors and lines only one cell wide are not supported.
+
+3x3 (minimal)
+~~~~~~~~~~~~~
+
+In 3x3 (minimal) mode, each bitmask contains 9 bits (4 corners, 4 edges,
+1 center).
+
+The 4 corner bits work the same as in 2x2 mode.
+
+When an edge bit is "on", the cell which shares that edge must be filled.
+When an edge bit is "off", the cell which shares that edge must be empty.
+
+The center bit should be "on" for any tile you wish to use.
+
+Note that in this mode, it makes no sense for a corner bit to be "on" when
+either edge bit adjacent to it is not "on".
+
+A total of 47 tiles would be needed to provide exactly one bitmask for each
+arrangement that this mode can test for.
+
+
+3x3
+~~~
+
+In 3x3 mode, each bitmaks contains 9 bits (4 corners, 4 edges, 1 center)
+
+Each bit checks a single adjacent cell. Corner bits only check diagonally
+adjacent cells. The center bit should be "on" for any tile you wish to use.
+
+A total of 256 tiles would be needed to provide exactly one bitmask for each
+arrangement that this mode can test for.
+
+
+Disabling autotile
+~~~~~~~~~~~~~~~~~~
+
+When using an autotile, it is possible to turn of the autotile behaviour and
+select tiles manually, by clicking "Disable Autotile" at the top of the tile
+selection window.
+
+Autotile binding
+~~~~~~~~~~~~~~~~
+
+By default, autotile only checks for adjacent cells filled using the same
+autotile. This behaviour can be overridden in order to have autotiles bind to
+each other, or even bind to empty cells. At present, this can only be done
+through scripting. You will need to add a script to your tileset, and define
+a function named "_is_tile_bound(drawn_id, neighbor_id)". This function will
+be called for each adjacent cell that does not contain the same autotile, and
+should return true if you want the drawn cell to "bind" to the neighbor cell.
+You can find the id of an autotile using "find_tile_by_name(name)", empty cells
+are given an id of -1.
+
+Note that to use this in the editor, the script should start with a "tool"
+declaration, and you may need to close and reload the scene for these changes
+to take effect.
+
 Tips and tricks
 ---------------