godot-tilemap Checked

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.

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

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])

### 2. Place and erase tiles at runtime