From 762ad4dc94ba1c6341c68cf9ba1ebdc41b9a4ff5 Mon Sep 17 00:00:00 2001 From: Peter Chaplin Date: Tue, 2 Jun 2020 19:06:17 +0100 Subject: [PATCH] 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 | 123 +++++++++++++++++++++++++++++++- 1 file changed, 120 insertions(+), 3 deletions(-) diff --git a/tutorials/2d/using_tilemaps.rst b/tutorials/2d/using_tilemaps.rst index 389dcc810..dc93d5a95 100644 --- a/tutorials/2d/using_tilemaps.rst +++ b/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 ---------------