Merge pull request #9681 from skyace65/TileMapLayer

Update docs for new TileMapLayer node

tutorials/2d/2d_lights_and_shadows.rst

@@ -38,7 +38,7 @@ There are several nodes involved in a complete 2D lighting setup:
 - :ref:`PointLight2D <class_PointLight2D>` (for omnidirectional or spot lights)
 - :ref:`DirectionalLight2D <class_DirectionalLight2D>` (for sunlight or moonlight)
 - :ref:`LightOccluder2D <class_LightOccluder2D>` (for light shadow casters)
-- Other 2D nodes that receive lighting, such as Sprite2D or TileMap.
+- Other 2D nodes that receive lighting, such as Sprite2D or TileMapLayer.
 
 :ref:`CanvasModulate <class_CanvasModulate>` is used to darken the scene by
 specifying a color that will act as the base "ambient" color. This is the final
@@ -55,7 +55,7 @@ to simulate lighting.
 
 :ref:`LightOccluder2Ds <class_LightOccluder2D>` are used to tell the shader
 which parts of the scene cast shadows. These occluders can be placed as
-independent nodes or can be part of a TileMap node.
+independent nodes or can be part of a TileMapLayer node.
 
 The shadows appear only on areas covered by the :ref:`PointLight2D
 <class_PointLight2D>` and their direction is based on the center of the

tutorials/2d/using_tilemaps.rst

@@ -13,7 +13,7 @@ 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.
+benefits to using :ref:`TileMapLayer <class_TileMapLayer>` nodes to design your levels.
 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
@@ -21,15 +21,15 @@ optimized for drawing large numbers of tiles. Finally, you can add collision,
 occlusion, and navigation shapes to tiles, adding greater functionality to
 the TileMap.
 
-Specifying the TileSet in the TileMap
--------------------------------------
+Specifying the TileSet in the TileMapLayer
+------------------------------------------
 
 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
+have a TileSet resource that is built-in to the TileMapLayer node. This is good for
 prototyping, but in a real world project, you will generally have multiple
 levels reusing the same tileset.
 
-The recommended way to reuse the same TileSet in several TileMap nodes is to save
+The recommended way to reuse the same TileSet in several TileMapLayer nodes is to save
 the TileSet to an external resource. To do so, click the dropdown next to the TileSet
 resource and choose **Save**:
 
@@ -39,48 +39,51 @@ resource and choose **Save**:
 
    Saving the built-in TileSet resource to an external resource file
 
-Creating TileMap layers
------------------------
+Multiple TileMaplayers and settings
+-----------------------------------
 
-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.
+When working with tilemaps it's generally advised that you use multiple TileMapLayer
+nodes when appropriate. Using multiple layers can be advantageous, 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.
 
-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:
+Each TileMapLayer node has several properties you can adjust:
 
-.. figure:: img/using_tilemaps_create_layers.webp
-   :align: center
-   :alt: Creating layers in a TileMap node (example with "background" and "foreground")
-
-   Creating layers in a TileMap node (example with "background" and "foreground")
-
-Each layer has several properties you can adjust:
-
-- **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.
+- **TileSet** The tileset used by the TileMapLayer node.
 
-You can reorder layers by drag-and-dropping the "three horizontal bars" icon on
-the left of the entries in the **Layers** section.
+Rendering
+^^^^^^^^^
+
+- **Y Sort Origin:** The vertical offset to use for Y-sorting on each tile (in pixels).
+  Only effective if **Y Sort Enabled** under CanvasItem settings is ``true``.
+- **X Draw Order Reversed** Reverses the order tiles are drawn on the X axis. Requires
+  that **Y Sort Enabled** under CanvasItem settings is ``true``.
+- **Rendering Quadrant Size** A quadrant is a group of tiles drawn together on a single
+  CanvasItem for optimization purposes. This setting defines the length of a square's
+  side in the map's coordinate system. The quadrant size does not apply to a Y sorted
+  TileMapLayer since tiles are grouped by Y position in that case.
+
+Physics
+^^^^^^^
+- **Collision Enabled** Enables or disables collision.
+- **Use Kinematic Bodies** When true TileMapLayer collision shapes will be instantiated
+  as kinematic bodies.
+- **Collision Visibility Mode** Whether or not the TileMapLayer's collision shapes are
+  visible. If set to default, then it depends on the show collision debug settings.
+
+Navigation
+^^^^^^^^^^
+
+- **Navigation Enabled** Whether or not navigation regions are enabled.
+- **Navigation Visible** Whether or not the TileMapLayer's navigation meshes are
+  visible. If set to default then it depends on the show navigation debug settings.
+
+You can reorder layers by drag-and-dropping their node in the Scene tab. You can
+also switch between which TileMapLayer node you're working on by using the buttons
+in the top right corner of the TileMap editor.
 
 .. note::
 
@@ -91,7 +94,7 @@ the left of the entries in the **Layers** section.
 Opening the TileMap editor
 --------------------------
 
-Select the TileMap node, then open the TileMap panel at the bottom
+Select the TileMapLayer node, then open the TileMap panel at the bottom
 of the editor:
 
 .. figure:: img/using_tilemaps_open_tilemap_editor.webp
