diff --git a/tutorials/2d/img/tile_lock.png b/tutorials/2d/img/tile_lock.png deleted file mode 100644 index a8011614bb0..00000000000 Binary files a/tutorials/2d/img/tile_lock.png and /dev/null differ diff --git a/tutorials/2d/img/tilemap_add_tile.png b/tutorials/2d/img/tilemap_add_tile.png deleted file mode 100644 index fcb03a01c8c..00000000000 Binary files a/tutorials/2d/img/tilemap_add_tile.png and /dev/null differ diff --git a/tutorials/2d/img/tilemap_add_tileset.png b/tutorials/2d/img/tilemap_add_tileset.png deleted file mode 100644 index 9ea8e7156c2..00000000000 Binary files a/tutorials/2d/img/tilemap_add_tileset.png and /dev/null differ diff --git a/tutorials/2d/img/tilemap_draw.png b/tutorials/2d/img/tilemap_draw.png deleted file mode 100644 index 72fea6c88f2..00000000000 Binary files a/tutorials/2d/img/tilemap_draw.png and /dev/null differ diff --git a/tutorials/2d/img/tilemap_menu.png b/tutorials/2d/img/tilemap_menu.png deleted file mode 100644 index 1115a0ab509..00000000000 Binary files a/tutorials/2d/img/tilemap_menu.png and /dev/null differ diff --git a/tutorials/2d/img/tilemap_mode.png b/tutorials/2d/img/tilemap_mode.png deleted file mode 100644 index 0022c1210fa..00000000000 Binary files a/tutorials/2d/img/tilemap_mode.png and /dev/null differ diff --git a/tutorials/2d/img/tilemap_size.png b/tutorials/2d/img/tilemap_size.png deleted file mode 100644 index e203d5fca4c..00000000000 Binary files a/tutorials/2d/img/tilemap_size.png and /dev/null differ diff --git a/tutorials/2d/img/tilemap_tool.png b/tutorials/2d/img/tilemap_tool.png deleted file mode 100644 index 14bdd2113f3..00000000000 Binary files a/tutorials/2d/img/tilemap_tool.png and /dev/null differ diff --git a/tutorials/2d/img/tileset_add_collision.png b/tutorials/2d/img/tileset_add_collision.png deleted file mode 100644 index 94d601beb5e..00000000000 Binary files a/tutorials/2d/img/tileset_add_collision.png and /dev/null differ diff --git a/tutorials/2d/img/tileset_atlas.png b/tutorials/2d/img/tileset_atlas.png deleted file mode 100644 index 0b43e464ba8..00000000000 Binary files a/tutorials/2d/img/tileset_atlas.png and /dev/null differ diff --git a/tutorials/2d/img/tileset_draw_atlas.png b/tutorials/2d/img/tileset_draw_atlas.png deleted file mode 100644 index fcb3976adbb..00000000000 Binary files a/tutorials/2d/img/tileset_draw_atlas.png and /dev/null differ diff --git a/tutorials/2d/img/tileset_snap.png b/tutorials/2d/img/tileset_snap.png deleted file mode 100644 index 16420902fc9..00000000000 Binary files a/tutorials/2d/img/tileset_snap.png and /dev/null differ diff --git a/tutorials/2d/img/tilesheet.png b/tutorials/2d/img/tilesheet.png deleted file mode 100755 index 0a2ccbe226f..00000000000 Binary files a/tutorials/2d/img/tilesheet.png and /dev/null differ diff --git a/tutorials/2d/img/using_tilemaps_bucket_fill.webp b/tutorials/2d/img/using_tilemaps_bucket_fill.webp new file mode 100644 index 00000000000..ec20d1c4d91 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_bucket_fill.webp differ diff --git a/tutorials/2d/img/using_tilemaps_bucket_fill_scatter.webp b/tutorials/2d/img/using_tilemaps_bucket_fill_scatter.webp new file mode 100644 index 00000000000..405c4be9a49 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_bucket_fill_scatter.webp differ diff --git a/tutorials/2d/img/using_tilemaps_create_layers.webp b/tutorials/2d/img/using_tilemaps_create_layers.webp new file mode 100644 index 00000000000..c56da00886d Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_create_layers.webp differ diff --git a/tutorials/2d/img/using_tilemaps_create_pattern.webp b/tutorials/2d/img/using_tilemaps_create_pattern.webp new file mode 100644 index 00000000000..71337982372 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_create_pattern.webp differ diff --git a/tutorials/2d/img/using_tilemaps_missing_tiles.webp b/tutorials/2d/img/using_tilemaps_missing_tiles.webp new file mode 100644 index 00000000000..ae510412829 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_missing_tiles.webp differ diff --git a/tutorials/2d/img/using_tilemaps_open_tilemap_editor.webp b/tutorials/2d/img/using_tilemaps_open_tilemap_editor.webp new file mode 100644 index 00000000000..244017d8f33 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_open_tilemap_editor.webp differ diff --git a/tutorials/2d/img/using_tilemaps_placing_scene_tiles.webp b/tutorials/2d/img/using_tilemaps_placing_scene_tiles.webp new file mode 100644 index 00000000000..857ffe2b2b2 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_placing_scene_tiles.webp 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 new file mode 100644 index 00000000000..46f3d25904f Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_save_tileset_to_resource.webp differ diff --git a/tutorials/2d/img/using_tilemaps_scatter_tiles.webp b/tutorials/2d/img/using_tilemaps_scatter_tiles.webp new file mode 100644 index 00000000000..da4f1080e39 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_scatter_tiles.webp differ diff --git a/tutorials/2d/img/using_tilemaps_select_layer.webp b/tutorials/2d/img/using_tilemaps_select_layer.webp new file mode 100644 index 00000000000..e66bdf39baa Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_select_layer.webp differ diff --git a/tutorials/2d/img/using_tilemaps_select_multiple_tiles_from_tileset.webp b/tutorials/2d/img/using_tilemaps_select_multiple_tiles_from_tileset.webp new file mode 100644 index 00000000000..c10b49baa30 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_select_multiple_tiles_from_tileset.webp differ diff --git a/tutorials/2d/img/using_tilemaps_select_single_tile_from_tileset.webp b/tutorials/2d/img/using_tilemaps_select_single_tile_from_tileset.webp new file mode 100644 index 00000000000..857ef9d533b Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_select_single_tile_from_tileset.webp differ diff --git a/tutorials/2d/img/using_tilemaps_terrain_paint_specific_tiles.webp b/tutorials/2d/img/using_tilemaps_terrain_paint_specific_tiles.webp new file mode 100644 index 00000000000..5b80dd43c96 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_terrain_paint_specific_tiles.webp differ diff --git a/tutorials/2d/img/using_tilemaps_terrain_select_connect_mode.webp b/tutorials/2d/img/using_tilemaps_terrain_select_connect_mode.webp new file mode 100644 index 00000000000..16fdd6e8da4 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_terrain_select_connect_mode.webp differ diff --git a/tutorials/2d/img/using_tilemaps_terrain_select_path_mode.webp b/tutorials/2d/img/using_tilemaps_terrain_select_path_mode.webp new file mode 100644 index 00000000000..dbbdd71f615 Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_terrain_select_path_mode.webp differ diff --git a/tutorials/2d/img/using_tilemaps_use_alternative_tile.webp b/tutorials/2d/img/using_tilemaps_use_alternative_tile.webp new file mode 100644 index 00000000000..8c176ebe01e Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_use_alternative_tile.webp differ diff --git a/tutorials/2d/img/using_tilemaps_use_pattern.webp b/tutorials/2d/img/using_tilemaps_use_pattern.webp new file mode 100644 index 00000000000..46af11433ea Binary files /dev/null and b/tutorials/2d/img/using_tilemaps_use_pattern.webp differ diff --git a/tutorials/2d/img/using_tilesets_adding_scene_tile.webp b/tutorials/2d/img/using_tilesets_adding_scene_tile.webp new file mode 100644 index 00000000000..309651a4834 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_adding_scene_tile.webp differ diff --git a/tutorials/2d/img/using_tilesets_atlas_merging_tool_dialog.webp b/tutorials/2d/img/using_tilesets_atlas_merging_tool_dialog.webp new file mode 100644 index 00000000000..e5069f1c865 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_atlas_merging_tool_dialog.webp differ diff --git a/tutorials/2d/img/using_tilesets_configure_alternative_tile.webp b/tutorials/2d/img/using_tilesets_configure_alternative_tile.webp new file mode 100644 index 00000000000..8e712b93816 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_configure_alternative_tile.webp differ diff --git a/tutorials/2d/img/using_tilesets_configure_terrain_on_tile.webp b/tutorials/2d/img/using_tilesets_configure_terrain_on_tile.webp new file mode 100644 index 00000000000..aa99a341243 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_configure_terrain_on_tile.webp differ diff --git a/tutorials/2d/img/using_tilesets_configure_terrain_peering_bits.webp b/tutorials/2d/img/using_tilesets_configure_terrain_peering_bits.webp new file mode 100644 index 00000000000..35bf2832b62 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_configure_terrain_peering_bits.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_alternative_tile.webp b/tutorials/2d/img/using_tilesets_create_alternative_tile.webp new file mode 100644 index 00000000000..d7e8ef45499 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_create_alternative_tile.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 new file mode 100644 index 00000000000..ffb8126175f Binary files /dev/null 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 new file mode 100644 index 00000000000..424cae015d0 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_create_navigation_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_new_atlas.webp b/tutorials/2d/img/using_tilesets_create_new_atlas.webp new file mode 100644 index 00000000000..46fa98ac3f5 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_create_new_atlas.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_new_tileset.webp b/tutorials/2d/img/using_tilesets_create_new_tileset.webp new file mode 100644 index 00000000000..a757ded8244 Binary files /dev/null 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 new file mode 100644 index 00000000000..9840bc544e9 Binary files /dev/null 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 new file mode 100644 index 00000000000..9b4175fb43e Binary files /dev/null and b/tutorials/2d/img/using_tilesets_create_physics_layer.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_terrain.webp b/tutorials/2d/img/using_tilesets_create_terrain.webp new file mode 100644 index 00000000000..0c858cc0bcb Binary files /dev/null and b/tutorials/2d/img/using_tilesets_create_terrain.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_terrain_set.webp b/tutorials/2d/img/using_tilesets_create_terrain_set.webp new file mode 100644 index 00000000000..3270f0bb1e5 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_create_terrain_set.webp differ diff --git a/tutorials/2d/img/using_tilesets_create_tiles_automatically.webp b/tutorials/2d/img/using_tilesets_create_tiles_automatically.webp new file mode 100644 index 00000000000..92021daa569 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_create_tiles_automatically.webp differ diff --git a/tutorials/2d/img/using_tilesets_creating_scene_collection.webp b/tutorials/2d/img/using_tilesets_creating_scene_collection.webp new file mode 100644 index 00000000000..785d4267d1d Binary files /dev/null and b/tutorials/2d/img/using_tilesets_creating_scene_collection.webp differ diff --git a/tutorials/2d/img/using_tilesets_creating_triangle_collision.webp b/tutorials/2d/img/using_tilesets_creating_triangle_collision.webp new file mode 100644 index 00000000000..2ab00193702 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_creating_triangle_collision.webp differ diff --git a/tutorials/2d/img/using_tilesets_custom_data_layers_example.webp b/tutorials/2d/img/using_tilesets_custom_data_layers_example.webp new file mode 100644 index 00000000000..39725c44b0f Binary files /dev/null and b/tutorials/2d/img/using_tilesets_custom_data_layers_example.webp differ diff --git a/tutorials/2d/img/using_tilesets_drawing_custom_collision.webp b/tutorials/2d/img/using_tilesets_drawing_custom_collision.webp new file mode 100644 index 00000000000..20cea1bef73 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_drawing_custom_collision.webp differ diff --git a/tutorials/2d/img/using_tilesets_edit_custom_data.webp b/tutorials/2d/img/using_tilesets_edit_custom_data.webp new file mode 100644 index 00000000000..aa7e7b5f042 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_edit_custom_data.webp differ diff --git a/tutorials/2d/img/using_tilesets_eraser_tool.webp b/tutorials/2d/img/using_tilesets_eraser_tool.webp new file mode 100644 index 00000000000..c8875838633 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_eraser_tool.webp differ diff --git a/tutorials/2d/img/using_tilesets_kenney_abstract_platformer_tile_sheet.webp b/tutorials/2d/img/using_tilesets_kenney_abstract_platformer_tile_sheet.webp new file mode 100644 index 00000000000..7699e0273c6 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_kenney_abstract_platformer_tile_sheet.webp differ diff --git a/tutorials/2d/img/using_tilesets_line_tool_multiple_tiles.webp b/tutorials/2d/img/using_tilesets_line_tool_multiple_tiles.webp new file mode 100644 index 00000000000..517f37a1eb2 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_line_tool_multiple_tiles.webp differ diff --git a/tutorials/2d/img/using_tilesets_load_tilesheet.webp b/tutorials/2d/img/using_tilesets_load_tilesheet.webp new file mode 100644 index 00000000000..4f4e6eb5443 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_load_tilesheet.webp differ diff --git a/tutorials/2d/img/using_tilesets_open_atlas_merging_tool.webp b/tutorials/2d/img/using_tilesets_open_atlas_merging_tool.webp new file mode 100644 index 00000000000..cd868d1d595 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_open_atlas_merging_tool.webp differ diff --git a/tutorials/2d/img/using_tilesets_paint_custom_data.webp b/tutorials/2d/img/using_tilesets_paint_custom_data.webp new file mode 100644 index 00000000000..2571277dc5a Binary files /dev/null and b/tutorials/2d/img/using_tilesets_paint_custom_data.webp differ diff --git a/tutorials/2d/img/using_tilesets_paint_tile_properties.webp b/tutorials/2d/img/using_tilesets_paint_tile_properties.webp new file mode 100644 index 00000000000..34fa42bde61 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_paint_tile_properties.webp differ diff --git a/tutorials/2d/img/using_tilesets_paint_tile_properties_collision.webp b/tutorials/2d/img/using_tilesets_paint_tile_properties_collision.webp new file mode 100644 index 00000000000..03d4f648d5e Binary files /dev/null and b/tutorials/2d/img/using_tilesets_paint_tile_properties_collision.webp differ diff --git a/tutorials/2d/img/using_tilesets_properties.webp b/tutorials/2d/img/using_tilesets_properties.webp new file mode 100644 index 00000000000..844c225dcf6 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_properties.webp differ diff --git a/tutorials/2d/img/using_tilesets_recreate_tiles_automatically.webp b/tutorials/2d/img/using_tilesets_recreate_tiles_automatically.webp new file mode 100644 index 00000000000..2283efb9372 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_recreate_tiles_automatically.webp differ diff --git a/tutorials/2d/img/using_tilesets_scene_collection_create_scene_tile.webp b/tutorials/2d/img/using_tilesets_scene_collection_create_scene_tile.webp new file mode 100644 index 00000000000..1576f2494e0 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_scene_collection_create_scene_tile.webp differ diff --git a/tutorials/2d/img/using_tilesets_select_and_set_tile_properties.webp b/tutorials/2d/img/using_tilesets_select_and_set_tile_properties.webp new file mode 100644 index 00000000000..10e3b70c026 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_select_and_set_tile_properties.webp differ diff --git a/tutorials/2d/img/using_tilesets_selecting_collision_editor.webp b/tutorials/2d/img/using_tilesets_selecting_collision_editor.webp new file mode 100644 index 00000000000..f432b02df7e Binary files /dev/null and b/tutorials/2d/img/using_tilesets_selecting_collision_editor.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 new file mode 100644 index 00000000000..7da39c8caba Binary files /dev/null and b/tutorials/2d/img/using_tilesets_specify_size_then_edit.webp differ diff --git a/tutorials/2d/img/using_tilesets_terrain_example_tilesheet.webp b/tutorials/2d/img/using_tilesets_terrain_example_tilesheet.webp new file mode 100644 index 00000000000..0151179fc39 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_terrain_example_tilesheet.webp differ diff --git a/tutorials/2d/img/using_tilesets_terrain_example_tilesheet_configuration.webp b/tutorials/2d/img/using_tilesets_terrain_example_tilesheet_configuration.webp new file mode 100644 index 00000000000..e8d8ea70052 Binary files /dev/null and b/tutorials/2d/img/using_tilesets_terrain_example_tilesheet_configuration.webp differ diff --git a/tutorials/2d/img/using_tilesets_using_default_rectangle_collision.webp b/tutorials/2d/img/using_tilesets_using_default_rectangle_collision.webp new file mode 100644 index 00000000000..7ad316a810e Binary files /dev/null and b/tutorials/2d/img/using_tilesets_using_default_rectangle_collision.webp differ diff --git a/tutorials/2d/index.rst b/tutorials/2d/index.rst index 36e85adf7bf..3d1825a4c69 100644 --- a/tutorials/2d/index.rst +++ b/tutorials/2d/index.rst @@ -38,4 +38,5 @@ Tools :maxdepth: 1 :name: toc-learn-features-2d-tools + using_tilesets using_tilemaps diff --git a/tutorials/2d/using_tilemaps.rst b/tutorials/2d/using_tilemaps.rst index a9d31427410..b61b13e0064 100644 --- a/tutorials/2d/using_tilemaps.rst +++ b/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 ` 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 +.. note:: -Project setup -------------- + 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. + + This change allows for greater design consistency, as not every tile needs to be + rotated or flipped within a TileSet. + +Specifying the TileSet in the TileMap +------------------------------------- + +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. + +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**: + +.. 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 + +Creating TileMap layers +----------------------- + +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. + +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: + +.. 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. + +You can reorder layers by drag-and-dropping the "three horizontal bars" icon on +the left of the entries in the **Layers** section. -This demo will use the following tiles taken from Kenney's "Abstract Platformer" -art pack. You can find the complete set `here `_ -but for this demo we'll stick to this small set. +.. note:: -.. image:: img/tilesheet.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. -Create a new project and place the above image in the project folder. +Opening the TileMap editor +-------------------------- -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. +Select the TileMap node, then open the TileMap panel at the bottom +of the editor: -TileMap node ------------- +.. 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. -Add a new :ref:`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. + Opening the TileMap panel at the bottom of the editor. The TileMap node must be selected first. -.. image:: img/tilemap_mode.png +Selecting tiles to use for painting +----------------------------------- -Under the "Cell" section in the Inspector are many properties you can adjust to -customize your tilemap's behavior: +First, if you've created additional layers above, make sure you've selected the +layer you wish to paint on: -.. image:: img/tilemap_size.png +.. figure:: img/using_tilemaps_select_layer.webp + :align: center + :alt: Selecting a layer to paint on in the TileMap editor -- ``Cell Size`` - This defines the size of the grid. This should match the pixel size - of your tiles. The default value is ``(64, 64)``. + Selecting a layer to paint on in the TileMap editor -- ``YSort`` - This causes tiles to be drawn in order of their ``Y`` position, so that - "lower" tiles are drawn on top of "higher" ones. +.. tip:: -- ``Half Offset`` and ``Tile Origin`` - These properties affect the position of the tile relative to the grid position. + 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). -- ``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. +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. -- ``Custom Transform`` - Used to alter the tile's shape. Use this if you have non-square tiles. +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: -All of these options can be left at their defaults for this demo. +.. figure:: img/using_tilemaps_select_single_tile_from_tileset.webp + :align: center + :alt: Selecting a tile in the TileMap editor by clicking it -Creating a TileSet ------------------- + Selecting a tile in the TileMap editor by clicking it -Once you've configured your tilemap, it's time to add a -:ref:`TileSet `. A TileSet is a -:ref:`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. +.. tip:: -To add a new TileSet, click on the "Tile Set" property and select "New -TileSet". + 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. -.. image:: img/tilemap_add_tileset.png +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). -Click on the TileSet property, and the "TileSet" panel will open at the bottom -of the editor window: +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. -.. image:: img/tilemap_tool.png +.. 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 -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. + Selecting multiple tiles in the TileMap editor by holding down the left mouse button -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. +If you've created alternative tiles in your TileSet, you can select them for +painting on the right of the base tiles: -.. image:: img/tilemap_add_tile.png +.. figure:: img/using_tilemaps_use_alternative_tile.webp + :align: center + :alt: Selecting an alternative tile in the TileMap editor -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. + Selecting an alternative tile in the TileMap editor -.. image:: img/tilemap_draw.png +Lastly, if you've created a *scenes collection* in the TileSet, you can place scene tiles in the TileMap: -It's easy to accidentally select and move the tilemap node. To avoid this, use -the node's lock button: +.. figure:: img/using_tilemaps_placing_scene_tiles.webp + :align: center + :alt: Placing a scene tile containing particles using the TileMap editor -.. image:: img/tile_lock.png + Placing a scene tile containing particles using the TileMap editor -Collision shapes ----------------- +Painting modes and tools +------------------------ -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". +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. -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: +From left to right, the painting modes and tools you can choose are: -.. image:: img/tileset_add_collision.png +Selection +^^^^^^^^^ -You can add occlusion and navigation shapes to the tile in the same way. +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. -Atlas tiles ------------ +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. -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. +The selection can then be used in any other painting mode to quickly create copies +of an already-placed pattern. -Click "New Atlas" and drag to select the entire tile sheet. +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. -.. image:: img/tileset_atlas.png +You can toggle this mode temporarily while in Paint mode by holding :kbd:`Ctrl` +then performing a selection. -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: +.. tip:: -.. image:: img/tileset_snap.png + 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. -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. +Paint +^^^^^ -Back in the TileMap, you can select the atlas tile and you'll see all of the -tiles it contains: +The standard Paint mode allows you to place tiles by clicking or holding +down the left mouse button. -.. image:: img/tileset_draw_atlas.png +If you right-click, the currently selected tile will be erased from the tilemap. +In other words, it will be replaced by empty space. -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. +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. -Random tile priorities -~~~~~~~~~~~~~~~~~~~~~~ +.. tip:: -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. + 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. -Autotiles ---------- + 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. -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. + 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. -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. +Line +^^^^ -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. +After selecting Line Paint mode, you can draw in a line that is +always 1 tile thick (no matter its orientation). -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. +If you right-click while in Line Paint mode, you will erase in a line. -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". +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. -All "on" and "off" bits must be satisfied for a bitmask to match, but "ignore" -bits are ignored. +You can toggle this mode temporarily while in Paint or Eraser mode by holding +:kbd:`Shift` then drawing. -2x2 -~~~ +.. figure:: img/using_tilemaps_bucket_fill.webp + :align: center + :alt: Using the line tool after selecting two tiles to draw platforms diagonally -In 2x2 mode, each bitmask contains four bits, one for each corner. + Using the line tool after selecting two tiles to draw platforms diagonally -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. +Rectangle +^^^^^^^^^ -Where a bit is "off", at least one cell connected to that corner must not be -set using the same autotile. +After selecting Rectangle Paint mode, you can draw in an axis-aligned +rectangle. -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. +If you right-click while in Rectangle Paint mode, you will erase in +an axis-aligned rectangle. -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. +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. -**Template - Generic:** +You can toggle this mode temporarily while in Paint or Eraser mode by holding +:kbd:`Ctrl` and :kbd:`Shift` then drawing. -This template can be used for sideways or fully top-down perspectives. -It's designed for a TileMap cell size of 64x64. +Bucket Fill +^^^^^^^^^^^ -Key: +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. -- Red: "on" -- White: "off" +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. -.. image:: img/autotile_template_2x2.png +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. -3x3 (minimal) -~~~~~~~~~~~~~ +If you right-click while in Bucket Fill mode, you will replace matching tiles +with empty tiles. -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. +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. -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. +.. figure:: img/using_tilemaps_bucket_fill.webp + :align: center + :alt: Using the Bucket Fill tool -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". + Using the Bucket Fill tool -A total of 47 tiles would be needed to provide exactly one bitmask for each -arrangement that this mode can test for. +Picker +^^^^^^ -.. note:: +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. - Right-click an image and choose **Save image as…** to save it. +Eraser +^^^^^^ -**Template - Generic:** +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. -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. +You can toggle this mode temporarily while in any other mode by right-clicking +instead of left-clicking. -Key: +Painting randomly using scattering +---------------------------------- -- Red: "on" -- White: "off" +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). -.. image:: img/autotile_template_3x3_minimal.png +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: -**Template - Generic 16 tiles:** +.. 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 -This template can be used for tilesets that only have 16 tiles - for simpler art -styles the missing tiles will not be noticeable. + Selecting from several times to randomly choose, then painting by holding down the left mouse button -Key: +Example when using Bucket Fill mode: -- Red: "on" -- White: "off" -- Blue-checkered: "ignore" +.. 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 -.. image:: img/autotile_template_3x3_minimal_16.png + 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. -**Template - Top-down floor in 3/4 perspective:** +Saving and loading premade tile placements using patterns +--------------------------------------------------------- -Key (applies to the four templates below): +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. -- Green: floor -- Cyan: wall -- Yellow: top of wall -- Transparent: air +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`: -.. image:: img/autotile_template_3x3_minimal_topdown_floor.png +.. figure:: img/using_tilemaps_create_pattern.webp + :align: center + :alt: Creating a new pattern from a selection in the TileMap editor -**Template - Top-down wall in 3/4 perspective:** + Creating a new pattern from a selection in the TileMap editor -.. image:: img/autotile_template_3x3_minimal_topdown_walls.png +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: -**Template - Top-down wall in 3/4 perspective (thick walls):** +.. figure:: img/using_tilemaps_use_pattern.webp + :align: center + :alt: Placing an existing pattern using the TileMap editor -When using this template, set the TileSet subtile size to ``Vector2(64, 88)``. + Placing an existing pattern using the TileMap editor -.. image:: img/autotile_template_3x3_minimal_topdown_walls_thick.png +Like multi-tile selections, patterns will be repeated if used with the Line, +Rectangle or Bucket Fill painting modes. + +.. note:: -**Template - Top-down wall in 3/4 perspective (tall walls):** + 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. -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)``: +Handling tile connections automatically using terrains +------------------------------------------------------ -.. image:: img/autotile_template_3x3_minimal_topdown_walls_tall.png +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. -3x3 -~~~ +There are 3 kinds of painting modes available for terrain connections: -In 3x3 mode, each bitmask contains 9 bits (4 corners, 4 edges, 1 center) +- **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. -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. +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. -A total of 256 tiles would be needed to provide exactly one bitmask for each -arrangement that this mode can test for. +.. 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 -Disabling autotile -~~~~~~~~~~~~~~~~~~ +.. figure:: img/using_tilemaps_terrain_select_path_mode.webp + :align: center + :alt: Selecting Path mode in the TileMap editor's Terrains tab -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. + Selecting Path mode in the TileMap editor's Terrains tab -Autotile binding -~~~~~~~~~~~~~~~~ +Lastly, you can select specific tiles from the terrain to resolve conflicts in +certain situations: -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. +.. figure:: img/using_tilemaps_terrain_paint_specific_tiles.webp + :align: center + :alt: Painting with specific tiles in the TileMap editor's Terrains tab -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. + Painting with specific tiles in the TileMap editor's Terrains tab -Tips and tricks ---------------- +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. -- If you're using a :ref:`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. +Handling missing tiles +---------------------- -- You can flip and rotate tiles using the icons at the top right of the editor. +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: -- To draw straight lines, hold :kbd:`Shift` while clicking and dragging a tile. +.. figure:: img/using_tilemaps_missing_tiles.webp + :align: center + :alt: Missing tiles in the TileMap editor due to the TileSet reference being broken -- Tools such as copy, paste, and bucket fill, can be found in the "TileMap" - menu in the upper-right. + 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:: -.. image:: img/tilemap_menu.png + Missing tile placeholders may not be visible until you select the TileMap + node and open the TileMap editor. diff --git a/tutorials/2d/using_tilesets.rst b/tutorials/2d/using_tilesets.rst new file mode 100644 index 00000000000..26cb123dac0 --- /dev/null +++ b/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 ` 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 +TileSet, you will be able to place them :ref:`using the TileMap editor +`. + +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 `__. +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 `__ + +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 `. + +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 `, 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 `. + +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 ` 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 ` +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 `__ 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.