Scene

Scene là một trạng thái lớn của game: menu, đang chơi, tạm dừng, game over. Mỗi lúc chỉ có một scene chạy.

#include <njin.h>
 
namespace {
njin::scene_handle menu, play;
 
// Chạy một lần khi vào scene "play": tạo thế giới của màn chơi.
void enter_play(njin::context &ctx) {
  entt::registry &reg = njin::world(ctx);
  for (int i = 0; i < 10; i++) {
    const entt::entity e = reg.create();
    reg.emplace<njin::transform>(e, njin::transform{.pos = {i * 40.0f, 100}});
    // Rời scene "play" thì engine tự hủy entity này.
    reg.emplace<njin::scene_owned>(e, njin::scene_owned{play});
  }
}
 
void menu_update(njin::context &ctx) {
  if (njin::key_pressed(ctx, njin::key_enter))
    njin::scene_set(ctx, play); // chuyển ở đầu frame sau
}
 
void play_update(njin::context &ctx) {
  if (njin::key_pressed(ctx, njin::key_escape))
    njin::scene_set(ctx, menu);
}
 
void draw_menu(njin::context &ctx) {
  njin::draw_text(ctx, "Press Enter", {20, 20}, 30, njin::colors::white);
}
 
void setup(njin::context &ctx) {
  // Đăng ký scene trước, để dùng handle trong sys_desc.
  menu = njin::scene_register(ctx, {.name = "menu"});
  play = njin::scene_register(ctx, {.name = "play", .on_enter = enter_play});
 
  // Mỗi system chỉ chạy trong scene của nó.
  njin::ecs_register(ctx, njin::phase_update, njin::sys_desc{.fnc = menu_update, .scene = menu});
  njin::ecs_register(ctx, njin::phase_update, njin::sys_desc{.fnc = play_update, .scene = play});
  njin::ecs_register(ctx, njin::phase_post_render, njin::sys_desc{.fnc = draw_menu, .scene = menu});
  njin::ecs_register(ctx, njin::phase_startup,
                     [](njin::context &c) { njin::scene_set(c, menu); });
}
} // namespace
 
njin::mod_desc scenes_module() { return {.name = "scenes", .setup = setup}; }

Ba việc scene làm cho bạn

1. System chỉ chạy trong một scene. Đặt scene trong njin::sys_desc. System không đặt scene (handle id 0) chạy ở mọi scene.

2. Gọi hàm khi vào và rời scene. on_enter và on_exit trong njin::scene_desc, mỗi hàm chạy đúng một lần mỗi lần chuyển. Đây là chỗ tạo thế giới của màn chơi và lưu điểm.

3. Tự hủy entity của scene. Gắn njin::scene_owned vào entity; khi rời scene đó, engine hủy nó. Không phải tự dọn.

Chuyển scene

njin::scene_set() không chuyển ngay mà ở đầu frame sau, trước mọi system của frame đó. Frame hiện tại vì thế chạy trọn vẹn trong một scene.

Khi chuyển, engine lần lượt:

1. gọi on_exit của scene cũ,
2. hủy mọi entity có njin::scene_owned trỏ tới scene cũ,
3. gọi on_enter của scene mới.

Scene đầu tiên cũng được đặt bằng njin::scene_set(), thường trong phase_startup. Trước đó chưa có scene nào: chỉ system không gắn scene chạy.

Hàm	Việc làm
njin::scene_register()	Tạo scene. Tên đã có thì trả về scene cũ
njin::scene_find()	Tìm scene theo tên
njin::scene_set()	Chuyển scene ở đầu frame sau
njin::scene_current()	Scene đang chạy

Chuyển cảnh mờ dần

njin::scene_fade() đổi scene sau một hiệu ứng mờ dần, và có thể hiện màn hình loading:

#include <njin.h>
 
namespace {
njin::scene_handle menu{}, level{};
njin::texture_handle level_art{};
 
void draw_loading(njin::context &ctx) {
  const njin::vec2 screen = njin::screen_size(ctx);
  njin::draw_text(ctx, "Đang tải...", {screen.x - 220.0f, screen.y - 60.0f}, 32.0f,
                  njin::colors::white);
}
 
void enter_level(njin::context &ctx) {
  // Nạp nặng ở đây: người chơi đang thấy màn hình loading, không phải cửa sổ đứng hình.
  level_art = njin::texture_load(ctx, "assets/level1.png");
}
 
void exit_level(njin::context &ctx) { njin::texture_unload(ctx, level_art); }
 
void startup(njin::context &ctx) {
  menu = njin::scene_register(ctx, {.name = "menu"});
  level = njin::scene_register(ctx, {.name = "level", .on_enter = enter_level,
                                     .on_exit = exit_level});
  njin::scene_set(ctx, menu);
}
 
void menu_input(njin::context &ctx) {
  // Bỏ qua phím trong lúc đang chuyển, để không bấm hai lần.
  if (!njin::scene_transitioning(ctx) && njin::key_pressed(ctx, njin::key_enter))
    njin::scene_fade(ctx, level, {.fade_out = 0.4f, .hold = 0.3f, .fade_in = 0.6f,
                                  .draw_loading = draw_loading});
}
 
void level_input(njin::context &ctx) {
  if (njin::key_pressed(ctx, njin::key_escape))
    njin::scene_fade(ctx, menu, {.color = {1.0f, 1.0f, 1.0f, 1.0f}}); // mờ sang trắng
}
 
void setup(njin::context &ctx) {
  njin::ecs_register(ctx, njin::phase_startup, startup);
  njin::ecs_register(ctx, njin::phase_update, {.fnc = menu_input, .scene = menu});
  njin::ecs_register(ctx, njin::phase_update, {.fnc = level_input, .scene = level});
}
} // namespace
 
njin::mod_desc scene_fade_module() { return {.name = "scene_fade", .setup = setup}; }

flowchart LR
  A["Phủ dần<br/>fade_out giây"]:::engine --> B["Phủ kín:<br/>vẽ màn loading<br/>ít nhất một frame"]:::engine --> C["on_exit cũ,<br/>on_enter mới<br/>(nạp tài nguyên)"]:::update --> D["Giữ kín<br/>ít nhất hold giây"]:::engine --> E["Mở dần<br/>fade_in giây"]:::engine

• Màn hình loading (draw_loading) được vẽ trước khi on_enter của scene mới chạy, nên on_enter nạp tài nguyên nặng thì người chơi vẫn thấy nó, không thấy cửa sổ đứng hình.
• Thời gian tính theo giờ thật: pause và time_set_scale() không ảnh hưởng.
• Game vẫn chạy trong lúc chuyển. Dùng njin::scene_transitioning() để bỏ qua nhập liệu nếu cần.
• Gọi lại njin::scene_fade() khi đang chuyển thì chỉ đổi scene đích. njin::scene_set() khi đang chuyển thì hủy hiệu ứng và đổi ngay frame sau.
• Lớp phủ nằm trên mọi thứ, kể cả UI.

Hàm	Việc làm
njin::scene_fade()	Chuyển scene với hiệu ứng mờ dần
njin::scene_transitioning()	Đang chuyển không
njin::scene_transition_cover()	Độ phủ hiện tại, 0..1

Scene hay tạm dừng?

Menu tạm dừng thường không nên là một scene riêng: chuyển scene sẽ hủy thế giới đang chơi. Hãy giữ scene "play" và dùng njin::time_set_paused() (xem Thời gian, fixed update, timer và tween), rồi vẽ menu khi đang dừng. Game Pong trong src/games/pong làm theo cách này.