Update TileSets and TileMaps documentation for Godot 4.0

The documentation was split into two pages, as there are much more
features to cover now.

Co-authored-by: Isaac <isaacwelfare@gmail.com>

tutorials/2d/index.rst

@@ -38,4 +38,5 @@ Tools
    :maxdepth: 1
    :name: toc-learn-features-2d-tools
 
+   using_tilesets
    using_tilemaps

tutorials/2d/using_tilemaps.rst

@@ -5,6 +5,12 @@
 Using TileMaps
 ==============
 
+.. seealso::
+
+    This page assumes you have created or downloaded a TileSet already. If not,
+    please read :ref:`doc_using_tilesets` first as you will need a TileSet
+    to create a TileMap.
+
 Introduction
 ------------
 
@@ -14,342 +20,453 @@ First, they make it possible to draw the layout by "painting" the tiles onto a
 grid, which is much faster than placing individual :ref:`Sprite2D <class_Sprite2D>`
 nodes one by one. Second, they allow for much larger levels because they are
 optimized for drawing large numbers of tiles. Finally, you can add collision,
-occlusion, and navigation shapes to tiles, adding additional functionality to
+occlusion, and navigation shapes to tiles, adding greater functionality to
 the TileMap.
 
-.. image:: img/tileset_draw_atlas.png
-
-Project setup
--------------
-
-This demo will use the following tiles taken from Kenney's "Abstract Platformer"
-art pack. You can find the complete set `here <https://kenney.nl/assets/abstract-platformer>`_
-but for this demo we'll stick to this small set.
-
-.. image:: img/tilesheet.png
-
-Create a new project and place the above image in the project folder.
-
-When using a tileset, it's important that adjacent tiles match up. Godot's default
-is to import 2D images using an interpolated "filter" mode, which will result in
-ugly borders between the tiles. Select the image and click the Import tab. Turn
-off ``Filter`` and click "Reimport". See :ref:`doc_import_images` for details.
-
-TileMap node
-------------
-
-Add a new :ref:`TileMap <class_TileMap>` node to the scene. By default, a TileMap
-uses a square grid of tiles. You can also use a perspective-based "Isometric" mode
-or define your own custom tile shape.
-
-.. image:: img/tilemap_mode.png
-
-Under the "Cell" section in the Inspector are many properties you can adjust to
-customize your tilemap's behavior:
-
-.. image:: img/tilemap_size.png
-
-- ``Cell Size``
-    This defines the size of the grid. This should match the pixel size
-    of your tiles. The default value is ``(64, 64)``.
-
-- ``YSort``
-    This causes tiles to be drawn in order of their ``Y`` position, so that
-    "lower" tiles are drawn on top of "higher" ones.
-
-- ``Half Offset`` and ``Tile Origin``
-    These properties affect the position of the tile relative to the grid position.
-
-- ``Quadrant``
-    Defines the chunk size used for batched drawing. This can negatively
-    affect performance. Don't change it unless you know what you're doing.
-
-- ``Custom Transform``
-    Used to alter the tile's shape. Use this if you have non-square tiles.
-
-All of these options can be left at their defaults for this demo.
-
-Creating a TileSet
-------------------
-
-Once you've configured your tilemap, it's time to add a
-:ref:`TileSet <class_TileSet>`. A TileSet is a
-:ref:`Resource <class_Resource>` that contains the data about your
-tiles - their   textures, collision shapes, and other properties. When the game
-runs, the TileMap combines the individual tiles into a single object.
-
-To add a new TileSet, click on the "Tile Set" property and select "New
-TileSet".
-
-.. image:: img/tilemap_add_tileset.png
-
-Click on the TileSet property, and the "TileSet" panel will open at the bottom
-of the editor window:
-
-.. image:: img/tilemap_tool.png
-
-First, you need to add the texture(s) that you'll use for the tiles. Click the
-"Add Texture(s) to TileSet" button and select the ``tilesheet.png`` image.
-
-Next, click "New Single Tile" and drag in the image to select the tile you want.
-Click the "Enable Snap" button to make it easier to select the entire tile. A
-yellow rectangle appears around the selected tile.
-
-.. image:: img/tilemap_add_tile.png
-
-Click on the TileMap in the scene tree, and you'll see that the newly created
-tile now appears on the right side. Click in the viewport and you can place
-tiles. Right-click to remove them.
-
-.. image:: img/tilemap_draw.png
-
-It's easy to accidentally select and move the tilemap node. To avoid this, use
-the node's lock button:
-
-.. image:: img/tile_lock.png
-
-Collision shapes
-----------------
-
-If you're making a map that needs collisions - walls, floor, or other obstacles,
-for example - then you'll need to add collision shapes to any tiles that you
-want to be considered "solid".
-
-Click "TileSet" at the bottom of the editor window to return to the tileset
-tool. Click the tile you previously defined (outlined in yellow). Select the
-"Collision" tab and click the "Create a new rectangle" button. Make sure you
-still have grid snap enabled, then click and drag in the tile. A square
-collision shape appears in light blue:
-
-.. image:: img/tileset_add_collision.png
-
-You can add occlusion and navigation shapes to the tile in the same way.
-
-Atlas tiles
------------
-
-Rather than adding individual tiles one at a time, you can define a group of
-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
-
-If you haven't already, make sure to change the "Step" in the snap settings to
-`(64, 64)`, or your tiles may be chopped into smaller pieces. You can find
-this in the Inspector:
-
-.. image:: img/tileset_snap.png
-
-Once you've defined the atlas you can add collision shapes to the individual
-tiles as before. You can also click "Icon" to select one of the tiles to represent
-the atlas.
-
-Back in the TileMap, you can select the atlas tile and you'll see all of the
-tiles it contains:
-
-.. image:: img/tileset_draw_atlas.png
-
-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.
-
-**Template - Generic:**
-
-This template can be used for sideways or fully top-down perspectives.
-It's designed for a TileMap cell size of 64x64.
-
-Key:
-
-- Red: "on"
-- White: "off"
-
-.. image:: img/autotile_template_2x2.png
-
-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.
-
 .. note::
 
-    Right-click an image and choose **Save image as…** to save it.
+    Godot 4.0 has moved several per-tile properties, such as tile rotation, from
+    TileMap to TileSet. Individual tiles can no longer be rotated while in the
+    TileMap editor. Instead, the TileSet editor must be used to create
+    alternative rotated tiles.
 
-**Template - Generic:**
+    This change allows for greater design consistency, as not every tile needs to be
+    rotated or flipped within a TileSet.
 
-This template can be used for sideways or fully top-down perspectives.
-All templates below are designed for a TileMap cell size of 64x64, but you may
-have to use different subtile sizes for top-down templates as described below.
+Specifying the TileSet in the TileMap
+-------------------------------------
 
