GDScript TileMapLayer Practice

Godot 4.3 deprecated the multi-layer TileMap node in favor of individual TileMapLayer nodes. Each layer is now its own node in the scene tree.

# OLD (Godot 4.2 and earlier) - deprecated
$TileMap.set_cell(0, Vector2i(3, 5), 0, Vector2i(0, 0))  # layer 0

# NEW (Godot 4.3+) - each layer is a separate node
$GroundLayer.set_cell(Vector2i(3, 5), 0, Vector2i(0, 0))
$WallLayer.set_cell(Vector2i(3, 5), 0, Vector2i(1, 0))

Migration: The Godot editor has a built-in migration tool that converts old TileMap nodes to TileMapLayer nodes automatically. Each layer becomes a child node you reference with @onready.

Runtime gotcha: TileMapLayer batches updates until the end of the frame. If you paint cells and immediately need fresh collision, navigation, or scene tile state, call update_internals() once after the batch.

set_cell() takes three required arguments: grid coordinates, source ID, and atlas coordinates. The source ID identifies which TileSetSource to use (usually 0 for a single tileset). Atlas coordinates pick the specific tile from the atlas texture.

@onready var ground_layer: TileMapLayer = $GroundLayer

const FLOOR_ATLAS := Vector2i(1, 0)
const WALL_ATLAS := Vector2i(0, 0)

# Paint a floor tile at grid position (3, 5)
ground_layer.set_cell(Vector2i(3, 5), 0, FLOOR_ATLAS)

# Erase a tile (removes it completely)
ground_layer.erase_cell(Vector2i(3, 5))

Fill-then-carve pattern for procedural generation: fill the entire grid with walls, then selectively replace wall tiles with floor tiles where the algorithm carves passages.

func fill_with_walls() -> void:
    for x in range(width):
        for y in range(height):
            ground_layer.set_cell(Vector2i(x, y), 0, WALL_ATLAS)

func carve_floor(pos: Vector2i) -> void:
    ground_layer.set_cell(pos, 0, FLOOR_ATLAS)

get_cell_source_id() returns -1 for empty cells, not 0. This is the most common source of bugs when checking tile types.

func is_wall(pos: Vector2i) -> bool:
    var source_id := ground_layer.get_cell_source_id(pos)
    if source_id == -1:
        return true  # Empty = treat as wall
    var atlas := ground_layer.get_cell_atlas_coords(pos)
    return atlas == WALL_ATLAS

func is_floor(pos: Vector2i) -> bool:
    var source_id := ground_layer.get_cell_source_id(pos)
    if source_id == -1:
        return false  # Empty = not walkable
    return ground_layer.get_cell_atlas_coords(pos) == FLOOR_ATLAS

Roguelike collision without physics: Instead of using CollisionShape2D for every wall tile, check is_wall() at the target position before allowing movement. Faster and simpler for grid-based games.

Reading custom tile metadata

If your TileSet stores custom data layers like movement cost, hazard damage, or biome type, use get_cell_tile_data():

func get_tile_power(pos: Vector2i) -> int:
    var data := ground_layer.get_cell_tile_data(pos)
    if data == null:
        return 0
    return data.get_custom_data("power")

This scales better than comparing atlas coordinates everywhere once tiles start carrying gameplay meaning.

map_to_local() converts grid coordinates to pixel coordinates. It returns the center of the tile, not the top-left corner.

# Grid to pixel (center of tile)
var pixel_pos: Vector2 = ground_layer.map_to_local(Vector2i(3, 5))

# Pixel to grid (which tile is the mouse over?)
var grid_pos: Vector2i = ground_layer.local_to_map(get_local_mouse_position())

Sprite snapping: To snap a character to a grid tile, set its position to map_to_local(grid_pos). The sprite centers on the tile automatically.

var grid_pos := Vector2i(5, 3)
player.position = ground_layer.map_to_local(grid_pos)

Mouse click to tile: Convert the mouse position to local coordinates first, then use local_to_map(). Both functions work in the TileMapLayer's local coordinate space. If the layer has been moved or scaled, use to_local() to convert global positions first.

Finding map bounds

When you need dungeon bounds, camera limits, or a quick "how much of this layer is painted?" check, get_used_rect() gives you the rectangle containing all non-empty cells:

var used_rect := ground_layer.get_used_rect()

Use separate TileMapLayer nodes for different purposes: ground, walls, decorations, and fog-of-war. Each layer references the same TileSet but is painted independently.

@onready var ground_layer: TileMapLayer = $GroundLayer
@onready var decor_layer: TileMapLayer = $DecorLayer
@onready var fog_layer: TileMapLayer = $FogLayer

Fog-of-war pattern

Fill the fog layer completely, then erase tiles around the player to reveal the map:

func reveal_around(center: Vector2i, radius: int) -> void:
    for dx in range(-radius, radius + 1):
        for dy in range(-radius, radius + 1):
            if dx * dx + dy * dy <= radius * radius:
                fog_layer.erase_cell(center + Vector2i(dx, dy))

The fog layer renders on top of everything. Erasing tiles punches holes that reveal the layers below.