@@ -386,7 +389,7 @@ 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
+    TileSet resource. This allows reusing patterns in different TileMapLayer nodes
     after loading a TileSet resource saved to an external file.
 
 Handling tile connections automatically using terrains
@@ -400,7 +403,7 @@ 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.
+  TileMapLayer.
 - **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
@@ -454,5 +457,5 @@ the new tile's appearance.
 
 .. note::
 
-    Missing tile placeholders may not be visible until you select the TileMap
+    Missing tile placeholders may not be visible until you select the TileMapLayer
     node and open the TileMap editor.

tutorials/2d/using_tilesets.rst

@@ -7,16 +7,16 @@ 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,
+benefits to using :ref:`TileMapLayer <class_TileMapLayer>` 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
+To use TileMapLayer nodes, you will need to create a TileSet first. A TileSet is a
+collection of tiles that can be placed in a TileMapLayer node. After creating a
 TileSet, you will be able to place them :ref:`using the TileMap editor
 <doc_using_tilemaps>`.
 
@@ -43,13 +43,13 @@ We'll use this particular *tilesheet* from the set:
 
    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:
+Create a new **TileMapLayer** 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
+   :alt: Creating a new TileSet resource within the TileMapLayer node
 
-   Creating a new TileSet resource within the TileMap node
+   Creating a new TileSet resource within the TileMapLayer 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,
@@ -70,7 +70,7 @@ Set the tile size to 64×64 in the inspector 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
+determine which tiles from the tilesheet can be added to a TileMapLayer 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 and drag the
@@ -135,7 +135,7 @@ The following properties can be adjusted on the atlas:
   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
+  cases, this should match the tile size defined in the TileMapLayer 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.
@@ -174,7 +174,7 @@ sounds), particle effects, and more.
 
 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
+TileMapLayer), then switch to the scene containing the TileMapLayer node. Open the TileSet
 editor, and create a new **Scenes Collection** in the left column:
 
 .. figure:: img/using_tilesets_creating_scene_collection.webp
@@ -258,7 +258,7 @@ 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.
+TileMapLayer 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.
 
@@ -272,31 +272,31 @@ 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
+resource first. To do so, select the TileMapLayer 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)
+   :alt: Creating a physics layer in the TileSet resource inspector (within the TileMapLayer node)
 
-   Creating a physics layer in the TileSet resource inspector (within the TileMap node)
+   Creating a physics layer in the TileSet resource inspector (within the TileMapLayer 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)
+   :alt: Creating a navigation layer in the TileSet resource inspector (within the TileMapLayer node)
 
-   Creating a navigation layer in the TileSet resource inspector (within the TileMap node)
+   Creating a navigation layer in the TileSet resource inspector (within the TileMapLayer 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)
+   :alt: Creating an occlusion layer in the TileSet resource inspector (within the TileMapLayer node)
 
-   Creating an occlusion layer in the TileSet resource inspector (within the TileMap node)
+   Creating an occlusion layer in the TileSet resource inspector (within the TileMapLayer node)
 
 .. note::
 
@@ -381,9 +381,9 @@ 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)
+   :alt: Creating a custom data layer in the TileSet resource inspector (within the TileMapLayer node)
 
-   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 TileMapLayer node)
 
 .. figure:: img/using_tilesets_custom_data_layers_example.webp
    :align: center
@@ -451,13 +451,13 @@ terrains are matched to each other in a terrain set.
     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*:
+Select the TileMapLayer 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)
+   :alt: Creating a terrain set in the TileSet resource inspector (within the TileMapLayer node)
 
-   Creating a terrain set in the TileSet resource inspector (within the TileMap node)
+   Creating a terrain set in the TileSet resource inspector (within the TileMapLayer node)
 
 After creating a terrain set, you **must** create one or more terrains *within* the terrain set:
 
@@ -643,7 +643,7 @@ properties is different compared to base tiles:
   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.
+  the TileMapLayer node under **CanvasItem > Ordering**
 
 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

tutorials/best_practices/data_preferences.rst

@@ -329,7 +329,7 @@ the other :ref:`Node <class_Node>` objects discussed here. One might create
 a :ref:`Sprite2D <class_Sprite2D>` node that uses AnimatedTexture as its texture.
 Or (something the others can't do) one could add AnimatedTextures as tiles
 in a :ref:`TileSet <class_TileSet>` and integrate it with a
-:ref:`TileMap <class_TileMap>` for many auto-animating backgrounds that
+:ref:`TileMapLayer <class_TileMapLayer>` for many auto-animating backgrounds that
 all render in a single batched draw call.
 
 The AnimatedSprite2D node, in combination with the

tutorials/shaders/your_first_shader/your_first_2d_shader.rst

@@ -33,7 +33,7 @@ material, the material must be attached to each object.
 
 All objects derived from a :ref:`CanvasItem <class_CanvasItem>` have a material
 property. This includes all :ref:`GUI elements <class_Control>`, :ref:`Sprite2Ds
-<class_Sprite2D>`, :ref:`TileMaps <class_Tilemap>`, :ref:`MeshInstance2Ds
+<class_Sprite2D>`, :ref:`TileMapLayers <class_TileMapLayer>`, :ref:`MeshInstance2Ds
 <class_MeshInstance2D>` etc. They also have an option to inherit their parent's
 material. This can be useful if you have a large number of nodes that you want
 to use the same material.