-Key:
+If you've followed the previous page on :ref:`doc_using_tilesets`, you should
+have a TileSet resource that is built-in to the TileMap node. This is good for
+prototyping, but in a real world project, you will generally have multiple
+levels reusing the same tileset.
 
-- Red: "on"
-- White: "off"
+The recommended way to reuse the same TileSet in several TileMap nodes is to save
+the TileSet to an external resource. To do so, click the dropdown next to the TileSet
+resource and choose **Save**:
 
-.. image:: img/autotile_template_3x3_minimal.png
+.. figure:: img/using_tilemaps_save_tileset_to_resource.webp
+   :align: center
+   :alt: Saving the built-in TileSet resource to an external resource file
 
+   Saving the built-in TileSet resource to an external resource file
 
-**Template - Generic 16 tiles:**
+Creating TileMap layers
+-----------------------
 
-This template can be used for tilesets that only have 16 tiles - for simpler art
-styles the missing tiles will not be noticeable.
+As of Godot 4.0, you can place several *layers* in a single TileMap node. For
+example, this allows you to distinguish foreground tiles from background tiles
+for better organization. You can place one tile per layer at a given location,
+which allows you to overlap several tiles together if you have more than one layer.
 
-Key:
+By default, a TileMap node automatically has one premade layer. You do not have
+to create additional layers if you only need a single layer, but if you wish to
+do so now, select the TileMap node and unfold the **Layers** section in the
+inspector:
 
-- Red: "on"
-- White: "off"
-- Blue-checkered: "ignore"
+.. figure:: img/using_tilemaps_create_layers.webp
+   :align: center
+   :alt: Creating layers in a TileMap node (example with "background" and "foreground")
 
-.. image:: img/autotile_template_3x3_minimal_16.png
+   Creating layers in a TileMap node (example with "background" and "foreground")
 
+Each layer has several properties you can adjust:
 
-**Template - Top-down floor in 3/4 perspective:**
+- **Name:** A human-readable name to display in the TileMap editor. This can be
+  something like "background", "buildings", "vegetation", etc.
+- **Enabled:** If ``true``, the layer is visible in the editor and when running
+  the project.
+- **Modulate:** The color to use as a multiplier for all tiles on the layer.
+  This is also multiplied with the per-tile **Modulate** property and the
+  TileMap node's **Modulate** property. For example, you can use this to darken
+  background tiles to make foreground tiles stand out more.
+- **Y Sort Enabled:** If ``true``, sorts tiles based on their Y position on the
+  TileMap. This can be used to prevent sorting issues with certain tile setups,
+  especially with isometric tiles.
+- **Y Sort Origin:** The vertical offset to use for Y-sorting on each tile (in pixels).
+  Only effective if **Y Sort Enabled** is ``true``.
+- **Z Index:** Controls whether this layer is drawn in front of or behind other
+  TileMap layers. This value can be positive or negative; the layer with the highest Z
+  Index is drawn on top of other layers. If several layers have an equal Z Index
+  property, the layer that is *last* in the list of layers (the one which
+  appears at the bottom in the list) is drawn on top.
 
-Key (applies to the four templates below):
+You can reorder layers by drag-and-dropping the "three horizontal bars" icon on
+the left of the entries in the **Layers** section.
 
-- Green: floor
-- Cyan: wall
-- Yellow: top of wall
-- Transparent: air
+.. note::
 
-.. image:: img/autotile_template_3x3_minimal_topdown_floor.png
+    You can create, rename or reorder layers in the future without affecting
+    existing tiles. Be careful though, as *removing* a layer will also remove
+    all tiles that were placed on the layer.
 
-**Template - Top-down wall in 3/4 perspective:**
+Opening the TileMap editor
+--------------------------
 
-.. image:: img/autotile_template_3x3_minimal_topdown_walls.png
+Select the TileMap node, then open the TileMap panel at the bottom
+of the editor:
 
-**Template - Top-down wall in 3/4 perspective (thick walls):**
+.. figure:: img/using_tilemaps_open_tilemap_editor.webp
+   :align: center
+   :alt: Opening the TileMap panel at the bottom of the editor. The TileMap node must be selected first.
 
-When using this template, set the TileSet subtile size to ``Vector2(64, 88)``.
+   Opening the TileMap panel at the bottom of the editor. The TileMap node must be selected first.
 
-.. image:: img/autotile_template_3x3_minimal_topdown_walls_thick.png
+Selecting tiles to use for painting
+-----------------------------------
 
-**Template - Top-down wall in 3/4 perspective (tall walls):**
+First, if you've created additional layers above, make sure you've selected the
+layer you wish to paint on:
 
-When using this template, set the "Snap Options" Step to ``Vector2(64, 184)``
-and the "Selected Tile" Texture offset to height minus the cell size.
-This means the texture offset should be ``Vector2(0, -120)``:
+.. figure:: img/using_tilemaps_select_layer.webp
+   :align: center
+   :alt: Selecting a layer to paint on in the TileMap editor
 
-.. image:: img/autotile_template_3x3_minimal_topdown_walls_tall.png
+   Selecting a layer to paint on in the TileMap editor
 
-3x3
-~~~
+.. tip::
 
-In 3x3 mode, each bitmask contains 9 bits (4 corners, 4 edges, 1 center)
+    In the 2D editor, the layers you aren't currently editing from the same
+    TileMap node will appear grayed out while in the TileMap editor. You can
+    disable this behavior by clicking the icon next to the layer selection menu
+    (**Highlight Selected TileMap Layer** tooltip).
 
-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.
+You can skip the above step if you haven't created additional layers, as the
+first layer is automatically selected when entering the TileMap editor.
 
-A total of 256 tiles would be needed to provide exactly one bitmask for each
-arrangement that this mode can test for.
+Before you can place tiles in the 2D editor, you must select one or more tiles
+in the TileMap panel located at the bottom of the editor. To do so, click a tile
+in the TileMap panel, or hold down the mouse button to select multiple tiles:
 
+.. figure:: img/using_tilemaps_select_single_tile_from_tileset.webp
+   :align: center
+   :alt: Selecting a tile in the TileMap editor by clicking it
 
-Disabling autotile
-~~~~~~~~~~~~~~~~~~
+   Selecting a tile in the TileMap editor by clicking it
 
-When using an autotile, it is possible to turn off the autotile behaviour and
-select tiles manually, by clicking "Disable Autotile" at the top of the tile
-selection window.
+.. tip::
 
-Autotile binding
-~~~~~~~~~~~~~~~~
+    Like in the 2D and TileSet editors, you can pan across the TileMap panel using
+    the middle or right mouse buttons, and zoom using the mouse wheel or buttons in
+    the top-left corner.
 
-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.
+You can also hold down :kbd:`Shift` to append to the current selection. When
+selecting more than one tile, multiple tiles will be placed every time you
+perform a painting operation. This can be used to paint structures composed of
+multiple tiles in a single click (such as large platforms or trees).
 
