TileMap in Godot 4 — Vollständiger Leitfaden

Einführung

Godot 4 hat das TileMap-System komplett neu geschrieben. Wenn du TileMap in Godot 3 verwendet hast, hat sich fast alles geändert — der TileSet-Editor, wie Kacheln definiert werden, Auto-Tiling, Ebenen und die GDScript-API. Dieser Leitfaden erklärt die neue Architektur von Grund auf.

Die neue TileMap-Architektur

Das TileMap-System von Godot 4 besteht aus zwei Hauptkomponenten:

• TileMap-Node — Der Node, den du deiner Szene hinzufügst. Er enthält eine oder mehrere Ebenen und referenziert eine TileSet-Ressource.
• TileSet-Ressource — Definiert die Kacheln selbst. Enthält Quellen (Atlas, Szenensammlung usw.), Physik-Ebenen, Navigations-Ebenen, benutzerdefinierte Datenebenen und Terrain-Sets.

TileSet-Quellen

Ein TileSet kann mehrere Quellen haben, die jeweils durch eine source_id (Ganzzahl) identifiziert werden. Zu den Quellentypen gehören:

• TileSetAtlasSource — Der häufigste Typ. Ein einzelnes Texturbild, das mehrere in einem Raster angeordnete Kacheln enthält.
• TileSetScenesCollectionSource — Jede Kachel ist eine gepackte Szene, nützlich für animierte oder interaktive Kacheln.

Ein TileSet einrichten

Schritt 1: Die TileSet-Ressource erstellen

1. Füge deiner Szene einen TileMap-Node hinzu.
2. Klicke im Inspektor auf die Eigenschaft Tile Set und wähle New TileSet.
3. Lege die Tile Size fest (z. B. 16x16 oder 32x32).

Schritt 2: Eine Atlas-Quelle hinzufügen

1. Klicke auf das TileSet, um den TileSet-Editor im unteren Panel zu öffnen.
2. Klicke auf die Schaltfläche + und wähle Atlas.
3. Ziehe dein Tileset-Bild in die Eigenschaft Texture.
4. Der Editor teilt es automatisch anhand deiner Kachelgröße in Kacheln auf. Du kannst die Texturregion und die Ränder anpassen.

Schritt 3: Kacheleigenschaften konfigurieren

Im TileSet-Editor kannst du verschiedene Ebenentypen hinzufügen, die für alle Kacheln gelten:

• Physics Layers — Kollisionsformen für Kacheln
• Navigation Layers — Begehbare Polygone für Wegfindung
• Custom Data Layers — Beliebige typisierte Daten (bool, int, float, String usw.)
• Terrain Sets — Für Auto-Tiling (der Ersatz für Godot 3 autotile)

TileMap-Ebenen

Ein einzelner TileMap-Node kann mehrere Ebenen enthalten. Das ist eine große Verbesserung gegenüber Godot 3, wo du separate TileMap-Nodes für Hintergrund und Vordergrund brauchtest. Jede Ebene kann ihre eigenen z-index-, y-sort- und modulate-Einstellungen haben.

Übliche Ebenen-Konfiguration:

• Layer 0 — Hintergrund (Boden, Fußboden) — z-index: -1
• Layer 1 — Terrain (Wände, Hindernisse) — z-index: 0
• Layer 2 — Vordergrund (Dekoration über dem Spieler) — z-index: 1

GDScript-API für Ebenen

# 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")

Terrain-System (Auto-Tiling)

Das Terrain-System ersetzt das autotile von Godot 3. Es wählt automatisch die richtige Kachelvariante basierend auf den benachbarten Kacheln aus.

Terrains einrichten

1. Füge in TileSet ein Terrain Set hinzu (Inspektor → Terrain Sets → Add Element).
2. Wähle den Terrain-Modus: Match Corners and Sides (47 Kacheln), Match Corners (16 Kacheln) oder Match Sides (16 Kacheln).
3. Füge Terrain-Typen innerhalb des Sets hinzu (z. B. „Grass", „Dirt", „Water").
4. Wechsle im TileSet-Editor in den Select-Modus, wähle eine Kachel aus und male die Terrain-Peering-Bits auf jede Kachel.

Terrains malen

Sobald die Terrains konfiguriert sind, wechsle zum TileMap-Editor und wähle den Tab Terrains. Wähle deinen Terrain-Typ und male direkt auf die Karte. Godot wählt automatisch die richtige Kachelvariante aus.

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

Physik auf Kacheln

Um Kollision zu Kacheln hinzuzufügen:

1. Füge im TileSet-Inspektor eine Physics Layer hinzu.
2. Konfiguriere, welche Kollisions-Layer und -Maske diese Physik-Ebene verwendet.
3. Wechsle im TileSet-Editor zum Tab Physics und zeichne Kollisionspolygone auf jede Kachel.

Benutzerdefinierte Daten auf Kacheln

Benutzerdefinierte Datenebenen ermöglichen es dir, typisierte Metadaten an jede Kachel anzuhängen. Das ist für Gameplay-Logik äußerst nützlich.

Benutzerdefinierte Daten einrichten

1. Füge im TileSet-Inspektor eine Custom Data Layer hinzu.
2. Benenne sie (z. B. „is_destructible") und lege den Typ fest (z. B. bool).
3. Wechsle im TileSet-Editor zum Tab Custom Data und setze Werte pro Kachel.

Benutzerdefinierte Daten im Code auslesen

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

Häufige Beispiele für benutzerdefinierte Daten:

• is_destructible: bool
• damage: int
• movement_cost: float
• tile_type: String (z. B. "water", "lava", "ice")
• spawn_chance: float

Prozedurale Kachelplatzierung

Das programmatische Platzieren von Kacheln ist mit der neuen API unkompliziert:

# 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()

Umrechnung von Welt- zu Kartenkoordinaten

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

Migration von Godot 3

Häufige Fehler

1. Vergessen, zuerst ein TileSet zu erstellen. Der TileMap-Node zeigt den Kacheleditor erst an, wenn du eine TileSet-Ressource zuweist. Erstelle eine im Inspektor.

2. Falsche source_id. Wenn du nur eine Atlas-Quelle hast, ist ihre source_id gleich 0. Das Hinzufügen einer zweiten Quelle gibt ihr source_id = 1. Prüfe das untere Panel des TileSet-Editors — jeder Quellen-Tab zeigt seine ID an.

3. atlas_coords mit Kachel-IDs verwechseln. In Godot 4 gibt es keine einfachen Kachel-IDs. Stattdessen referenzierst du Kacheln über ihre Position im Atlas-Raster als Vector2i(column, row).

4. Den Ebenen-Parameter nicht angeben. Jede Zelloperation benötigt einen Ebenenindex als erstes Argument. Ihn zu vergessen verursacht Argumentfehler.

5. set_cellv() verwenden. Diese Methode existiert nicht mehr. Verwende set_cell() mit der neuen Signatur.