TileMap en Godot 4 — Guía completa

Introducción

Godot 4 reescribió por completo el sistema TileMap. Si usaste TileMap en Godot 3, casi todo ha cambiado — el editor de TileSet, cómo se definen los tiles, el auto-tiling, las capas y la API de GDScript. Esta guía cubre la nueva arquitectura desde cero.

La nueva arquitectura de TileMap

El sistema TileMap de Godot 4 tiene dos componentes principales:

• Nodo TileMap — El nodo que añades a tu escena. Contiene una o más capas y hace referencia a un recurso TileSet.
• Recurso TileSet — Define los tiles en sí. Contiene fuentes (atlas, colección de escenas, etc.), capas de física, capas de navegación, capas de datos personalizados y conjuntos de terreno.

Fuentes de TileSet

Un TileSet puede tener múltiples fuentes, cada una identificada por un source_id (entero). Los tipos de fuente incluyen:

• TileSetAtlasSource — El tipo más común. Una única imagen de textura que contiene varios tiles dispuestos en una cuadrícula.
• TileSetScenesCollectionSource — Cada tile es una escena empaquetada, útil para tiles animados o interactivos.

Configurar un TileSet

Paso 1: Crear el recurso TileSet

1. Añade un nodo TileMap a tu escena.
2. En el Inspector, haz clic en la propiedad Tile Set y selecciona New TileSet.
3. Establece el Tile Size (por ejemplo, 16x16 o 32x32).

Paso 2: Añadir una fuente de atlas

1. Haz clic en el TileSet para abrir el editor de TileSet en el panel inferior.
2. Haz clic en el botón + y selecciona Atlas.
3. Arrastra tu imagen de tileset a la propiedad Texture.
4. El editor la divide automáticamente en tiles según tu tamaño de tile. Puedes ajustar la región de textura y los márgenes.

Paso 3: Configurar las propiedades de los tiles

En el editor de TileSet, puedes añadir varios tipos de capas que se aplican a todos los tiles:

• Physics Layers — Formas de colisión para los tiles
• Navigation Layers — Polígonos transitables para el pathfinding
• Custom Data Layers — Datos tipados arbitrarios (bool, int, float, String, etc.)
• Terrain Sets — Para auto-tiling (el reemplazo del autotile de Godot 3)

Capas de TileMap

Un único nodo TileMap puede contener múltiples capas. Es una gran mejora respecto a Godot 3, donde necesitabas nodos TileMap separados para el fondo y el primer plano. Cada capa puede tener sus propios ajustes de z-index, y-sort y modulate.

Configuración de capas habitual:

• Layer 0 — Fondo (suelo, terreno) — z-index: -1
• Layer 1 — Terreno (paredes, obstáculos) — z-index: 0
• Layer 2 — Primer plano (decoración por encima del jugador) — z-index: 1

API de GDScript para capas

# Set a cell on layer 0
tilemap.set_cell(0, Vector2i(5, 3), source_id, atlas_coords)

# Get cell info
var source = tilemap.get_cell_source_id(0, Vector2i(5, 3))
var coords = tilemap.get_cell_atlas_coords(0, Vector2i(5, 3))

# Erase a cell
tilemap.erase_cell(0, Vector2i(5, 3))

# Check if a cell is occupied
if tilemap.get_cell_source_id(0, Vector2i(5, 3)) != -1:
    print("Cell has a tile")

Sistema de terreno (Auto-Tiling)

El sistema de terreno reemplaza el autotile de Godot 3. Selecciona automáticamente la variante de tile correcta según los tiles vecinos.

Configurar terrenos

1. En TileSet, añade un Terrain Set (Inspector → Terrain Sets → Add Element).
2. Elige el modo de terreno: Match Corners and Sides (47 tiles), Match Corners (16 tiles) o Match Sides (16 tiles).
3. Añade tipos de terreno dentro del conjunto (por ejemplo, «Grass», «Dirt», «Water»).
4. En el editor de TileSet, cambia al modo Select, selecciona un tile y pinta los bits de peering de terreno en cada tile.