-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.
+The final selection does not have to be contiguous: if there is empty space
+between selected tiles, it will be left empty in the pattern that will be
+painted in the 2D editor.
 
-Tips and tricks
----------------
+.. figure:: img/using_tilemaps_select_multiple_tiles_from_tileset.webp
+   :align: center
+   :alt: Selecting multiple tiles in the TileMap editor by holding down the left mouse button
 
-- If you're using a :ref:`Camera2D <class_Camera2D>` to scroll your level, you
-  may notice lines appearing between your tiles. To fix this, open Project
-  Settings and enable **Use Gpu Pixel Snap** in the **Rendering > 2d > Snapping** section.
+   Selecting multiple tiles in the TileMap editor by holding down the left mouse button
 
-- You can flip and rotate tiles using the icons at the top right of the editor.
+If you've created alternative tiles in your TileSet, you can select them for
+painting on the right of the base tiles:
 
-- To draw straight lines, hold :kbd:`Shift` while clicking and dragging a tile.
+.. figure:: img/using_tilemaps_use_alternative_tile.webp
+   :align: center
+   :alt: Selecting an alternative tile in the TileMap editor
 
-- Tools such as copy, paste, and bucket fill, can be found in the "TileMap"
-  menu in the upper-right.
+   Selecting an alternative tile in the TileMap editor
 
