Nhập liệu

njin hỗ trợ bàn phím, chuột, tay cầm và nhập văn bản. Có ba cách dùng, từ trực tiếp đến linh hoạt:

Cách	Khi nào dùng
Hỏi thẳng thiết bị (key_*, mouse_*, pad_*)	Việc nhanh, cố định
Action: một tên logic, đúng hoặc sai	"Nhảy", "bắn": nút bấm
Axis: một tên logic, giá trị -1 đến 1	"Đi ngang", "đi dọc": chuyển động

Action và axis cho phép đổi phím sau này mà không sửa logic.

Trạng thái nút

Trạng thái mọi thiết bị được đọc một lần đầu mỗi frame và giữ nguyên trong suốt frame đó, nên mọi system trong một frame thấy cùng một kết quả. Mọi nút (phím, chuột, tay cầm) dùng chung một quy tắc, ba hàm cho ba câu hỏi:

Hàm	Đúng khi
*_pressed	Nút vừa được nhấn ở frame này (chỉ một frame)
*_held	Nút đã được giữ từ frame trước và vẫn đang giữ
*_released	Nút vừa được thả ở frame này (chỉ một frame)

Ví dụ một lần nhấn giữ 3 frame rồi thả:

Frame	Người dùng	pressed	held	released
1	chưa ấn	–	–	–
2	nhấn xuống	✔	–	–
3	vẫn giữ	–	✔	–
4	vẫn giữ	–	✔	–
5	thả ra	–	–	✔

Ghi chú

Một phím được nhấn rồi nhả giữa hai frame (gõ cực nhanh) vẫn được tính: *_pressed đúng ở frame đó và *_released đúng ở frame sau.

Lưu ý

Ở frame nhấn đầu tiên (frame 2), *_held trả về false. Muốn biết "nút đang được ấn", dùng *_pressed(...) || *_held(...).

Bàn phím

njin::key_pressed(), njin::key_held(), njin::key_released() nhận một njin::key_code: chữ cái, số, F1 đến F12, mũi tên, phím điều hướng, ký hiệu, phím điều khiển (Shift, Ctrl, Alt, Windows) và bàn phím số.

Chuột

Hàm	Trả về
njin::mouse_pos()	Vị trí con trỏ, pixel màn hình
njin::mouse_delta()	Độ dời so với frame trước
njin::mouse_wheel()	Số nấc cuộn, dương là cuộn ra xa người dùng. Đa số frame là 0
njin::mouse_pressed() / njin::mouse_held() / njin::mouse_released()	Nút chuột (njin::mouse_button), cùng quy tắc như phím

Ghi chú

njin::mouse_pos() là pixel màn hình, không qua camera. Đổi sang vị trí trong thế giới bằng njin::scr2w(): xem Camera.

Tay cầm

Tay cầm được đánh số từ 0 đến njin::gamepad_max - 1. Tay cầm chưa cắm không gây lỗi: mọi hàm đọc như không nhấn và trả về 0.

Hàm	Việc làm
njin::pad_available()	Tay cầm có đang cắm không
njin::pad_pressed() / njin::pad_held() / njin::pad_released()	Nút tay cầm (njin::gamepad_button)
njin::pad_axis()	Trục analog (njin::gamepad_axis), từ -1 đến 1
njin::pad_set_deadzone()	Vùng chết của cần, mặc định 0.15

• Tên nút mặt theo vị trí: pad_face_down là A trên Xbox và Cross trên PlayStation.
• Giá trị trục đã qua vùng chết và được co giãn lại: vừa qua vùng chết thì đọc gần 0 và đạt 1 ở mép, nên không bị nhảy bậc.
• Cò (pad_axis_left_trigger, pad_axis_right_trigger) nghỉ ở -1 và đọc 1 khi nhấn hết, theo quy ước của raylib.

Nhập văn bản

Gõ chữ và bấm phím tắt là hai câu hỏi khác nhau. njin::key_pressed() cho biết phím nào được nhấn; njin::text_count() và njin::text_char() cho biết ký tự nào được gõ, đã qua bố cục bàn phím và phím chết. Ô nhập văn bản cần loại thứ hai:

#include <njin.h>
#include <string>
 
