TileMap w Godot 4 — Kompletny przewodnik

Wprowadzenie

Godot 4 całkowicie przepisał system TileMap. Jeśli używałeś TileMap w Godot 3, zmieniło się niemal wszystko — edytor TileSet, sposób definiowania kafelków, auto-kafelkowanie, warstwy oraz API GDScript. Ten przewodnik omawia nową architekturę od podstaw.

Nowa architektura TileMap

System TileMap w Godot 4 składa się z dwóch głównych komponentów:

• Węzeł TileMap — Węzeł dodawany do sceny. Przechowuje jedną lub więcej warstw i odwołuje się do zasobu TileSet.
• Zasób TileSet — Definiuje same kafelki. Zawiera źródła (atlas, kolekcja scen itp.), warstwy fizyki, warstwy nawigacji, niestandardowe warstwy danych oraz zestawy terenu.

Źródła TileSet

TileSet może mieć wiele źródeł, z których każde jest identyfikowane przez source_id (liczba całkowita). Typy źródeł obejmują:

• TileSetAtlasSource — Najczęstszy typ. Pojedynczy obraz tekstury zawierający wiele kafelków ułożonych w siatkę.
• TileSetScenesCollectionSource — Każdy kafelek jest spakowaną sceną, przydatne dla kafelków animowanych lub interaktywnych.

Konfiguracja TileSet

Krok 1: Utwórz zasób TileSet

1. Dodaj do sceny węzeł TileMap.
2. W inspektorze kliknij właściwość Tile Set i wybierz New TileSet.
3. Ustaw Tile Size (np. 16x16 lub 32x32).

Krok 2: Dodaj źródło atlasu

1. Kliknij TileSet, aby otworzyć edytor TileSet w dolnym panelu.
2. Kliknij przycisk + i wybierz Atlas.
3. Przeciągnij obraz zestawu kafelków do właściwości Texture.
4. Edytor automatycznie podzieli go na kafelki na podstawie rozmiaru kafelka. Możesz dostosować region tekstury i marginesy.

Krok 3: Skonfiguruj właściwości kafelków

W edytorze TileSet możesz dodawać różne typy warstw, które dotyczą wszystkich kafelków:

• Physics Layers — Kształty kolizji dla kafelków
• Navigation Layers — Wielokąty do chodzenia dla wyszukiwania ścieżek
• Custom Data Layers — Dowolne dane typowane (bool, int, float, String itp.)
• Terrain Sets — Do auto-kafelkowania (następca autotile z Godot 3)

Warstwy TileMap

Pojedynczy węzeł TileMap może zawierać wiele warstw. To duże ulepszenie względem Godot 3, gdzie potrzebowałeś osobnych węzłów TileMap dla tła i pierwszego planu. Każda warstwa może mieć własne ustawienia z-index, y-sort i modulate.

Typowa konfiguracja warstw:

• Layer 0 — Tło (grunt, podłoga) — z-index: -1
• Layer 1 — Teren (ściany, przeszkody) — z-index: 0
• Layer 2 — Pierwszy plan (dekoracja nad graczem) — z-index: 1

API GDScript dla warstw

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

System terenu (auto-kafelkowanie)

System terenu zastępuje autotile z Godot 3. Automatycznie wybiera właściwy wariant kafelka na podstawie sąsiadujących kafelków.

Konfiguracja terenów

1. W TileSet dodaj Terrain Set (Inspektor → Terrain Sets → Add Element).
2. Wybierz tryb terenu: Match Corners and Sides (47 kafelków), Match Corners (16 kafelków) lub Match Sides (16 kafelków).
3. Dodaj typy terenu w obrębie zestawu (np. „Grass", „Dirt", „Water").
4. W edytorze TileSet przełącz się w tryb Select, wybierz kafelek i namaluj bity powiązań terenu na każdym kafelku.

Malowanie terenów

Gdy tereny są już skonfigurowane, przełącz się do edytora TileMap i wybierz kartę Terrains. Wybierz typ terenu i maluj bezpośrednio na mapie. Godot automatycznie wybierze właściwy wariant kafelka.

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

Fizyka na kafelkach

Aby dodać kolizję do kafelków:

1. Dodaj Physics Layer w inspektorze TileSet.
2. Skonfiguruj, której warstwy i maski kolizji używa ta warstwa fizyki.
3. W edytorze TileSet przełącz się na kartę Physics i narysuj wielokąty kolizji na każdym kafelku.

Dane niestandardowe na kafelkach

Niestandardowe warstwy danych pozwalają dołączyć typowane metadane do dowolnego kafelka. Jest to niezwykle przydatne dla logiki rozgrywki.

Konfiguracja danych niestandardowych

1. W inspektorze TileSet dodaj Custom Data Layer.
2. Nadaj jej nazwę (np. „is_destructible") i ustaw typ (np. bool).
3. W edytorze TileSet przełącz się na kartę Custom Data i ustaw wartości dla poszczególnych kafelków.

Odczyt danych niestandardowych w kodzie

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

Częste przykłady danych niestandardowych:

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

Proceduralne rozmieszczanie kafelków

Programowe rozmieszczanie kafelków jest proste dzięki nowemu 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()

Konwersja współrzędnych świat–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)

Migracja z Godot 3

Częste błędy

1. Zapominanie o utworzeniu najpierw TileSet. Węzeł TileMap nie pokaże edytora kafelków, dopóki nie przypiszesz zasobu TileSet. Utwórz go w inspektorze.

2. Błędne source_id. Jeśli masz tylko jedno źródło atlasu, jego source_id to 0. Dodanie drugiego źródła nadaje mu source_id = 1. Sprawdź dolny panel edytora TileSet — każda karta źródła pokazuje swój identyfikator.

3. Mylenie atlas_coords z identyfikatorami kafelków. W Godot 4 nie ma prostych identyfikatorów kafelków. Zamiast tego odwołujesz się do kafelków przez ich pozycję w siatce atlasu jako Vector2i(column, row).

4. Niepodanie parametru warstwy. Każda operacja na komórce wymaga indeksu warstwy jako pierwszego argumentu. Pominięcie go powoduje błędy argumentów.

5. Używanie set_cellv(). Ta metoda już nie istnieje. Użyj set_cell() z nową sygnaturą.