-.. image:: img/tilemap_menu.png
+Lastly, if you've created a *scenes collection* in the TileSet, you can place scene tiles in the TileMap:
+
+.. figure:: img/using_tilemaps_placing_scene_tiles.webp
+   :align: center
+   :alt: Placing a scene tile containing particles using the TileMap editor
+
+   Placing a scene tile containing particles using the TileMap editor
+
+Painting modes and tools
+------------------------
+
+Using the toolbar at the top of the TileMap editor, you can choose between
+several painting modes and tools. These modes affect operation when clicking in
+the 2D editor, **not** the TileMap panel itself.
+
+From left to right, the painting modes and tools you can choose are:
+
+Selection
+^^^^^^^^^
+
+Select tiles by clicking a single tile, or by holding down the left mouse button to
+select multiple with a rectangle in the 2D editor. Note that empty space cannot be
+selected: if you create a rectangle selection, only non-empty tiles will be selected.
+
+To append to the current selection, hold :kbd:`Shift` then select a tile.
+To remove from the current selection, hold :kbd:`Ctrl` then select a tile.
+
+The selection can then be used in any other painting mode to quickly create copies
+of an already-placed pattern.
+
+While in Selection mode, you can't place new tiles, but you can still erase
+tiles by right-clicking after making a selection. The whole selection will be erased,
+regardless of where you click in the selection.
+
+You can toggle this mode temporarily while in Paint mode by holding :kbd:`Ctrl`
+then performing a selection.
+
+.. tip::
+
+    You can copy and paste tiles that were already placed by performing a
+    selection, pressing :kbd:`Ctrl + C` then pressing :kbd:`Ctrl + V`.
+    The selection will be pasted after left-clicking. You can press
+    :kbd:`Ctrl + V` another time to perform more copies this way.
+    Right-click or press :kbd:`Escape` to cancel pasting.
+
+Paint
+^^^^^
+
+The standard Paint mode allows you to place tiles by clicking or holding
+down the left mouse button.
+
+If you right-click, the currently selected tile will be erased from the tilemap.
+In other words, it will be replaced by empty space.
+
+If you have selected multiple tiles in the TileMap or using the Selection tool,
+they will be placed every time you click or drag the mouse while holding down
+the left mouse button.
+
+.. tip::
+
+    While in Paint mode, you can draw a line by holding :kbd:`Shift` *before*
+    holding down the left mouse button, then dragging the mouse to the line's end
+    point. This is identical to using the Line tool described below.
+
+    You can also draw a rectangle by holding :kbd:`Ctrl` and :kbd:`Shift`
+    *before* holding down the left mouse button, then dragging the mouse to the
+    rectangle's end point. This is identical to using the Rectangle tool
+    described below.
+
+    Lastly, you can pick existing tiles in the 2D editor by holding :kbd:`Ctrl`
+    then clicking on a tile (or holding and dragging the mouse).
+    This will switch the currently painted tile(s) to the tile(s) you've just clicked.
+    This is identical to using the Picker tool described below.
+
+Line
+^^^^
+
+After selecting Line Paint mode, you can draw in a line that is
+always 1 tile thick (no matter its orientation).
+
+If you right-click while in Line Paint mode, you will erase in a line.
+
+If you have selected multiple tiles in the TileMap or using the Selection tool,
+you can place them in a repeating pattern across the line.
+
+You can toggle this mode temporarily while in Paint or Eraser mode by holding
+:kbd:`Shift` then drawing.
+
+.. figure:: img/using_tilemaps_bucket_fill.webp
+   :align: center
+   :alt: Using the line tool after selecting two tiles to draw platforms diagonally
+
+   Using the line tool after selecting two tiles to draw platforms diagonally
+
+Rectangle
+^^^^^^^^^
+
+After selecting Rectangle Paint mode, you can draw in an axis-aligned
+rectangle.
+
+If you right-click while in Rectangle Paint mode, you will erase in
+an axis-aligned rectangle.
+
+If you have selected multiple tiles in the TileMap or using the Selection tool,
+you can place them in a repeating pattern within the rectangle.
+
+You can toggle this mode temporarily while in Paint or Eraser mode by holding
+:kbd:`Ctrl` and :kbd:`Shift` then drawing.
+
+Bucket Fill
+^^^^^^^^^^^
+
+After selecting Bucket Fill mode, you can choose whether painting should be
+limited to contiguous areas only by toggling the **Contiguous** checkbox that
+appears on the right of the toolbar.
+
+If you enable **Contiguous** (the default), only matching tiles that touch the
+current selection will be replaced. This contiguous check is performed
+horizontally and vertically, but *not* diagonally.
+
+If you disable **Contiguous**, all tiles with the same ID in the entire TileMap will
+be replaced by the currently selected tile. If selecting an empty tile with
+**Contiguous** unchecked, all tiles in the rectangle that encompasses the
+TileMap's effective area will be replaced instead.
+
+If you right-click while in Bucket Fill mode, you will replace matching tiles
+with empty tiles.
+
+If you have selected multiple tiles in the TileMap or using the Selection tool,
+you can place them in a repeating pattern within the filled area.
+
+.. figure:: img/using_tilemaps_bucket_fill.webp
+   :align: center
+   :alt: Using the Bucket Fill tool
+
+   Using the Bucket Fill tool
+
+Picker
+^^^^^^
+
+After selecting Picker mode, you can pick existing tiles in the 2D editor by
+holding :kbd:`Ctrl` then clicking on a tile. This will switch the currently
+painted tile to the tile you've just clicked. You can also pick multiple tiles
+at once by holding down the left mouse button and forming a rectangle selection.
+Only non-empty tiles can be picked.
+
+You can toggle this mode temporarily while in Paint mode by holding :kbd:`Ctrl`
+then clicking or dragging the mouse.
+
+Eraser
+^^^^^^
+
+This mode is combined with any other painting mode (Paint, Line, Rectangle,
+Bucket Fill). When eraser mode is enabled, tiles will be replaced by empty tiles
+instead of drawing new lines when left-clicking.
+
+You can toggle this mode temporarily while in any other mode by right-clicking
+instead of left-clicking.
+
+Painting randomly using scattering
+----------------------------------
+
+While painting, you can optionally enable *randomization*. When enabled,
+a random tile will be chosen between all the currently selected tiles when
+painting. This is supported with the Paint, Line, Rectangle and Bucket Fill
+tools. For effective paint randomization, you must select multiple tiles
+in the TileMap editor or use scattering (both approaches can be combined).
+
+If **Scattering** is set to a value greater than 0, there is a chance that no tile
+will be placed when painting. This can be used to add occasional, non-repeating
+detail to large areas (such as adding grass or crumbs on a large top-down
+TileMap).
+
+Example when using Paint mode:
+
+.. figure:: img/using_tilemaps_scatter_tiles.webp
+   :align: center
+   :alt: Selecting from several times to randomly choose, then painting by holding down the left mouse button
+
+   Selecting from several times to randomly choose, then painting by holding down the left mouse button
+
+Example when using Bucket Fill mode:
+
+.. figure:: img/using_tilemaps_bucket_fill_scatter.webp
+   :align: center
+   :alt: Using Bucket Fill tool with a single tile, but with randomization and scattering enabled
+
+   Using Bucket Fill tool with a single tile, but with randomization and scattering enabled
+
+.. note::
+
+    Eraser mode does not take randomization and scattering into account.
+    All tiles within the selection are always removed.
+
+Saving and loading premade tile placements using patterns
+---------------------------------------------------------
+
+While you can copy and paste tiles while in Select mode, you may wish to save
+premade *patterns* of tiles to place together in a go. This can be done on a
+per-TileMap basis by choosing the **Patterns** tab of the TileMap editor.
+
+To create a new pattern, switch to Select mode, perform a selection and press
+:kbd:`Ctrl + C`. Click on empty space within the Patterns tab (a blue focus
+rectangle should appear around the empty space), then press :kbd:`Ctrl + V`:
+
+.. figure:: img/using_tilemaps_create_pattern.webp
+   :align: center
+   :alt: Creating a new pattern from a selection in the TileMap editor
+
+   Creating a new pattern from a selection in the TileMap editor
+
+To use an existing pattern, click its image in the **Patterns** tab, switch to
+any painting mode, then left-click somewhere in the 2D editor:
+
+.. figure:: img/using_tilemaps_use_pattern.webp
+   :align: center
+   :alt: Placing an existing pattern using the TileMap editor
+
+   Placing an existing pattern using the TileMap editor
+
+Like multi-tile selections, patterns will be repeated if used with the Line,
+Rectangle or Bucket Fill painting modes.
+
+.. note::
+
+    Despite being edited in the TileMap editor, patterns are stored in the
+    TileSet resource. This allows reusing patterns in different TileMap nodes
+    after loading a TileSet resource saved to an external file.
+
+Handling tile connections automatically using terrains
+------------------------------------------------------
+
+To use terrains, the TileMap node must feature at least one terrain set and a
+terrain within this terrain set. See
+:ref:`doc_using_tilesets_creating_terrain_sets` if you haven't created a terrain
+set for the TileSet yet.
+
+There are 3 kinds of painting modes available for terrain connections:
+
+- **Connect**, where tiles are connected to surrounding tiles on the same
+  TileMap layer.
+- **Path**, where tiles are connected to tiles painted in the same stroke (until
+  the mouse button is released).
+- Tile-specific overrides to resolve conflicts or handle situations not covered
+  by the terrain system.
+
+The Connect mode is easier to use, but Path is more flexible as it allows for
+more artist control during painting. For instance, Path can allow roads to be
+directly adjacent to each other without being connected to each other, while
+Connect will force both roads to be connected.
+
+.. figure:: img/using_tilemaps_terrain_select_connect_mode.webp
+   :align: center
+   :alt: Selecting Connect mode in the TileMap editor's Terrains tab
+
+   Selecting Connect mode in the TileMap editor's Terrains tab
+
+.. figure:: img/using_tilemaps_terrain_select_path_mode.webp
+   :align: center
+   :alt: Selecting Path mode in the TileMap editor's Terrains tab
+
+   Selecting Path mode in the TileMap editor's Terrains tab
+
+Lastly, you can select specific tiles from the terrain to resolve conflicts in
+certain situations:
+
+.. figure:: img/using_tilemaps_terrain_paint_specific_tiles.webp
+   :align: center
+   :alt: Painting with specific tiles in the TileMap editor's Terrains tab
+
+   Painting with specific tiles in the TileMap editor's Terrains tab
+
+Any tile that has at least one of its bits set to a value set to the
+corresponding terrain ID will appear in the list of tiles to choose from.
+
+Handling missing tiles
+----------------------
+
+If you remove tiles in the TileSet that are referenced in a TileMap, the TileMap
+will display a placeholder to indicate that an invalid tile ID is placed:
+
+.. figure:: img/using_tilemaps_missing_tiles.webp
+   :align: center
+   :alt: Missing tiles in the TileMap editor due to the TileSet reference being broken
+
+   Missing tiles in the TileMap editor due to the TileSet reference being broken
+
+These placeholders are **not** visible in the running project, but the tile data
+is still persisted to disk. This allows you to safely close and reopen such
+scenes. Once you re-add a tile with the matching ID, the tiles will appear with
+the new tile's appearance.
+
+.. note::
+
+    Missing tile placeholders may not be visible until you select the TileMap
+    node and open the TileMap editor.

tutorials/2d/using_tilesets.rst