namespace {
bool menu_open = true;
std::string typed;
 
// Nhập văn bản: dùng text_count/text_char, không dùng key_pressed. Ký tự đã qua
// bố cục bàn phím, nên gõ dấu tiếng Việt hay chữ hoa vẫn đúng.
void read_text(njin::context &ctx) {
  for (njin::i32 i = 0; i < njin::text_count(ctx); i++) {
    const njin::i32 codepoint = njin::text_char(ctx, i);
    if (codepoint >= 32 && codepoint < 127) // ví dụ chỉ nhận ASCII
      typed.push_back((char)codepoint);
  }
  if (njin::key_pressed(ctx, njin::key_backspace) && !typed.empty())
    typed.pop_back();
  if (njin::key_pressed(ctx, njin::key_enter)) {
    NJIN_INFO("đã gõ: %s", typed.c_str());
    typed.clear();
  }
}
 
// Menu chạy TRƯỚC thế giới và nuốt cú nhấp, để thế giới bên dưới không nhận
// cùng cú nhấp đó.
void menu_click(njin::context &ctx) {
  if (menu_open && njin::mouse_pressed(ctx, njin::mouse_left)) {
    NJIN_INFO("menu nhận cú nhấp");
    njin::mouse_consume(ctx, njin::mouse_left);
  }
}
 
void world_click(njin::context &ctx) {
  // Khi menu đã nuốt cú nhấp, hàm này trả về false.
  if (njin::mouse_pressed(ctx, njin::mouse_left))
    NJIN_INFO("thế giới nhận cú nhấp");
}
 
void setup(njin::context &ctx) {
  njin::ecs_register(ctx, njin::phase_update, read_text);
  njin::ecs_register(ctx, njin::phase_pre_update, menu_click);
  njin::ecs_register(ctx, njin::phase_update, world_click);
}
} // namespace
 
njin::mod_desc text_consume_module() {
  return {.name = "text_consume", .setup = setup};
}

Mã trả về là Unicode. Mỗi frame nhận tối đa 32 ký tự.

Consume: nuốt input

njin::key_consume(), njin::mouse_consume() và njin::mouse_wheel_consume() xóa trạng thái của một nút trong phần còn lại của frame. System chạy sau đó không thấy nút đó nữa. Dùng khi một menu cần nuốt cú nhấp trước khi thế giới bên dưới xử lý cùng cú nhấp đó (xem ví dụ trên).

Hiệu lực không kéo dài quá frame gọi nó, vì trạng thái được đọc lại ở frame sau. Consume cũng không làm sai lịch sử của nút: một phím đang giữ bị consume thì ở frame sau vẫn là "đang giữ", không bị tính là vừa nhấn lại. Muốn system menu chạy trước, đặt nó ở phase sớm hơn (phase_pre_update) hoặc dùng thứ tự after/before: xem Module, system và phase.

Action

Action là một tên logic (ví dụ "fire") gắn với một hoặc nhiều nguồn: phím, nút chuột, nút tay cầm. Nguồn nào thỏa cũng làm action thỏa. Game hỏi về action thay vì phím, nên đổi phím sau này không phải sửa logic.

Hàm	Việc làm
njin::action_define()	Tạo action và gắn mọi nguồn trong một dòng: action_define(ctx, "jump", {key_space, key_w, pad_face_down}). Cách nên dùng
njin::action_register()	Tạo action trống. Nếu tên đã có thì trả về action cũ
njin::action_find()	Tìm action theo tên
njin::action_bind_key()	Gắn thêm một phím
njin::action_bind_mouse()	Gắn thêm một nút chuột
njin::action_bind_pad()	Gắn thêm một nút tay cầm (bất kỳ tay cầm nào đang cắm)
njin::action_clear_binds()	Xóa mọi nguồn đã gắn. Dùng được ở mọi lúc
njin::action_pressed() / njin::action_held() / njin::action_released()	Cùng quy tắc như phím

Đổi phím trong lúc chạy là gọi njin::action_clear_binds() rồi bind lại.

Axis

Axis đọc giá trị từ -1 đến 1. Nó tách khỏi action vì hai thứ trả lời hai câu hỏi khác nhau: action là đúng hoặc sai, axis là mức độ.

Hàm	Việc làm
njin::axis_define()	Tạo axis và gắn mọi cặp phím, trục tay cầm trong một dòng: axis_define(ctx, "move", {{key_left, key_right}, {key_a, key_d}}, {pad_axis_left_x}). Cách nên dùng
njin::axis_register() / njin::axis_find()	Tạo axis trống, và tìm axis theo tên
njin::axis_bind_keys()	Gắn một cặp phím: chỉ phím âm thì -1, chỉ phím dương thì 1, cả hai hoặc không phím nào thì 0
njin::axis_bind_pad()	Gắn một trục tay cầm
njin::axis_clear_binds()	Xóa mọi nguồn đã gắn
njin::axis_value()	Giá trị hiện tại

Nguồn lệch xa vị trí nghỉ nhất thì thắng: cần đẩy nửa chừng không bị cặp phím đang đứng yên làm phẳng, và cặp phím đang giữ không bị cần không ai chạm chặn lại.

Không có axis dạng vector 2 chiều. Đọc hai axis rồi ghép lại: chỉ bạn biết có cần chuẩn hóa vector đó hay không (đi chéo có nhanh hơn không).

Ví dụ hoàn chỉnh

