diff --git a/tutorials/2d/2d_lights_and_shadows.rst b/tutorials/2d/2d_lights_and_shadows.rst index e7f4d193a..848c00d8c 100644 --- a/tutorials/2d/2d_lights_and_shadows.rst +++ b/tutorials/2d/2d_lights_and_shadows.rst @@ -38,7 +38,7 @@ There are several nodes involved in a complete 2D lighting setup: - :ref:`PointLight2D ` (for omnidirectional or spot lights) - :ref:`DirectionalLight2D ` (for sunlight or moonlight) - :ref:`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 ` 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 ` 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 ` and their direction is based on the center of the diff --git a/tutorials/2d/img/using_tilemaps_create_layers.webp b/tutorials/2d/img/using_tilemaps_create_layers.webp deleted file mode 100644 index c56da0088..000000000 Binary files a/tutorials/2d/img/using_tilemaps_create_layers.webp and /dev/null differ diff --git a/tutorials/2d/img/using_tilemaps_save_tileset_to_resource.webp b/tutorials/2d/img/using_tilemaps_save_tileset_to_resource.webp index 46f3d2590..33b8bdf77 100644 Binary files a/tutorials/2d/img/using_tilemaps_save_tileset_to_resource.webp and b/tutorials/2d/img/using_tilemaps_save_tileset_to_resource.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_custom_data_layer.webp b/tutorials/2d/img/using_tilesets_create_custom_data_layer.webp index ffb812617..81754b72c 100644 Binary files a/tutorials/2d/img/using_tilesets_create_custom_data_layer.webp and b/tutorials/2d/img/using_tilesets_create_custom_data_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_navigation_layer.webp b/tutorials/2d/img/using_tilesets_create_navigation_layer.webp index 424cae015..f359d57ea 100644 Binary files a/tutorials/2d/img/using_tilesets_create_navigation_layer.webp and b/tutorials/2d/img/using_tilesets_create_navigation_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_new_tileset.webp b/tutorials/2d/img/using_tilesets_create_new_tileset.webp index a757ded82..ef325ba1f 100644 Binary files a/tutorials/2d/img/using_tilesets_create_new_tileset.webp and b/tutorials/2d/img/using_tilesets_create_new_tileset.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_occlusion_layer.webp b/tutorials/2d/img/using_tilesets_create_occlusion_layer.webp index 9840bc544..c6d740ad7 100644 Binary files a/tutorials/2d/img/using_tilesets_create_occlusion_layer.webp and b/tutorials/2d/img/using_tilesets_create_occlusion_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_physics_layer.webp b/tutorials/2d/img/using_tilesets_create_physics_layer.webp index 9b4175fb4..f667e48c5 100644 Binary files a/tutorials/2d/img/using_tilesets_create_physics_layer.webp and b/tutorials/2d/img/using_tilesets_create_physics_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_terrain_set.webp b/tutorials/2d/img/using_tilesets_create_terrain_set.webp index 3270f0bb1..fb99233d9 100644 Binary files a/tutorials/2d/img/using_tilesets_create_terrain_set.webp and b/tutorials/2d/img/using_tilesets_create_terrain_set.webp differ diff --git a/tutorials/2d/img/using_tilesets_specify_size_then_edit.webp b/tutorials/2d/img/using_tilesets_specify_size_then_edit.webp index 7da39c8ca..fc854fe87 100644 Binary files a/tutorials/2d/img/using_tilesets_specify_size_then_edit.webp and b/tutorials/2d/img/using_tilesets_specify_size_then_edit.webp differ diff --git a/tutorials/2d/using_tilemaps.rst b/tutorials/2d/using_tilemaps.rst index 0cfba9054..0ceab4215 100644 --- a/tutorials/2d/using_tilemaps.rst +++ b/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 ` nodes to design your levels. +benefits to using :ref:`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 ` 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. diff --git a/tutorials/2d/using_tilesets.rst b/tutorials/2d/using_tilesets.rst index 843fc5af5..8dbc0e392 100644 --- a/tutorials/2d/using_tilesets.rst +++ b/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 ` nodes to design your levels. -First, they let you draw a layout by "painting" tiles onto a grid, +benefits to using :ref:`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 ` 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 `. @@ -43,13 +43,13 @@ We'll use this particular *tilesheet* from the set: Tilesheet with 64×64 tiles. Credit: `Kenney `__ -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 `__ 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 diff --git a/tutorials/best_practices/data_preferences.rst b/tutorials/best_practices/data_preferences.rst index a5b3b4c33..7bd718267 100644 --- a/tutorials/best_practices/data_preferences.rst +++ b/tutorials/best_practices/data_preferences.rst @@ -329,7 +329,7 @@ the other :ref:`Node ` objects discussed here. One might create a :ref:`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 ` and integrate it with a -:ref:`TileMap ` for many auto-animating backgrounds that +:ref:`TileMapLayer ` for many auto-animating backgrounds that all render in a single batched draw call. The AnimatedSprite2D node, in combination with the diff --git a/tutorials/shaders/your_first_shader/your_first_2d_shader.rst b/tutorials/shaders/your_first_shader/your_first_2d_shader.rst index 2d5f5c292..ff84bbde2 100644 --- a/tutorials/shaders/your_first_shader/your_first_2d_shader.rst +++ b/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 ` have a material property. This includes all :ref:`GUI elements `, :ref:`Sprite2Ds -`, :ref:`TileMaps `, :ref:`MeshInstance2Ds +`, :ref:`TileMapLayers `, :ref:`MeshInstance2Ds ` 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.