@@ -0,0 +1,665 @@
+.. _doc_using_tilesets:
+
+Using TileSets
+==============
+
+Introduction
+------------
+
+A tilemap is a grid of tiles used to create a game's layout. There are several
+benefits to using :ref:`TileMap <class_TileMap>` nodes to design your levels.
+First, they let you draw a layout by "painting" tiles onto a grid,
+which is much faster than placing individual :ref:`Sprite2D
+<class_Sprite2D>` nodes one by one. Second, they allow for larger levels
+because they are optimized for drawing large numbers of tiles.
+Finally, they allow you to add greater functionality to your tiles with
+collision, occlusion, and navigation shapes.
+
+To use tilemaps, you will need to create a TileSet first. A TileSet is a
+collection of tiles that can be placed in a TileMap node. After creating a
+TileSet, you will be able to place them :ref:`using the TileMap editor
+<doc_using_tilemaps>`.
+
+To follow this guide, you will need an image containing your tiles where every
+tile has the same size (large objects can be split into several tiles). This
+image is called a *tilesheet*. Tiles do not have to be square: they can be
+rectangular, hexagonal, or isometric (pseudo-3D perspective).
+
+Creating a new TileSet
+----------------------
+
+.. _doc_creating_tilesets_using_tilesheet:
+
+Using a tilesheet
+^^^^^^^^^^^^^^^^^
+
+This demonstration will use the following tiles taken from
+`Kenney's "Abstract Platformer" pack <https://kenney.nl/assets/abstract-platformer>`__.
+We'll use this particular *tilesheet* from the set:
+
+.. figure:: img/using_tilesets_kenney_abstract_platformer_tile_sheet.webp
+   :align: center
+   :alt: Tilesheet example with 64×64 tiles
+
+   Tilesheet with 64×64 tiles. Credit: `Kenney <https://kenney.nl/assets/abstract-platformer>`__
+
+Create a new **TileMap** node, then select it and create a new TileSet resource in the inspector:
+
+.. figure:: img/using_tilesets_create_new_tileset.webp
+   :align: center
+   :alt: Creating a new TileSet resource within the TileMap node
+
+   Creating a new TileSet resource within the TileMap node
+
+After creating the TileSet resource, click the value to unfold it in the
+inspector. The default tile shape is Square, but you can also choose Isometric,
+Half-Offset Square or Hexagon (depending on the shape of your tile images). If
+using a tile shape other than Square, you may also need to adjust the **Tile
+Layout** and **Tile Offset Axis** properties. Lastly, enabling the
+**Rendering > UV Clipping** property may be useful if you wish tiles to be clipped
+by their tile coordinates. This ensures tiles cannot draw outside their allocated
+area on the tilesheet.
+
+Set the tile size to 64×64 in the inspector to match the example tilesheet:
+
+.. figure:: img/using_tilesets_specify_size_then_edit.webp
+   :align: center
+   :alt: Setting the tile size to 64×64 to match the example tilesheet
+
+   Setting the tile size to 64×64 to match the example tilesheet
+
+If relying on automatic tiles creation (like we're about to do here), you must
+set the tile size **before** creating the *atlas*. The atlas will
+determine which tiles from the tilesheet can be added to a TileMap node
+(as not every part of the image may be a valid tile).
+
+Open the **TileSet** panel at the bottom of the editor, then click the "+" icon
+in the bottom-left corner to add a new atlas:
+
+.. figure:: img/using_tilesets_create_new_atlas.webp
+   :align: center
+   :alt: Creating a new atlas in a TileSet resource using the bottom panel
+
+   Creating a new atlas in a TileSet resource using the bottom panel
+
+After creating an atlas, you must assign a tilesheet texture to it.
+This can be done by choosing it on the left column of the bottom panel, then
+clicking the value of the **Texture** property and choosing **Quick Load** (or **Load**).
+Specify the path to the image file using the file dialog that appears.
+
+.. figure:: img/using_tilesets_load_tilesheet.webp
+   :align: center
+   :alt: Loading a tilesheet image in the newly created TileSet atlas
+
+   Loading a tilesheet image in the newly created TileSet atlas
+
+After specifying a valid image, you will be asked whether to create tiles
+automatically. Answer **Yes**:
+
+.. figure:: img/using_tilesets_create_tiles_automatically.webp
+   :align: center
+   :alt: Automatically creating tiles based on tilesheet image content
+
+   Automatically creating tiles based on tilesheet image content
+
+This will automatically create tiles according to the tile size you specified
+earlier in the TileSet resource. This greatly speeds up initial tile setup.
+
+.. note::
+
+    When using automatic tile generation based on image contents, parts of the
+    tilesheet that are *fully* transparent will not have tiles generated.
+
+If there are tiles from the tilesheet you do not wish to be present in atlas,
+choose the Eraser tool at the top of the tileset preview, then click the tiles
+you wish to remove:
+
+.. figure:: img/using_tilesets_eraser_tool.webp
+   :align: center
+   :alt: Using the Eraser tool to remove unwanted tiles from the TileSet atlas
+
+   Using the Eraser tool to remove unwanted tiles from the TileSet atlas
+
+You can also right-click a tile and choose **Delete**, as an alternative to the
+Eraser tool.
+
+.. tip::
+
+    Like in the 2D and TileMap editors, you can pan across the TileSet panel using
+    the middle or right mouse buttons, and zoom using the mouse wheel or buttons in
+    the top-left corner.
+
+If you wish to source tiles from several tilesheet images for a single TileSet,
+create additional atlases and assign textures to each of them before continuing.
+It is also possible to use one image per tile this way (although using
+tilesheets is recommended for better usability).
+
+You can adjust properties for the atlas in the middle column:
+
+.. figure:: img/using_tilesets_properties.webp
+   :align: center
+   :alt: Adjusting TileSet atlas properties in the dedicated inspector (part of the TileSet panel)
+
+   Adjusting TileSet atlas properties in the dedicated inspector (part of the TileSet panel)
+
+The following properties can be adjusted on the atlas:
+
+- **ID:** The identifier (unique within this TileSet), used for sorting.
+- **Name:** The human-readable name for the atlas. Use a descriptive name
+  here for organizational purposes (such as "terrain", "decoration", etc).
+- **Margins:** The margins on the image's edges that should not be selectable as
+  tiles (in pixels). Increasing this can be useful if you download a tilesheet
+  image that has margins on the edges (e.g. for attribution).
+- **Separation:** The separation between each tile on the atlas in pixels.
+  Increasing this can be useful if the tilesheet image you're using contains
+  guides (such as outlines between every tile).
+- **Texture Region Size:** The size of each tile on the atlas in pixels. In most
+  cases, this should match the tile size defined in the TileMap property
+  (although this is not strictly necessary).
+- **Use Texture Padding:** If checked, adds a 1-pixel transparent edge around
+  each tile to prevent texture bleeding when filtering is enabled.
+  It's recommended to leave this enabled unless you're running into rendering issues
+  due to texture padding.
+
+Note that changing texture margin, separation and region size may cause tiles to
+be lost (as some of them would be located outside the atlas image's
+coordinates). To regenerate tiles automatically from the tilesheet, use the
+three vertical dots menu button at the top of the TileSet editor and choose
+**Create Tiles in Non-Transparent Texture Regions**:
+
+.. figure:: img/using_tilesets_recreate_tiles_automatically.webp
+   :align: center
+   :alt: Recreating tiles automatically after changing atlas properties
+
+   Recreating tiles automatically after changing atlas properties
+
+Using a collection of scenes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since Godot 4.0, you can place actual *scenes* as tiles. This allows you to use
+any collection of nodes as a tile. For example, you could use scene tiles to
+place gameplay elements, such as shops the player may be able to interact with.
+You could also use scene tiles to place AudioStreamPlayer2Ds (for ambient
+sounds), particle effects, and more.
+
+.. warning::
+
+   Scene tiles come with a greater performance overhead compared to atlases, as
+   every scene is instanced individually for every placed tile.
+
+   It's recommended to use only scene tiles when necessary. To draw sprites in a
+   tile without any kind of advanced manipulation,
+   :ref:`use atlases instead <doc_creating_tilesets_using_tilesheet>`.
+
+For this example, we'll create a scene containing a CPUParticles2D root node.
+Save this scene to a scene file (separate from the scene containing the
+TileMap), then switch to the scene containing the TileMap node. Open the TileSet
+editor, and create a new **Scenes Collection** in the left column:
+
+.. figure:: img/using_tilesets_recreate_tiles_automatically.webp
+   :align: center
+   :alt: Creating a scenes collection in the TileSet editor
+
+   Creating a scenes collection in the TileSet editor
+
+After creating a scenes collection, you can enter a descriptive name for the
+scenes collection in the middle column if you wish. Select this scenes
+collection then create a new scene slot:
+
+.. figure:: img/using_tilesets_scene_collection_create_scene_tile.webp
+   :align: center
+   :alt: Creating a scene tile after selecting the scenes collection in the TileSet editor
+
+   Creating a scene tile after selecting the scenes collection in the TileSet editor
+
+Select this scene slot in the right column, then use **Quick Load** (or
+**Load**) to load the scene file containing the particles:
+
+.. figure:: img/using_tilesets_recreate_tiles_automatically.webp
+   :align: center
+   :alt: Creating a scene slot, then loading a scene file into it in the TileSet editor
+
+   Creating a scene slot, then loading a scene file into it in the TileSet editor
+
+You now have a scene tile in your TileSet. Once you switch to the TileMap
+editor, you'll be able to select it from the scenes collection and paint it like
+any other tile.
+
+Merging several atlases into a single atlas
+-------------------------------------------
+
+Using multiple atlases within a single TileSet resource can sometimes be useful,
+but it can also be cumbersome in certain situations (especially if you're using
+one image per tile). Godot allows you to merge several atlases into a single
+atlas for easier organization.
+
+To do so, you must have more than one atlas created in the TileSet resource.
+Use the "three vertical dots" menu button located at the bottom of the list of
+atlases, then choose **Open Atlas Merging Tool**:
+
+.. figure:: img/using_tilesets_open_atlas_merging_tool.webp
+   :align: center
+   :alt: Opening the atlas merging tool after creating multiple atlases
+
+   Opening the atlas merging tool after creating multiple atlases
+
+This will open a dialog, in which you can select several atlases by holding
+:kbd:`Shift` or :kbd:`Ctrl` then clicking on multiple elements:
+
+.. figure:: img/using_tilesets_atlas_merging_tool_dialog.webp
+   :align: center
+   :alt: Using the atlas merging tool dialog
+
+   Using the atlas merging tool dialog
+
+Choose **Merge** to merge the selected atlases into a single atlas image (which
+translates to a single atlas within the TileSet). The unmerged atlases will be
+removed within the TileSet, but *the original tilesheet images will be kept on
+the filesystem*. If you don't want the unmerged atlases to be removed from the
+TileSet resource, choose **Merge (Keep Original Atlases)** instead.
+
+.. tip::
+
+    TileSet features a system of *tile proxies*. Tile proxies are a mapping
+    table that allows notifying the TileMap using a given TileSet that a given
+    set of tile identifiers should be replaced by another one.
+
+    Tile proxies are automatically set up when merging different atlases, but
+    they can also be set manually thanks to the **Manage Tile Proxies** dialog
+    you can access using the "three vertical dots" menu mentioned above.
+
+    Manually creating tile proxies may be useful when you changed an atlas ID or
+    want to replace all tiles from an atlas by the ones from another atlas. Note
+    that when editing a TileMap, you can replace all cells by their
+    corresponding mapped value.
+
+Adding collision, navigation and occlusion to the TileSet
+---------------------------------------------------------
+
+We've now successfully created a basic TileSet. We could start using in the
+TileMap node now, but it currently lacks any form of collision detection.
+This means the player and other objects could walk straight through the floor or
+walls.
+
+If you use :ref:`2D navigation <doc_navigation_overview_2d>`, you'll also need
+to define navigation polygons for tiles to generate a navigation mesh that
+agents can use for pathfinding.
+
+Lastly, if you use :ref:`doc_2d_lights_and_shadows` or GPUParticles2D, you may
+also want your TileSet to be able to cast shadows and collide with particles.
+This requires defining occluder polygons for "solid" tiles on the TileSet.
+
+To be able to define collision, navigation and occlusion shapes for each tile,
+you will need to create a physics, navigation or occlusion layer for the TileSet
+resource first. To do so, select the TileMap node, click the TileSet property
+value in the inspector to edit it then unfold **Physics Layers** and choose
+**Add Element**:
+
+.. figure:: img/using_tilesets_create_physics_layer.webp
+   :align: center
+   :alt: Creating a physics layer in the TileSet resource inspector (within the TileMap node)
+
+   Creating a physics layer in the TileSet resource inspector (within the TileMap node)
+
+If you also need navigation support, now is a good time to create a navigation layer:
+
+.. figure:: img/using_tilesets_create_navigation_layer.webp
+   :align: center
+   :alt: Creating a navigation layer in the TileSet resource inspector (within the TileMap node)
+
+   Creating a navigation layer in the TileSet resource inspector (within the TileMap node)
+
+If you need support for light polygon occluders, now is a good time to create an occlusion layer:
+
+.. figure:: img/using_tilesets_create_occlusion_layer.webp
+   :align: center
+   :alt: Creating an occlusion layer in the TileSet resource inspector (within the TileMap node)
+
+   Creating an occlusion layer in the TileSet resource inspector (within the TileMap node)
+
+.. note::
+
+    Future steps in this tutorial are tailored to creating collision polygons,
+    but the procedure for navigation and occlusion is very similar.
+    Their respective polygon editors behave in the same way, so these steps are
+    not repeated for brevity.
+
+    The only caveat is that the tile's occlusion polygon property is part of a
+    **Rendering** subsection in the atlas inspector. Make sure to unfold this
+    section so you can edit the polygon.
+
+After creating a physics layer, you have access to the **Physics Layer** section
+in the TileSet atlas inspector:
+
+.. figure:: img/using_tilesets_selecting_collision_editor.webp
+   :align: center
+   :alt: Opening the collision editor while in Select mode
+
+   Opening the collision editor while in Select mode
+
+You can quickly create a rectangle collision shape by pressing :kbd:`F` while
+the TileSet editor is focused. If the keyboard shortcut doesn't work, try
+clicking in the empty area around the polygon editor to focus it:
+
+.. figure:: img/using_tilesets_using_default_rectangle_collision.webp
+   :align: center
+   :alt: Using default rectangle collision shape by pressing :kbd:`F`
+
+   Using default rectangle collision shape by pressing :kbd:`F`
+
+In this tile collision editor, you have access to all the 2D polygon editing tools:
+
+- Use the toolbar above the polygon to toggle between creating a new polygon,
+  editing an existing polygon and removing points on the polygon. The "three vertical dots"
+  menu button offers additional options, such as rotating and flipping the polygon.
+- Create new points by clicking and dragging a line between two points.
+- Remove a point by right-clicking it (or using the Remove tool described above
+  and left-clicking).
+- Pan in the editor by middle-clicking or right-clicking. (Right-click panning
+  can only be used in areas where there is no point nearby.)
+
+You can use the default rectangle shape to quickly create a triangle-shaped
+collision shape by removing one of the points:
+
+.. figure:: img/using_tilesets_creating_triangle_collision.webp
+   :align: center
+   :alt: Creating a triangle collision shape by right-clicking one of the corners to remove it
+
+   Creating a triangle collision shape by right-clicking one of the corners to remove it
+
+You can also use the rectangle as a base for more complex shapes by adding more points:
+
+.. figure:: img/using_tilesets_drawing_custom_collision.webp
+   :align: center
+   :alt: Drawing a custom collision for a complex tile shape
+
+   Drawing a custom collision for a complex tile shape
+
+.. tip::
+
+    If you have a large tileset, specifying the collision for each tile
+    individually could take a lot of time. This is especially true as TileMaps
+    tend to have many tiles with common collision patterns (such as solid blocks
+    or 45-degree slopes). To apply a similar collision shape to several tiles
+    quickly, use functionality to
+    :ref:`assign properties to multiple tiles at once <doc_using_tilemaps_assigning_properties_to_multiple_tiles>`.
+
+Assigning custom metadata to the TileSet's tiles
+------------------------------------------------
+
+You can assign custom data on a per-tile basis using *custom data layers*.
+This can be useful to store information specific to your game, such as the damage
+that a tile should deal when the player touches it, or whether a tile can be
+destroyed using a weapon.
+
+The data is associated with the tile in the TileSet: all instances of the placed
+tile will use the same custom data. If you need to create a variant of a tile
+that has different custom data, this can be done by :ref:`creating an
+alternative tile <doc_using_tilesets_creating_alternative_tiles>` and changing
+the custom data for the alternative tile only.
+
+.. figure:: img/using_tilesets_create_custom_data_layer.webp
+   :align: center
+   :alt: Creating a custom data layer in the TileSet resource inspector (within the TileMap node)
+
+   Creating a custom data layer in the TileSet resource inspector (within the TileMap node)
+
+.. figure:: img/using_tilesets_custom_data_layers_example.webp
+   :align: center
+   :alt: Example of configured custom data layers with game-specific properties
+
+   Example of configured custom data layers with game-specific properties
+
+You can reorder custom data without breaking existing metadata: the TileSet
+editor will update automatically after reordering custom data properties.
+
+Note that in the editor, property names do not appear (only their index, which
+matches the order in which they are defined). For example, with the custom data
+layers example shown above, we're assigning a tile to have the
+``damage_per_second`` metadata set to ``25`` and the ``destructible`` metadata
+to ``false``:
+
+.. figure:: img/using_tilesets_edit_custom_data.webp
+   :align: center
+   :alt: Editing custom data in the TileSet editor while in Select mode
+
+   Editing custom data in the TileSet editor while in Select mode
+
+:ref:`Tile property painting <doc_using_tilemaps_using_tile_property_painting>`
+can also be used for custom data:
+
+.. figure:: img/using_tilesets_edit_custom_data.webp
+   :align: center
+   :alt: Assigning custom data in the TileSet editor using tile property painting
+
+   Assigning custom data in the TileSet editor using tile property painting
+
+.. _doc_using_tilesets_creating_terrain_sets:
+
+Creating terrain sets (autotiling)
+----------------------------------
+
+.. note::
+
+    This functionality was implemented in a different form as *autotiling* in Godot 3.x.
+    Terrains are essentially a more powerful replacement of autotiles. Unlike
+    autotiles, terrains can support transitions from one terrain to another, as
+    a tile may define several terrains at once.
+
+    Unlike before, where autotiles were a specific kind of tiles, terrains are
+    only a set of properties assigned to atlas tiles. These properties are then
+    used by a dedicated TileMap painting mode that selects tiles featuring
+    terrain data in a smart way. This means any terrain tile can be either
+    painted as terrain or as a single tile, like any other.
+
+A "polished" tileset generally features variations that you should use on
+corners or edges of platforms, floors, etc. While these can be placed manually,
+this quickly becomes tedious. Handling this situation with procedurally
+generated levels can also be difficult and require a lot of code.
+
+Godot offers *terrains* to perform this kind of tile connections automatically.
+This allows you to have the "correct" tile variants automatically used.
+
+Terrains are grouped into terrain sets. Each terrain set is assigned a mode from
+**Match Corners and Sides**, **Match Corners** and **Match sides**. They define how
+terrains are matched to each other in a terrain set.
+
+.. note::
+
+    The above modes correspond to the previous bitmask modes autotiles used in
+    Godot 3.x: 2×2, 3×3 or 3×3 minimal. This is also similar to what
+    the `Tiled <https://www.mapeditor.org/>`__ editor features.
+
+Select the TileMap node, go to the inspector and create a new terrain set within the TileSet *resource*:
+
+.. figure:: img/using_tilesets_create_terrain_set.webp
+   :align: center
+   :alt: Creating a terrain set in the TileSet resource inspector (within the TileMap node)
+
+   Creating a terrain set in the TileSet resource inspector (within the TileMap node)
+
+After creating a terrain set, you **must** create one or more terrains *within* the terrain set:
+
+.. figure:: img/using_tilesets_create_terrain.webp
+   :align: center
+   :alt: Creating a terrain within the terrain set
+
+   Creating a terrain within the terrain set
+
+In the TileSet editor, switch to Select mode and click a tile. In the middle
+column, unfold the **Terrains** section then assign a terrain set ID and a
+terrain ID for the tile. ``-1`` means "no terrain set" or "no terrain", which
+means you must set **Terrain Set** to ``0`` or greater before you can set
+**Terrain** to ``0`` or greater.
+
+.. note::
+
+   Terrain set IDs and terrain IDs are independent from each other. They also
+   start from ``0``, not ``1``.
+
+.. figure:: img/using_tilesets_configure_terrain_on_tile.webp
+   :align: center
+   :alt: Configuring terrain on a single tile in the TileSet editor's Select mode
+
+   Configuring terrain on a single tile in the TileSet editor's Select mode
+
+After doing so, you can now configure the **Terrain Peering Bits** section which
+becomes visible in the middle column. The peering bits determine which tile will
+be placed depending on neighboring tiles. ``-1`` is a special value which refers
+to empty space.
+
+For example, if a tile has all its bits set to ``0`` or greater, it will only
+appear if *all* 8 neighboring tiles are using a tile with the same terrain ID.
+is present on corners or sides. If a tile has its bits set to ``0`` or greater,
+but the top-left, top and top-right bits are set to ``-1``, it will only appear
+if there is empty space on top of it (including diagonally).
+
+.. figure:: img/using_tilesets_configure_terrain_peering_bits.webp
+   :align: center
+   :alt: Configuring terrain peering bits on a single tile in the TileSet editor's Select mode
+
+   Configuring terrain peering bits on a single tile in the TileSet editor's Select mode
+
+An example configuration for a full tilesheet may look as follows:
+
+.. figure:: img/using_tilesets_terrain_example_tilesheet.webp
+   :align: center
+   :alt: Example full tilesheet for a sidescrolling game
+
+   Example full tilesheet for a sidescrolling game
+
+.. figure:: img/using_tilesets_terrain_example_tilesheet_configuration.webp
+   :align: center
+   :alt: Example full tilesheet for a sidescrolling game with terrain peering bits visible
+
+   Example full tilesheet for a sidescrolling game with terrain peering bits visible
+
+.. _doc_using_tilemaps_assigning_properties_to_multiple_tiles:
+
+Assigning properties to multiple tiles at once
+----------------------------------------------c
+
+There are two ways to assign properties to multiple tiles at once.
+Depending on your use cases, one method may be faster than the other:
+
+Using multiple tile selection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to configure various properties on several times at once,
+choose the **Select** mode at the top of the TileSet editor:
+
+After doing this, you can select multiple tiles on the right column by holding
+:kbd:`Shift` then clicking on tiles. You can also perform rectangle selection by
+holding down the left mouse button then dragging the mouse. Lastly, you can
+deselect tiles that were already selected (without affecting the rest of the
+selection) by holding :kbd:`Shift` then clicking on a selected tile.
+
+You can then assign properties using the inspector in the middle column of the
+TileSet editor. Only properties that you change here will be applied to all
+selected tiles. Like in the editor's inspector, properties that differ on
+selected tiles will remain different until you edit them.
+
+With numerical and color properties, you will also see a preview of the
+property's value on all tiles in the atlas after editing a property:
+
+.. figure:: img/using_tilesets_select_and_set_tile_properties.webp
+   :align: center
+   :alt: Selecting multiple tiles using the Select mode, then applying properties
+
+   Selecting multiple tiles using the Select mode, then applying properties
+
+.. _doc_using_tilemaps_using_tile_property_painting:
+
+Using tile property painting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to apply a single property to several tiles at once,
+you can use the *property painting* mode for this purpose.
+
+Configure a property to be painted in the middle column, then
+click on tiles (or hold down the left mouse button) in the right column
+to "paint" properties onto tiles.
+
+.. figure:: img/using_tilesets_paint_tile_properties.webp
+   :align: center
+   :alt: Painting tile properties using the TileSet editor
+
+   Painting tile properties using the TileSet editor
+
+Tile property painting is especially useful with properties that are
+time-consuming to set manually, such as collision shapes:
+
+.. figure:: img/using_tilesets_paint_tile_properties_collision.webp
+   :align: center
+   :alt: Painting a collision polygon, then left-clicking tiles to apply it
+
+   Painting a collision polygon, then left-clicking tiles to apply it
+
+.. _doc_using_tilesets_creating_alternative_tiles:
+
+Creating alternative tiles
+--------------------------
+
+Sometimes, you want to use a single tile image (found only once within the
+atlas), but configured in different ways. For example, you may want to use the
+same tile image, but rotated, flipped, or modulated with a different color. This
+can be done using *alternative tiles*.
+
+To create an alternative tile, right-click a base tile in the atlas displayed by
+the TileSet editor, then choose **Create an Alternative Tile**:
+
+.. figure:: img/using_tilesets_create_alternative_tile.webp
+   :align: center
+   :alt: Creating an alternative tile by right-clicking a base tile in the TileSet editor
+
+   Creating an alternative tile by right-clicking a base tile in the TileSet editor
+
+If currently in Select mode, the alternative tile will already be selected
+for editing. If not currently in Select mode, you can still create alternative
+tiles, but you will need to switch to Select mode and select the alternative
+tile to edit it.
+
+If you don't see the alternative tile, pan over to the right of the atlas image,
+as alternative tiles always appear on the right of base tiles of a given atlas
+in the TileSet editor:
+
+.. figure:: img/using_tilesets_configure_alternative_tile.webp
+   :align: center
+   :alt: Configuring an alternative tile after clicking it in the TileSet editor
+
+   Configuring an alternative tile after clicking it in the TileSet editor
+
+After selecting an alternative tile, you can change any properties using the
+middle column like you would on a base tile. However, the list of exposed
+properties is different compared to base tiles:
+
+- **Alternative ID:** The unique numerical identifier for this alternative tile.
+  Changing it will break existing TileMaps, so be careful! This ID also controls
+  the sorting in the list of alternative tiles displayed in the editor.
+- **Rendering > Flip H:** If ``true``, the tile is horizontally flipped.
+- **Rendering > Flip V:** If ``true``, the tile is vertically flipped.
+- **Rendering > Transpose:** If ``true``, the tile is rotated 90 degrees
+  counter-clockwise. Combine this with **Flip H** and/or **Flip V** to perform
+  180-degree or 270-degree rotation.
+- **Rendering > Texture Origin:** The origin to use for drawing the tile. This
+  can be used to visually offset the tile compared to the base tile.
+- **Rendering > Modulate:** The color multiplier to use when rendering the tile.
+- **Rendering > Material:** The material to use for this tile. This can be used
+  to apply a different blend mode or custom shaders to a single tile.
+- **Z Index:** The sorting order for this tile. Higher values will make the tile
+  render in front of others on the same layer.
+- **Y Sort Origin:** The vertical offset to use for tile sorting based on its Y
+  coordinate (in pixels). This allows using layers as if they were on different
+  height for top-down games. Adjusting this can help alleviate issues with
+  sorting certain tiles. Only effective if **Y Sort Enabled** is ``true`` on
+  the TileMap layer the tile is placed on.
+
+You can create an additional alternative tile variant by clicking the large "+"
+icon next to the alternative tile. This is equivalent to selecting the base tile
+and right-clicking it to choose **Create an Alternative Tile** again.
+
+.. note::
+
+    When creating an alternative tile, none of the properties from the base tile
+    are inherited. You must set properties again on the alternative tile if you
+    wish those to be identical on the base tile and the alternative tile.