godot-tilemap

Q: How do I install godot-tilemap?

Run npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-tilemap in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/godot-tilemap/ (personal) or .claude/skills/godot-tilemap/ (project).

by gamedev-skillsAI & Agents

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 (setcell, getcelltiledata, localtomap). Use when working with TileMapLayer nodes, .tres TileSets, autotiling, or migrating a deprecated TileMap node to TileMapLayer.

Installs: 6.4K
Last 24h: +327
Trending rank: #908
Security: Pass

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-tilemap

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads godot-tilemap automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·This skill provides documentation and code examples for Godot 4.7's TileMapLayer system, including runtime tile manipulation, autotiling, and custom metadata handling. No security risks were identified.

Socket PassNo alerts

Snyk PassLOW ·Risk: LOW · No issues

SKILL.md

The instructions your agent reads when the skill is triggered.

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.

FAQ

What does the godot-tilemap skill do?

How do I install godot-tilemap?

Run npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-tilemap in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/godot-tilemap/ (personal) or .claude/skills/godot-tilemap/ (project).

Which AI agents can use godot-tilemap?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is godot-tilemap safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains godot-tilemap?

It is published by gamedev-skills in gamedev-skills/awesome-gamedev-agent-skills. It has 6,400 recorded installs.