Tilemap

Tilemap là lưới ô vuông vẽ từ một tileset (một ảnh gồm các ô cùng kích thước). Dùng cho bản đồ platformer, RPG, thế giới đào xới.

#include <njin.h>
 
namespace {
constexpr njin::vec2 player_size{12, 14};
constexpr njin::f32 gravity = 900.0f;
constexpr njin::f32 jump_speed = 330.0f;
 
entt::entity level = entt::null;
njin::vec2 player_pos{40, 0};
njin::vec2 player_vel{};
bool on_ground = false;
 
void build(njin::context &ctx) {
  entt::registry &reg = njin::world(ctx);
  njin::tilemap map;
  map.tileset = njin::texture_load(ctx, "assets/tiles.png");
  map.tile_size = {16, 16};
 
  // Không cần khai báo kích thước: đặt ô ở đâu, chunk ở đó được tạo.
  for (int x = -20; x < 400; x++)
    njin::tilemap_set(map, x, 10, 1); // mặt đất dài 420 ô, trải qua 14 chunk
  for (int y = 6; y < 10; y++)
    njin::tilemap_set(map, 15, y, 2); // một bức tường
  njin::tilemap_set(map, 8, 7, 3);    // một bục nhỏ
 
  level = reg.create();
  reg.emplace<njin::transform>(level, njin::transform{.pos = {0, 0}});
  reg.emplace<njin::tilemap>(level, std::move(map));
}
 
// Vật lý platformer trong phase cố định: kết quả không phụ thuộc FPS.
void physics(njin::context &ctx) {
  entt::registry &reg = njin::world(ctx);
  const auto &map = reg.get<njin::tilemap>(level);
  const njin::vec2 origin = reg.get<njin::transform>(level).pos;
  const njin::f32 dt = njin::delta(ctx); // đúng một nhịp cố định
 
  njin::f32 dir = 0;
  if (njin::key_pressed(ctx, njin::key_left) || njin::key_held(ctx, njin::key_left))
    dir -= 1;
  if (njin::key_pressed(ctx, njin::key_right) || njin::key_held(ctx, njin::key_right))
    dir += 1;
  player_vel.x = dir * 140.0f;
  player_vel.y += gravity * dt;
  if (on_ground && njin::key_pressed(ctx, njin::key_space))
    player_vel.y = -jump_speed;
 
  // Đi ngang trước rồi dọc: trượt dọc tường thay vì dính vào.
  const njin::move_result mv = njin::tilemap_move(
      map, origin, njin::rect{player_pos, player_size}, player_vel * dt);
  player_pos = mv.pos;
  on_ground = mv.hit_y && player_vel.y > 0;
  if (mv.hit_y)
    player_vel.y = 0;
}
 
// Đào ô bằng chuột: tilemap_set đánh dấu chunk cần vẽ lại.
void dig(njin::context &ctx) {
  if (!njin::mouse_pressed(ctx, njin::mouse_left))
    return;
  entt::registry &reg = njin::world(ctx);
  auto &map = reg.get<njin::tilemap>(level);
  const njin::vec2 origin = reg.get<njin::transform>(level).pos;
  const njin::vec2 world_pos = njin::scr2w(ctx, njin::mouse_pos(ctx));
  const njin::cell c = njin::tilemap_cell_at(map, origin, world_pos);
  njin::tilemap_set(map, c.x, c.y, -1);
}
 
void draw_player(njin::context &ctx) {
  njin::draw_rect(ctx, njin::rect{player_pos, player_size}, njin::colors::yellow);
}
 
void setup(njin::context &ctx) {
  njin::ecs_register(ctx, njin::phase_startup, build);
  njin::ecs_register(ctx, njin::phase_fixed_update, physics);
  njin::ecs_register(ctx, njin::phase_update, dig);
  njin::ecs_register(ctx, njin::phase_render, draw_player);
}
} // namespace
 
njin::mod_desc platformer_module() { return {.name = "platformer", .setup = setup}; }

Tạo tilemap

Gắn njin::transform và njin::tilemap vào một entity. transform.pos là góc trên trái của ô (0, 0) trong thế giới.

• tileset, tile_size: ảnh và kích thước một ô.
• Mỗi ô giữ số thứ tự ô trong tileset (từ 0, theo hàng), hoặc -1 là ô trống.
• Đổi ô bằng njin::tilemap_set(), đọc bằng njin::tilemap_get().
• layer, tint, visible như sprite.

Tilemap không có kích thước cố định và tọa độ ô có thể âm: đặt ô ở đâu thì bản đồ mở rộng tới đó.

Viết bản đồ bằng chữ

Không muốn dùng Tiled hay LDtk? Viết bản đồ như ngày xưa: mỗi ký tự là một ô. njin::tilemap_from_text() đọc một chuỗi nhiều dòng (viết thẳng trong code, hoặc đọc từ một file văn bản bằng njin::file_read()), còn njin::tilemap_from_rows() nhận từng hàng riêng cho bản đồ nhỏ.

#include <njin.h>
 
