TileMap System

Relevant source files

• core/register_core_types.cpp
• core/register_core_types.h
• doc/classes/AnimatedTexture.xml
• doc/classes/AtlasTexture.xml
• doc/classes/Camera2D.xml
• doc/classes/Camera3D.xml
• doc/classes/CanvasLayer.xml
• doc/classes/Node2D.xml
• doc/classes/Node3D.xml
• doc/classes/ParallaxBackground.xml
• doc/classes/ParallaxLayer.xml
• modules/dds/dds_enums.h
• modules/dds/image_saver_dds.cpp
• modules/dds/register_types.cpp
• modules/dds/texture_loader_dds.cpp
• modules/gltf/tests/test_gltf.h
• modules/ktx/register_types.cpp
• modules/mono/register_types.cpp
• modules/theora/register_types.cpp
• scene/2d/camera_2d.cpp
• scene/2d/camera_2d.h
• scene/2d/light_2d.cpp
• scene/2d/light_2d.h
• scene/2d/light_occluder_2d.cpp
• scene/2d/light_occluder_2d.h
• scene/2d/node_2d.cpp
• scene/2d/node_2d.h
• scene/2d/polygon_2d.cpp
• scene/2d/polygon_2d.h
• scene/3d/camera_3d.cpp
• scene/3d/camera_3d.h
• scene/3d/node_3d.cpp
• scene/3d/node_3d.h
• scene/main/canvas_layer.cpp
• scene/main/canvas_layer.h
• scene/register_scene_types.cpp
• scene/resources/atlas_texture.cpp
• scene/resources/atlas_texture.h
• scene/resources/texture.cpp
• scene/resources/texture.h
• servers/register_server_types.cpp
• servers/rendering/rendering_device_binds.h
• tests/SCsub
• tests/display_server_mock.h
• tests/test_macros.h
• tests/test_main.cpp

This page documents the tile-based map system in Godot, covering TileMap, TileMapLayer, TileSet, TileSetAtlasSource, TileData, and related classes. This system lives under the Scene System (see page 4); for the 2D rendering pipeline that draws tiles, see page 7

---

Overview

The TileMap system provides grid-based 2D maps. Tiles are defined in a shared TileSet resource and placed into one or more TileMapLayer nodes. Each cell on a layer references a tile by three IDs: source_id, atlas_coords, and alternative_tile.

Deprecation note: TileMap is deprecated as of Godot 4.x. New projects should use individual TileMapLayer nodes directly. The TileMap node now emits a configuration warning recommending migration. See the TileMap → TileMapLayer section below.

Sources: scene/register_scene_types.cpp, scene/2d/node_2d.cpp

---

Architecture

Class Relationship Overview

Sources: scene/register_scene_types.cpp101-150 scene/2d/node_2d.h31-100 scene/resources/atlas_texture.h37-60

---

Core Data Structure: TileMapCell

Every occupied cell is stored as a TileMapCell. It is a compact structure used to identify which tile from the TileSet is placed at a specific coordinate.

Field	Type	Description
source_id	int16_t	Identifies the TileSetSource within the TileSet
coord_x, coord_y	int16_t	Atlas coordinates identifying the tile within the source
alternative_tile	int16_t	Alternative tile variant (rotation/flip flags or scene index)

An invalid/empty cell typically uses -1 for these IDs.

Sources: scene/resources/atlas_texture.cpp33-80

---

TileMapLayer

TileMapLayer is the modern node class for a single tile layer. It inherits from Node2D and CanvasItem, allowing it to handle its own transforms and rendering calls to the RenderingServer.

Rendering and Transforms

Like all CanvasItem nodes, TileMapLayer uses the RenderingServer to draw. It calculates its local transform based on the TileSet grid properties.

scene/2d/node_2d.cpp139-146

Sources: scene/2d/node_2d.cpp139-146 scene/main/canvas_item.h35-100

---

TileSet

TileSet defines the library of tiles. It contains TileSetSource objects, which can be textures (atlases) or scene collections.

Property Layers

TileSet supports multiple functional layers that apply to all tiles:

• Physics Layers: Defines collision shapes handled by PhysicsServer2D.
• Navigation Layers: Defines polygons for the NavigationServer2D.
• Custom Data Layers: Allows users to attach metadata to tiles.

Sources: scene/register_scene_types.cpp145-147 servers/register_server_types.cpp87-98

---

TileSet Sources

Source Type Hierarchy

Sources: core/register_core_types.cpp150-160 scene/resources/texture.h41-84

TileSetAtlasSource

An atlas source uses a Texture2D (such as a CompressedTexture2D or ImageTexture) and slices it into a grid. Each tile in the grid can have TileData associated with it.

TileSetScenesCollectionSource

This source allows grid cells to represent PackedScene resources. When the map is instantiated, the system spawns these scenes as child nodes.

Sources: scene/resources/texture.cpp37-121 scene/register_scene_types.cpp150-155

---

TileData

TileData holds the properties for a specific tile. This includes visual properties (modulate, Z-index) and functional properties (collision polygons, navigation).

Property	Description
modulate	The color applied to the tile texture during draw_rect_region.
z_index	The rendering priority relative to other items in the same CanvasLayer.
terrain	The terrain ID used by the auto-tiling algorithms.

Sources: scene/resources/texture.cpp89-108 scene/main/canvas_layer.cpp35-80

---

Update Lifecycle Summary

Internal Update Sequence

Tiles are rendered via the CanvasItem API. When a cell changes, the layer triggers a redraw or updates its internal representation in the physics/navigation servers.

Sources: scene/resources/texture.cpp103-108 scene/2d/node_2d.cpp139-146 servers/register_server_types.cpp93-98

---

Migration: TileMap to TileMapLayer {#migration}

TileMap is now a legacy wrapper. The engine encourages moving to TileMapLayer nodes for better performance and clearer scene trees.

Deprecated TileMap Call	New TileMapLayer Equivalent
set_cell(layer_index, coords, ...)	set_cell(coords, ...) on the specific layer node
get_cell_source_id(layer, coords)	get_cell_source_id(coords)

Sources: scene/register_scene_types.cpp101-110 scene/2d/node_2d.h31-50