Di chuyển bằng phím hoặc cần trái, bắn bằng phím cách, chuột trái hoặc nút A:

#include <njin.h>
 
namespace {
njin::axis_handle move_x;
njin::axis_handle move_y;
njin::action_handle fire;
 
void bind(njin::context &ctx) {
  // Một axis có thể nhận cả cặp phím lẫn cần analog. Nguồn nào lệch xa vị trí
  // nghỉ nhất thì thắng.
  move_x = njin::axis_register(ctx, "move_x");
  njin::axis_bind_keys(ctx, move_x, njin::key_a, njin::key_d);
  njin::axis_bind_pad(ctx, move_x, njin::pad_axis_left_x);
 
  move_y = njin::axis_register(ctx, "move_y");
  njin::axis_bind_keys(ctx, move_y, njin::key_w, njin::key_s);
  njin::axis_bind_pad(ctx, move_y, njin::pad_axis_left_y);
 
  // Một action nhận cả phím, nút chuột và nút tay cầm.
  fire = njin::action_register(ctx, "fire");
  njin::action_bind_key(ctx, fire, njin::key_space);
  njin::action_bind_mouse(ctx, fire, njin::mouse_left);
  njin::action_bind_pad(ctx, fire, njin::pad_face_down);
 
  // Vùng chết của cần analog, mặc định 0.15.
  njin::pad_set_deadzone(ctx, 0.2f);
}
 
void steer(njin::context &ctx) {
  // Hai axis đọc cùng nhau là một vector. Có chuẩn hóa hay không do bạn quyết.
  const njin::vec2 direction{njin::axis_value(ctx, move_x),
                             njin::axis_value(ctx, move_y)};
  (void)direction;
 
  if (njin::action_pressed(ctx, fire)) {
    // Chuột tính bằng pixel màn hình; scr2w đổi sang vị trí trong thế giới.
    const njin::vec2 target = njin::scr2w(ctx, njin::mouse_pos(ctx));
    NJIN_INFO("bắn tới %.0f, %.0f", target.x, target.y);
  }
 
  // Nút và cần của một tay cầm cụ thể.
  if (njin::pad_available(ctx, 0)) {
    if (njin::pad_pressed(ctx, 0, njin::pad_start))
      NJIN_INFO("Start");
    const njin::f32 trigger = njin::pad_axis(ctx, 0, njin::pad_axis_right_trigger);
    (void)trigger; // -1 khi nghỉ, 1 khi nhấn hết
  }
 
  // Bánh xe chuột: dương là cuộn ra xa người dùng.
  const njin::f32 wheel = njin::mouse_wheel(ctx);
  if (wheel != 0.0f)
    NJIN_INFO("cuộn %.1f nấc", wheel);
}
 
void setup(njin::context &ctx) {
  njin::ecs_register(ctx, njin::phase_startup, bind);
  njin::ecs_register(ctx, njin::phase_update, steer);
}
} // namespace
 
njin::mod_desc input_devices_module() {
  return {.name = "input_devices", .setup = setup};
}

Xem thêm ví dụ action đơn giản hơn:

#include <njin.h>
 
namespace {
njin::action_handle move_left;
njin::action_handle move_right;
 
void bind_keys(njin::context &ctx) {
  // Một action có thể có nhiều phím.
  move_left = njin::action_register(ctx, "move_left");
  njin::action_bind_key(ctx, move_left, njin::key_a);
  njin::action_bind_key(ctx, move_left, njin::key_left);
 
  move_right = njin::action_register(ctx, "move_right");
  njin::action_bind_key(ctx, move_right, njin::key_d);
  njin::action_bind_key(ctx, move_right, njin::key_right);
}
 
// Phím đang được ấn = vừa nhấn xuống (pressed) hoặc đã giữ từ frame trước (held).
bool is_down(const njin::context &ctx, njin::action_handle action) {
  return njin::action_pressed(ctx, action) || njin::action_held(ctx, action);
}
 
void steer(njin::context &ctx) {
  njin::f32 direction = 0.0f;
  if (is_down(ctx, move_left))
    direction -= 1.0f;
  if (is_down(ctx, move_right))
    direction += 1.0f;
 
  if (njin::key_pressed(ctx, njin::key_space))
    NJIN_INFO("nhảy! hướng hiện tại: %.0f", direction);
}
 
void setup(njin::context &ctx) {
  njin::ecs_register(ctx, njin::phase_startup, bind_keys);
  njin::ecs_register(ctx, njin::phase_update, steer);
}
} // namespace
 
njin::mod_desc input_demo_module() {
  return {.name = "input_demo", .setup = setup};
}

Danh sách phím và nút

Mọi mã nằm trong njin::key_code, njin::mouse_button, njin::gamepad_button và njin::gamepad_axis.