TileMap di Godot 4 — Panduan Lengkap

Pengantar

Godot 4 menulis ulang sistem TileMap sepenuhnya. Jika kamu menggunakan TileMap di Godot 3, hampir semuanya berubah — editor TileSet, cara tile didefinisikan, auto-tiling, layer, dan API GDScript. Panduan ini membahas arsitektur baru dari awal.

Arsitektur TileMap Baru

Sistem TileMap Godot 4 memiliki dua komponen utama:

• Node TileMap — Node yang kamu tambahkan ke scene-mu. Ia menampung satu atau lebih layer dan mereferensikan sebuah resource TileSet.
• Resource TileSet — Mendefinisikan tile-nya sendiri. Berisi sumber (atlas, koleksi scene, dll.), layer fisika, layer navigasi, layer data kustom, dan terrain set.

Sumber TileSet

Sebuah TileSet dapat memiliki beberapa sumber, masing-masing diidentifikasi oleh sebuah source_id (bilangan bulat). Jenis sumber meliputi:

• TileSetAtlasSource — Jenis yang paling umum. Sebuah gambar tekstur tunggal yang berisi banyak tile yang tersusun dalam grid.
• TileSetScenesCollectionSource — Setiap tile adalah sebuah packed scene, berguna untuk tile animasi atau interaktif.

Menyiapkan TileSet

Langkah 1: Buat Resource TileSet

1. Tambahkan sebuah node TileMap ke scene-mu.
2. Di Inspector, klik properti Tile Set dan pilih New TileSet.
3. Atur Tile Size (mis. 16x16 atau 32x32).

Langkah 2: Tambahkan Sumber Atlas

1. Klik TileSet untuk membuka editor TileSet di panel bawah.
2. Klik tombol + dan pilih Atlas.
3. Seret gambar tileset-mu ke properti Texture.
4. Editor secara otomatis membaginya menjadi tile berdasarkan ukuran tile-mu. Kamu dapat menyesuaikan region tekstur dan margin.

Langkah 3: Konfigurasi Properti Tile

Di editor TileSet, kamu dapat menambahkan berbagai jenis layer yang berlaku untuk semua tile:

• Physics Layers — Bentuk kolisi untuk tile
• Navigation Layers — Poligon yang dapat dilalui untuk pathfinding
• Custom Data Layers — Data bertipe sembarang (bool, int, float, String, dll.)
• Terrain Sets — Untuk auto-tiling (pengganti autotile Godot 3)

Layer TileMap

Satu node TileMap dapat berisi beberapa layer. Ini adalah peningkatan besar dibanding Godot 3, di mana kamu memerlukan node TileMap terpisah untuk latar belakang dan latar depan. Setiap layer dapat memiliki pengaturan z-index, y-sort, dan modulate-nya sendiri.

Konfigurasi layer yang umum:

• Layer 0 — Latar belakang (tanah, lantai) — z-index: -1
• Layer 1 — Terrain (dinding, rintangan) — z-index: 0
• Layer 2 — Latar depan (dekorasi di atas pemain) — z-index: 1

API GDScript untuk Layer

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

Sistem Terrain (Auto-Tiling)

Sistem terrain menggantikan autotile Godot 3. Ia secara otomatis memilih varian tile yang benar berdasarkan tile-tile tetangganya.

Menyiapkan Terrain

1. Di TileSet, tambahkan sebuah Terrain Set (Inspector → Terrain Sets → Add Element).
2. Pilih mode terrain: Match Corners and Sides (47 tile), Match Corners (16 tile), atau Match Sides (16 tile).
3. Tambahkan jenis terrain di dalam set (mis. "Grass", "Dirt", "Water").
4. Di editor TileSet, beralih ke mode Select, pilih sebuah tile, lalu cat bit peering terrain pada setiap tile.

Mengecat Terrain

Setelah terrain dikonfigurasi, beralih ke editor TileMap dan pilih tab Terrains. Pilih jenis terrain-mu dan cat langsung di map. Godot akan otomatis memilih varian tile yang benar.

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

Fisika pada Tile

Untuk menambahkan kolisi ke tile:

1. Tambahkan sebuah Physics Layer di Inspector TileSet.
2. Konfigurasikan collision layer dan mask mana yang digunakan physics layer ini.
3. Di editor TileSet, beralih ke tab Physics dan gambar poligon kolisi pada setiap tile.

Data Kustom pada Tile

Custom data layer memungkinkan kamu melampirkan metadata bertipe ke tile mana pun. Ini sangat berguna untuk logika gameplay.

Menyiapkan Data Kustom

1. Di Inspector TileSet, tambahkan sebuah Custom Data Layer.
2. Beri nama (mis. "is_destructible") dan atur tipenya (mis. bool).
3. Di editor TileSet, beralih ke tab Custom Data dan atur nilai per tile.

Membaca Data Kustom dalam Kode

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

Contoh data kustom yang umum:

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

Penempatan Tile Prosedural

Menempatkan tile secara programatik sangat mudah dengan API baru:

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

Konversi Koordinat Dunia ke Map

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

Migrasi dari Godot 3

Kesalahan Umum

1. Lupa membuat TileSet terlebih dahulu. Node TileMap tidak akan menampilkan editor tile hingga kamu menetapkan resource TileSet. Buat satu di Inspector.

2. source_id yang salah. Jika kamu hanya memiliki satu sumber atlas, source_id-nya adalah 0. Menambahkan sumber kedua memberinya source_id = 1. Periksa panel bawah editor TileSet — setiap tab sumber menampilkan ID-nya.

3. Mengacaukan atlas_coords dengan ID tile. Di Godot 4, tidak ada ID tile sederhana. Sebagai gantinya, kamu mereferensikan tile berdasarkan posisinya dalam grid atlas sebagai Vector2i(column, row).

4. Tidak menentukan parameter layer. Setiap operasi sel memerlukan indeks layer sebagai argumen pertama. Melupakannya menyebabkan kesalahan argumen.

5. Menggunakan set_cellv(). Metode ini tidak ada lagi. Gunakan set_cell() dengan signature baru.