TileMap trong Godot 4 — Hướng dẫn đầy đủ

Giới thiệu

Godot 4 đã viết lại hoàn toàn hệ thống TileMap. Nếu bạn từng dùng TileMap trong Godot 3, thì gần như mọi thứ đã thay đổi — trình chỉnh sửa TileSet, cách định nghĩa tile, auto-tiling, layer và GDScript API. Hướng dẫn này trình bày kiến trúc mới từ đầu.

Kiến trúc TileMap mới

Hệ thống TileMap của Godot 4 gồm hai thành phần chính:

• Node TileMap — Node bạn thêm vào scene. Nó chứa một hoặc nhiều layer và tham chiếu đến một tài nguyên TileSet.
• Tài nguyên TileSet — Định nghĩa chính các tile. Chứa nguồn (atlas, bộ sưu tập scene, v.v.), layer vật lý, layer điều hướng, layer dữ liệu tùy chỉnh và terrain set.

Nguồn TileSet

Một TileSet có thể có nhiều nguồn, mỗi nguồn được xác định bằng một source_id (số nguyên). Các loại nguồn bao gồm:

• TileSetAtlasSource — Loại phổ biến nhất. Một ảnh texture đơn chứa nhiều tile được sắp xếp theo lưới.
• TileSetScenesCollectionSource — Mỗi tile là một packed scene, hữu ích cho các tile có hoạt ảnh hoặc tương tác.

Thiết lập một TileSet

Bước 1: Tạo tài nguyên TileSet

1. Thêm một node TileMap vào scene của bạn.
2. Trong Inspector, nhấp vào thuộc tính Tile Set và chọn New TileSet.
3. Đặt Tile Size (ví dụ: 16x16 hoặc 32x32).

Bước 2: Thêm một nguồn atlas

1. Nhấp vào TileSet để mở trình chỉnh sửa TileSet ở panel phía dưới.
2. Nhấp vào nút + và chọn Atlas.
3. Kéo ảnh tileset của bạn vào thuộc tính Texture.
4. Trình chỉnh sửa tự động chia ảnh thành các tile dựa trên kích thước tile của bạn. Bạn có thể điều chỉnh vùng texture và lề (margin).

Bước 3: Cấu hình thuộc tính tile

Trong trình chỉnh sửa TileSet, bạn có thể thêm nhiều loại layer áp dụng cho tất cả các tile:

• Physics Layers — Hình dạng va chạm cho tile
• Navigation Layers — Đa giác có thể đi lại cho việc tìm đường
• Custom Data Layers — Dữ liệu có kiểu tùy ý (bool, int, float, String, v.v.)
• Terrain Sets — Dùng cho auto-tiling (phần thay thế cho autotile của Godot 3)

Layer TileMap

Một node TileMap đơn có thể chứa nhiều layer. Đây là một cải tiến lớn so với Godot 3, nơi bạn cần các node TileMap riêng biệt cho nền và tiền cảnh. Mỗi layer có thể có cài đặt z-index, y-sort và modulate riêng.

Cấu hình layer thông thường:

• Layer 0 — Nền (mặt đất, sàn) — z-index: -1
• Layer 1 — Địa hình (tường, chướng ngại vật) — z-index: 0
• Layer 2 — Tiền cảnh (vật trang trí phía trên người chơi) — z-index: 1

GDScript API cho 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")

Hệ thống terrain (Auto-Tiling)

Hệ thống terrain thay thế autotile của Godot 3. Nó tự động chọn biến thể tile đúng dựa trên các tile lân cận.

Thiết lập terrain

1. Trong TileSet, thêm một Terrain Set (Inspector → Terrain Sets → Add Element).
2. Chọn chế độ terrain: Match Corners and Sides (47 tile), Match Corners (16 tile) hoặc Match Sides (16 tile).
3. Thêm các loại terrain trong set (ví dụ: "Grass", "Dirt", "Water").
4. Trong trình chỉnh sửa TileSet, chuyển sang chế độ Select, chọn một tile và vẽ các bit peering terrain lên từng tile.

Vẽ terrain

Sau khi terrain đã được cấu hình, chuyển sang trình chỉnh sửa TileMap và chọn tab Terrains. Chọn loại terrain của bạn và vẽ trực tiếp lên bản đồ. Godot sẽ tự động chọn biến thể tile đúng.

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

Vật lý trên tile

Để thêm va chạm cho tile:

1. Thêm một Physics Layer trong Inspector của TileSet.
2. Cấu hình collision layer và mask nào mà layer vật lý này sử dụng.
3. Trong trình chỉnh sửa TileSet, chuyển sang tab Physics và vẽ các đa giác va chạm lên từng tile.

Dữ liệu tùy chỉnh trên tile

Các layer dữ liệu tùy chỉnh cho phép bạn đính kèm metadata có kiểu vào bất kỳ tile nào. Điều này cực kỳ hữu ích cho logic gameplay.

Thiết lập dữ liệu tùy chỉnh

1. Trong Inspector của TileSet, thêm một Custom Data Layer.
2. Đặt tên cho nó (ví dụ: "is_destructible") và đặt kiểu (ví dụ: bool).
3. Trong trình chỉnh sửa TileSet, chuyển sang tab Custom Data và đặt giá trị cho từng tile.

Đọc dữ liệu tùy chỉnh trong code

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

Các ví dụ dữ liệu tùy chỉnh thường gặp:

• is_destructible: bool
• damage: int
• movement_cost: float
• tile_type: String (ví dụ: "water", "lava", "ice")
• spawn_chance: float

Đặt tile theo thủ tục

Việc đặt tile bằng lập trình rất đơn giản với API mới:

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

Chuyển đổi tọa độ world sang 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)

Chuyển đổi từ Godot 3

Các lỗi thường gặp

1. Quên tạo TileSet trước. Node TileMap sẽ không hiển thị trình chỉnh sửa tile cho đến khi bạn gán một tài nguyên TileSet. Hãy tạo một cái trong Inspector.

2. Sai source_id. Nếu bạn chỉ có một nguồn atlas, thì source_id của nó là 0. Thêm nguồn thứ hai sẽ cho nó source_id = 1. Kiểm tra panel phía dưới của trình chỉnh sửa TileSet — mỗi tab nguồn hiển thị ID của nó.

3. Nhầm lẫn atlas_coords với tile ID. Trong Godot 4, không có tile ID đơn giản. Thay vào đó, bạn tham chiếu tile theo vị trí của chúng trong lưới atlas dưới dạng Vector2i(column, row).

4. Không chỉ định tham số layer. Mọi thao tác trên cell đều yêu cầu chỉ số layer làm đối số đầu tiên. Quên nó sẽ gây lỗi đối số.

5. Dùng set_cellv(). Phương thức này không còn tồn tại. Hãy dùng set_cell() với chữ ký mới.