Pintar terrenos

Una vez configurados los terrenos, cambia al editor de TileMap y selecciona la pestaña Terrains. Elige tu tipo de terreno y pinta directamente en el mapa. Godot seleccionará automáticamente la variante de tile correcta.

# Set terrain programmatically
tilemap.set_cells_terrain_connect(0, [Vector2i(5, 3)], 0, 0)
# Parameters: layer, cells array, terrain_set, terrain index

Física en los tiles

Para añadir colisión a los tiles:

1. Añade una Physics Layer en el Inspector del TileSet.
2. Configura qué capa y máscara de colisión usa esta capa de física.
3. En el editor de TileSet, cambia a la pestaña Physics y dibuja polígonos de colisión en cada tile.

Datos personalizados en los tiles

Las capas de datos personalizados te permiten adjuntar metadatos tipados a cualquier tile. Esto resulta extremadamente útil para la lógica de juego.

Configurar datos personalizados

1. En el Inspector del TileSet, añade una Custom Data Layer.
2. Nómbrala (por ejemplo, «is_destructible») y establece el tipo (por ejemplo, bool).
3. En el editor de TileSet, cambia a la pestaña Custom Data y establece los valores por tile.

Leer datos personalizados en código

var tile_data = tilemap.get_cell_tile_data(0, Vector2i(5, 3))
if tile_data:
    var is_destructible = tile_data.get_custom_data("is_destructible")
    var damage = tile_data.get_custom_data("damage")
    if is_destructible:
        destroy_tile(Vector2i(5, 3))

Ejemplos habituales de datos personalizados:

• is_destructible: bool
• damage: int
• movement_cost: float
• tile_type: String (por ejemplo, "water", "lava", "ice")
• spawn_chance: float

Colocación procedural de tiles

Colocar tiles mediante código es sencillo con la nueva API:

# Fill a rectangular area
for x in range(20):
    for y in range(10):
        tilemap.set_cell(0, Vector2i(x, y), 0, Vector2i(0, 0))

# Random tile placement
for x in range(50):
    for y in range(50):
        if randf() > 0.7:
            tilemap.set_cell(0, Vector2i(x, y), 0, Vector2i(1, 0))
        else:
            tilemap.set_cell(0, Vector2i(x, y), 0, Vector2i(0, 0))

# Get all used cells on a layer
var used_cells: Array[Vector2i] = tilemap.get_used_cells(0)
print("Layer 0 has ", used_cells.size(), " tiles")

# Clear all tiles on a layer
tilemap.clear_layer(0)

# Clear everything
tilemap.clear()

Conversión de coordenadas de mundo a mapa

# Convert world position to map coordinates
var map_pos: Vector2i = tilemap.local_to_map(world_position)

# Convert map coordinates to world position (center of tile)
var world_pos: Vector2 = tilemap.map_to_local(Vector2i(5, 3))

# Example: check what tile the player is standing on
var player_tile = tilemap.local_to_map(tilemap.to_local(player.global_position))
var tile_data = tilemap.get_cell_tile_data(0, player_tile)
if tile_data:
    var tile_type = tile_data.get_custom_data("tile_type")
    print("Player is on: ", tile_type)

Migración desde Godot 3

Errores comunes

1. Olvidar crear primero un TileSet. El nodo TileMap no mostrará el editor de tiles hasta que asignes un recurso TileSet. Crea uno en el Inspector.

2. source_id incorrecto. Si solo tienes una fuente de atlas, su source_id es 0. Añadir una segunda fuente le asigna source_id = 1. Revisa el panel inferior del editor de TileSet — cada pestaña de fuente muestra su ID.

3. Confundir atlas_coords con IDs de tile. En Godot 4 no existen los IDs de tile simples. En su lugar, referencias los tiles por su posición en la cuadrícula del atlas como Vector2i(column, row).

4. No especificar el parámetro de capa. Cada operación de celda requiere un índice de capa como primer argumento. Olvidarlo provoca errores de argumentos.

5. Usar set_cellv(). Este método ya no existe. Usa set_cell() con la nueva firma.