namespace {
using namespace njin;
 
void startup(context &ctx) {
  const axis_handle move_x = axis_define(ctx, "move_x", {{key_left, key_right}, {key_a, key_d}}, {pad_axis_left_x});
  const axis_handle move_y = axis_define(ctx, "move_y", {{key_up, key_down}, {key_w, key_s}}, {pad_axis_left_y});
  const action_handle dash = action_define(ctx, "dash", {key_space, pad_face_down});
 
  entt::registry &reg = world(ctx);
 
  // 1. Bản đồ viết bằng chữ, mỗi ký tự một ô: # là tường đá (ô 7), . là cỏ (ô 0), P là chỗ nhân vật
  //    xuất hiện. P vừa đặt ô cỏ 0 bên dưới, vừa được báo lại (tham số thứ ba là true).
  tilemap map;
  map.tileset = texture_load(ctx, "assets/tiles.png");
  texture_set_filter(ctx, map.tileset, filter_nearest);
  tilemap_set_shape(map, 0, tile_none); // cỏ chỉ để nhìn, đi qua được
  const std::vector<tile_marker> markers = tilemap_from_text(map, R"(
####################
#..................#
#..P...............#
#..................#
#..................#
#.....####.........#
#..................#
#..................#
#..................#
#..................#
#..................#
####################
)", {{'#', 7}, {'.', 0}, {'P', 0, true}});
 
  vec2 start{};
  for (const tile_marker &m : markers)
    if (m.symbol == 'P') {
      const rect r = tilemap_cell_rect(map, {0.0f, 0.0f}, m.at.x, m.at.y); // ô -> hình chữ nhật trong thế giới
      start = {r.pos.x + r.size.x * 0.5f, r.pos.y + r.size.y};             // chân ở đáy ô
    }
 
  const entt::entity level = reg.create();
  reg.emplace<transform>(level);
  reg.emplace<tilemap>(level, std::move(map));
  reg.emplace<collider>(level, collider{.shape = collider_tiles}); // đá thành vật cản
 
  // 2. Nhân vật ở đúng chỗ chữ P.
  const entt::entity player = reg.create();
  reg.emplace<transform>(player, transform{.pos = start});
  reg.emplace<collider>(player, collider{.size = {10.0f, 8.0f}, .offset = {0.0f, -4.0f}});
  reg.emplace<topdown_body>(player, topdown_body{.dash_speed = 230.0f});
  reg.emplace<topdown_input_map>(player, topdown_input_map{move_x, move_y, dash});
 
  // 3. Camera bám nhân vật, không lộ ra ngoài bản đồ (20 x 12 ô, mỗi ô 16 pixel).
  const rect bounds{{0.0f, 0.0f}, {320.0f, 192.0f}};
  reg.emplace<camera_follow>(camera_spawn(ctx, 3.0f), camera_follow{.target = player, .bounds = bounds});
}
 
void draw_player(context &ctx) {
  world(ctx).view<transform, collider, topdown_body>().each(
      [&](const transform &tr, const collider &col, const topdown_body &) {
        draw_rect(ctx, rect_from_center(tr.pos + col.offset, col.size), colors::yellow);
      });
}
 
void setup(context &ctx) {
  ecs_register(ctx, phase_startup, startup);
  ecs_register(ctx, phase_render, draw_player);
}
} // namespace
 
int main() {
  context *ctx = create({.title = "Bản đồ bằng chữ", .width = 960, .height = 540, .target_fps = 60});
  mod_register(*ctx, {.name = "game", .setup = setup});
  run(*ctx);
  destroy(ctx);
}

Tham số thứ ba là bảng ký tự (njin::tile_key): ký tự nào đặt ô số mấy. Ở ví dụ trên # là ô 7 (tường đá) và . là ô 0 (cỏ). Ký tự không có trong bảng thì có hai trường hợp:

• , . và tab là ô trống;
• mọi ký tự khác là điểm đánh dấu: hàm không đặt ô nào, mà trả về vị trí của nó trong một danh sách njin::tile_marker (theo thứ tự đọc, từ trên xuống và trái sang phải). Đây là chỗ để đặt điểm xuất hiện của người chơi (P), kẻ địch (E), đồng xu, cửa... Tự tạo entity ở đúng ô đó; njin::tilemap_cell_rect() đổi ô thành vị trí trong thế giới.

Một ký tự có thể vừa đặt ô vừa được báo lại: {'P', 0, true} đặt ô cỏ 0 dưới chân nhân vật và báo vị trí của P, để không có lỗ hổng dưới người chơi.

