Godot TileMap (4.7 TileMapLayer)
Author tile-based levels with TileMapLayer + TileSet, add per-tile collision and
custom data, autotile with terrains, and manipulate cells at runtime. Targets
Godot 4.7, where TileMapLayer replaces the now-deprecated TileMap node.
When to use
- Use when designing 2D levels from a tile grid, configuring a
TileSet (collision,
navigation, custom data, terrains), or reading/writing tiles from code.
- Use when migrating a
TileMap node (single node, many layers) to multiple
TileMapLayer nodes (one layer each).
When not to use: moving the player across the tiles → godot-2d-movement; general
physics bodies/raycasts → godot-physics; procedural map generation algorithms →
procedural-gen; level design practice → level-design.
Core workflow
- Add a
TileMapLayer node (one per visual/logical layer: background, walls,
foreground). Each holds exactly one layer of tiles.
- Create or assign a
TileSet on the layer's tile_set property. Add an atlas
source (a texture sliced into tiles) in the TileSet editor. Save the TileSet as an
external .tres so multiple layers/levels reuse it.
- Add tile data in the TileSet editor: physics layers (collision polygons),
navigation layers, occlusion, and custom data layers (typed per-tile values like
damage or is_ladder).
- Paint in the TileMap bottom panel (Paint/Line/Rectangle/Bucket). For self-
connecting tiles, define a terrain set and paint with Connect/Path mode.
- Enable per-layer collision/navigation via the layer's
collision_enabled /
navigation_enabled properties.
- Read/write from code with
local_to_map, set_cell, get_cell_source_id, and
get_cell_tile_data(...).get_custom_data(...).
Patterns
1. Convert mouse position to a cell and read its custom data
extends TileMapLayer
func _unhandled_input(event: InputEvent) -> void:
if event is InputEventMouseButton and event.pressed:
# event.position is in viewport pixels and ignores Camera2D scroll/zoom.
# make_input_local() converts it into this layer's local space.
var local_event := make_input_local(event) as InputEventMouseButton
var cell := local_to_map(local_event.position)
var data := get_cell_tile_data(cell) # TileData or null
if data:
var dmg: int = data.get_custom_data("damage") # custom data layer
print("Cell %s deals %d damage" % [cell, dmg])
2. Place and erase tiles at runtime
# set_cell(coords, source_id, atlas_coords, alternative_tile = 0)
func place_wall(cell: Vector2i) -> void:
set_cell(cell, 0, Vector2i(2, 1)) # source 0, atlas tile at column 2, row 1
func dig(cell: Vector2i) -> void:
erase_cell(cell) # same as set_cell(cell, -1)
func clear_level() -> void:
clear() # remove every tile on this layer
3. Autotiling a region with a terrain set
# Paint a filled area with terrain `terrain` of terrain set `terrain_set`;
# Godot picks the correct edge/corner tiles to connect them.
func fill_with_grass(cells: Array[Vector2i]) -> void:
var terrain_set := 0
var grass_terrain := 0
set_cells_terrain_connect(cells, terrain_set, grass_terrain, true)
4. Iterate placed tiles (e.g. find all spawn tiles)
func find_spawns() -> Array[Vector2i]:
var spawns: Array[Vector2i] = []
for cell in get_used_cells():
var data := get_cell_tile_data(cell)
if data and data.get_custom_data("is_spawn"):
spawns.append(cell)
return spawns
Pitfalls
TileMap node is deprecated in 4.3. Use TileMapLayer nodes (one layer per node);
group them under a parent Node2D. Old TileMap calls that took a layer argument
(set_cell(layer, ...)) do not apply to TileMapLayer.
local_to_map needs layer-local coordinates. A world position needs to_local(...)
first. A mouse event's position is in viewport pixels, not world space, so it is wrong as
soon as a Camera2D scrolls or zooms; convert it with make_input_local(event) (or
poll get_local_mouse_position()) instead.
get_cell_tile_data returns null for empty cells or non-atlas sources — always
null-check before get_custom_data.
- Custom data is typed. A layer declared as
int returns int; reading it as the
wrong type or referencing a non-existent layer name errors. Define the layer in the
TileSet first.
- Terrains need every combination defined.
set_cells_terrain_connect produces odd
results if the TileSet's terrain bitmask peering is incomplete.
- Runtime edits are batched to end-of-frame. If you must read updated internals
immediately after
set_cell, call update_internals() (expensive — avoid in loops).
- Collision not working? Check the layer's
collision_enabled, that the tile has a
physics layer with a polygon, and that the TileSet's physics layer mask matches your
bodies.
References
- For TileSet setup (atlas sources, physics/navigation/custom-data layers, terrain
bitmasks), scene tiles, Y-sorting, and runtime tile-data overrides
(
_use_tile_data_runtime_update), read references/tileset-and-terrains.md.
Related skills
godot-2d-movement — characters that walk on these tiles.
godot-physics — collision layers/masks the tile collisions participate in.
procedural-gen — generating tilemaps from noise/RNG.
level-design / roguelike — design practice and grid-based genres.
1---2name: godot-tilemap3description: >4 Build and edit tile-based 2D levels in Godot 4.7 with TileMapLayer and TileSet:5 paint layers, set up collision/navigation/custom-data on tiles, autotile with6 terrain sets, and read/write cells from code (set_cell, get_cell_tile_data,7 local_to_map). Use when working with TileMapLayer nodes, .tres TileSets, autotiling,8 or migrating a deprecated TileMap node to TileMapLayer.9metadata:10 source: https://skillmd.com/skills/junmystery/godot-tilemap11---1213# Godot TileMap (4.7 TileMapLayer)1415Author tile-based levels with `TileMapLayer` + `TileSet`, add per-tile collision and16custom data, autotile with terrains, and manipulate cells at runtime. Targets17**Godot 4.7**, where `TileMapLayer` replaces the now-deprecated `TileMap` node.1819## When to use2021- Use when designing 2D levels from a tile grid, configuring a `TileSet` (collision,22 navigation, custom data, terrains), or reading/writing tiles from code.23- Use when migrating a `TileMap` node (single node, many layers) to multiple24 `TileMapLayer` nodes (one layer each).2526**When *not* to use:** moving the player across the tiles → `godot-2d-movement`; general27physics bodies/raycasts → `godot-physics`; procedural map *generation* algorithms →28`procedural-gen`; level *design* practice → `level-design`.2930## Core workflow31321. **Add a `TileMapLayer` node** (one per visual/logical layer: background, walls,33 foreground). Each holds exactly one layer of tiles.342. **Create or assign a `TileSet`** on the layer's `tile_set` property. Add an atlas35 source (a texture sliced into tiles) in the TileSet editor. Save the TileSet as an36 external `.tres` so multiple layers/levels reuse it.373. **Add tile data in the TileSet editor:** physics layers (collision polygons),38 navigation layers, occlusion, and **custom data layers** (typed per-tile values like39 `damage` or `is_ladder`).404. **Paint** in the TileMap bottom panel (Paint/Line/Rectangle/Bucket). For self-41 connecting tiles, define a **terrain set** and paint with Connect/Path mode.425. **Enable per-layer collision/navigation** via the layer's `collision_enabled` /43 `navigation_enabled` properties.446. **Read/write from code** with `local_to_map`, `set_cell`, `get_cell_source_id`, and45 `get_cell_tile_data(...).get_custom_data(...)`.4647## Patterns4849### 1. Convert mouse position to a cell and read its custom data5051```gdscript52extends TileMapLayer5354func _unhandled_input(event: InputEvent) -> void:55 if event is InputEventMouseButton and event.pressed:56 # event.position is in viewport pixels and ignores Camera2D scroll/zoom.57 # make_input_local() converts it into this layer's local space.58 var local_event := make_input_local(event) as InputEventMouseButton59 var cell := local_to_map(local_event.position)60 var data := get_cell_tile_data(cell) # TileData or null61 if data:62 var dmg: int = data.get_custom_data("damage") # custom data layer63 print("Cell %s deals %d damage" % [cell, dmg])64```6566### 2. Place and erase tiles at runtime6768```gdscript69# set_cell(coords, source_id, atlas_coords, alternative_tile = 0)70func place_wall(cell: Vector2i) -> void:71 set_cell(cell, 0, Vector2i(2, 1)) # source 0, atlas tile at column 2, row 17273func dig(cell: Vector2i) -> void:74 erase_cell(cell) # same as set_cell(cell, -1)7576func clear_level() -> void:77 clear() # remove every tile on this layer78```7980### 3. Autotiling a region with a terrain set8182```gdscript83# Paint a filled area with terrain `terrain` of terrain set `terrain_set`;84# Godot picks the correct edge/corner tiles to connect them.85func fill_with_grass(cells: Array[Vector2i]) -> void:86 var terrain_set := 087 var grass_terrain := 088 set_cells_terrain_connect(cells, terrain_set, grass_terrain, true)89```9091### 4. Iterate placed tiles (e.g. find all spawn tiles)9293```gdscript94func find_spawns() -> Array[Vector2i]:95 var spawns: Array[Vector2i] = []96 for cell in get_used_cells():97 var data := get_cell_tile_data(cell)98 if data and data.get_custom_data("is_spawn"):99 spawns.append(cell)100 return spawns101```102103## Pitfalls104105- **`TileMap` node is deprecated in 4.3.** Use `TileMapLayer` nodes (one layer per node);106 group them under a parent `Node2D`. Old `TileMap` calls that took a `layer` argument107 (`set_cell(layer, ...)`) do not apply to `TileMapLayer`.108- **`local_to_map` needs layer-local coordinates.** A world position needs `to_local(...)`109 first. A mouse event's `position` is in viewport pixels, not world space, so it is wrong as110 soon as a `Camera2D` scrolls or zooms; convert it with `make_input_local(event)` (or111 poll `get_local_mouse_position()`) instead.112- **`get_cell_tile_data` returns `null`** for empty cells or non-atlas sources — always113 null-check before `get_custom_data`.114- **Custom data is typed.** A layer declared as `int` returns `int`; reading it as the115 wrong type or referencing a non-existent layer name errors. Define the layer in the116 TileSet first.117- **Terrains need every combination defined.** `set_cells_terrain_connect` produces odd118 results if the TileSet's terrain bitmask peering is incomplete.119- **Runtime edits are batched** to end-of-frame. If you must read updated internals120 immediately after `set_cell`, call `update_internals()` (expensive — avoid in loops).121- **Collision not working?** Check the layer's `collision_enabled`, that the tile has a122 physics layer with a polygon, and that the TileSet's physics layer mask matches your123 bodies.124125## References126127- For TileSet setup (atlas sources, physics/navigation/custom-data layers, terrain128 bitmasks), scene tiles, Y-sorting, and runtime tile-data overrides129 (`_use_tile_data_runtime_update`), read `references/tileset-and-terrains.md`.130131## Related skills132133- `godot-2d-movement` — characters that walk on these tiles.134- `godot-physics` — collision layers/masks the tile collisions participate in.135- `procedural-gen` — generating tilemaps from noise/RNG.136- `level-design` / `roguelike` — design practice and grid-based genres.