godot-tilemap

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

extends TileMapLayer

func _unhandled_input(event: InputEvent) -> void:
    if event is InputEventMouseButton and event.pressed:
        # local_to_map expects local coords; convert from global first.
        var cell := local_to_map(to_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])