Quy tắc	Chi tiết
Vị trí	Dòng đầu là hàng 0, ký tự đầu là cột 0, cộng thêm tham số origin nếu có. Các hàng dài ngắn khác nhau được
Dòng đầu chuỗi	Nếu chuỗi bắt đầu bằng xuống dòng thì xuống dòng đó bị bỏ, để viết R"( rồi xuống dòng mới đến hàng đầu. Dòng cuối kết thúc bằng xuống dòng không thêm hàng rỗng
Kết thúc dòng Windows	\r\n được hiểu đúng, không có ký tự \r lạc
Chồng lớp	Ô trống và điểm đánh dấu không đụng tới ô đang có, nên gọi nhiều lần cho nhiều lớp (nền, rồi vật trang trí). Muốn xóa một ô, ghi rõ trong bảng: {'x', -1}
Hình va chạm	Ký tự trong bảng gọi njin::tilemap_set(), nên njin::tilemap_set_shape() và njin::tilemap_animate() áp dụng như bình thường

Ghi chú

Bản đồ chữ chỉ dựng ô và báo vị trí. Nó không tạo entity, không có thuộc tính hay đối tượng như Tiled/LDtk (xem Level từ Tiled và LDtk). Muốn có những thứ đó thì đọc danh sách njin::tile_marker rồi tạo entity, hoặc dùng njin::prefab_spawn() (Prefab và transform cha–con) cho từng ký tự. Muốn lưu bản đồ ra file thì ghi lại chính chuỗi chữ.

Chunking

Ô được lưu và vẽ theo chunk: khối 32 x 32 ô (njin::tile_chunk_size).

flowchart LR
  S["tilemap_set()"]:::api --> C[("chunk.version tăng")]:::data
  C --> B["post_update: bake lại<br/>chunk đó vào ảnh riêng"]:::update
  B --> D["render: mỗi chunk trong<br/>khung nhìn = 1 lệnh vẽ"]:::render

Lưu trữ thưa. Chỉ những chunk có ít nhất một ô mới tồn tại. Một bản đồ rộng hàng nghìn ô nhưng thưa vẫn nhẹ. Xóa hết ô của một chunk thì chunk bị xóa.

Vẽ sẵn (bake). Mỗi chunk được vẽ một lần vào một ảnh riêng. Mỗi frame, chunk chỉ tốn một lệnh vẽ thay vì 1024 lệnh cho từng ô. Chunk chỉ được vẽ lại khi có ô đổi: mỗi chunk có số version tăng lên mỗi lần njin::tilemap_set() đổi nó.

Chỉ vẽ những gì nhìn thấy. Chỉ chunk nằm trong khung nhìn của camera (njin::camera_bounds()) mới được bake và vẽ.

Giải phóng. Ảnh của chunk khuất khỏi màn hình khoảng 5 giây (300 frame) bị giải phóng, và được bake lại khi quay lại. Ảnh của chunk hay tilemap đã bị xóa được giải phóng ngay frame sau.

Đổi ô sau khi đã bake. Chunk vừa đổi trong frame này (ví dụ trong phase_render) sẽ được vẽ từng ô một lần cho đúng, rồi được bake lại ở frame sau. Không bao giờ hiện ảnh cũ.

Lưu ý

Luôn đổi ô bằng njin::tilemap_set(). Sửa thẳng tilemap::chunks thì engine không biết chunk nào cần vẽ lại.

Va chạm với tilemap

Mọi ô không trống đều là vật cản.

Hàm	Việc làm
njin::tilemap_cell_at()	Ô chứa một điểm trong thế giới
njin::tilemap_cell_rect()	Hình chữ nhật của một ô trong thế giới
njin::tilemap_overlaps()	Một hình chữ nhật có chạm ô nào không
njin::tilemap_move()	Di chuyển một hình chữ nhật, dừng khi đụng ô

njin::tilemap_move() đi theo trục ngang trước rồi đến trục dọc, nên nhân vật trượt dọc tường thay vì dính vào. hit_y && delta.y > 0 nghĩa là đang đứng trên mặt đất.

Cần va chạm với cả tilemap lẫn các entity khác (thùng, cửa, quái) thì gắn collider collider_tiles lên tilemap và dùng njin::collision_move(), xem Va chạm.

Ghi chú

Mỗi lần gọi, mỗi trục nên dời không quá một ô. Vật đi quá nhanh có thể xuyên qua tường mỏng. Đặt vật lý trong phase_fixed_update để bước đi nhỏ và đều (xem Thời gian, fixed update, timer và tween).

Hình va chạm và animation của ô

Mỗi loại ô có thể có hình va chạm riêng (bục một chiều, dốc, không va chạm) và animation (nước, đuốc). Cả hai đặt theo số thứ tự ô, nên áp dụng cho mọi ô cùng loại:

njin::tilemap_set_shape(map, 3, njin::tile_one_way);
njin::tilemap_set_shape(map, 4, njin::tile_slope_r);
njin::tilemap_animate(map, 10, {10, 11, 12, 13}, 0.18f); // ô 10 chạy qua bốn frame

Bản đồ nạp từ Tiled và LDtk có sẵn cả hai (xem Level từ Tiled và LDtk). Ô có animation không bị bake vào ảnh chunk mà vẽ chồng lên mỗi frame, nên chunk tĩnh vẫn rẻ. collision_move() và collision_raycast() hiểu hình của ô; tilemap_move() thì coi mọi ô là vật cản. Xem Làm game platformer để dùng chúng.