godot-tilemap
Build and edit tile-based 2D levels in Godot 4.7 with TileMapLayer and TileSet: paint layers, set up collision/navigation/custom-data on tiles, autotile with terrain sets, and read/write cells from code (set_cell, get_cell_tile_data, local_to_map). Use when working with TileMapLa
Install
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/main/skills/godot/godot-tilemap
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gamedev-skills-awesome-gamedev-agent-skills@llmmart
git clone https://github.com/gamedev-skills/awesome-gamedev-agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gamedev-skills/awesome-gamedev-agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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
TileMapnode (single node, many layers) to multipleTileMapLayernodes (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
TileMapLayernode (one per visual/logical layer: background, walls, foreground). Each holds exactly one layer of tiles. - Create or assign a
TileSeton the layer'stile_setproperty. Add an atlas source (a texture sliced into tiles) in the TileSet editor. Save the TileSet as an external.tresso 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
damageoris_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_enabledproperties. - Read/write from code with
local_to_map,set_cell,get_cell_source_id, andget_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
TileMapnode is deprecated in 4.3. UseTileMapLayernodes (one layer per node); group them under a parentNode2D. OldTileMapcalls that took alayerargument (set_cell(layer, ...)) do not apply toTileMapLayer.local_to_mapneeds layer-local coordinates. A world position needsto_local(...)first. A mouse event'spositionis in viewport pixels, not world space, so it is wrong as soon as aCamera2Dscrolls or zooms; convert it withmake_input_local(event)(or pollget_local_mouse_position()) instead.get_cell_tile_datareturnsnullfor empty cells or non-atlas sources — always null-check beforeget_custom_data.- Custom data is typed. A layer declared as
intreturnsint; 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_connectproduces 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, callupdate_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), readreferences/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.
Files (awesome-gamedev-agent-skills)
-
references
-
tileset-and-terrains.md 4 KB
Loading…
-
-
SKILL.md 5.9 KB
--- name: godot-tilemap description: > Build and edit tile-based 2D levels in Godot 4.7 with TileMapLayer and TileSet: paint layers, set up collision/navigation/custom-data on tiles, autotile with terrain sets, and read/write cells from code (set_cell, get_cell_tile_data, local_to_map). Use when working with TileMapLayer nodes, .tres TileSets, autotiling, or migrating a deprecated TileMap node to TileMapLayer. --- # 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 1. **Add a `TileMapLayer` node** (one per visual/logical layer: background, walls, foreground). Each holds exactly one layer of tiles. 2. **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. 3. **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`). 4. **Paint** in the TileMap bottom panel (Paint/Line/Rectangle/Bucket). For self- connecting tiles, define a **terrain set** and paint with Connect/Path mode. 5. **Enable per-layer collision/navigation** via the layer's `collision_enabled` / `navigation_enabled` properties. 6. **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 ```gdscript 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 ```gdscript # 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 ```gdscript # 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) ```gdscript 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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.