Debug

Cổng debug cho njin_inspector: số liệu, entity, watches, log, điều khiển thời gian, gizmo. Tiếp...

Classes
struct	njin::debug_server_desc
	Cách mở cổng debug, dùng với debug_server_start(). Tiếp...
struct	njin::render_info
	Những gì frame vừa rồi đã vẽ, cho màn hình debug của chính game. Tiếp...

Typedefs
using	njin::debug_component_fn = std::function<json_value(const entt::registry &, entt::entity)>
	Hàm chuyển một component thành JSON để inspector hiện giá trị của nó.

Các hàm
bool	njin::debug_server_start (context &ctx, const debug_server_desc &desc={})
	Mở cổng debug để chương trình njin_inspector (một process riêng) kết nối vào: FPS, biểu đồ thời gian frame, danh sách entity và component, khung collider vẽ trên bản đồ, log, giá trị theo dõi, và điều khiển thời gian (dừng, chạy từng frame, tua chậm) và quay cửa sổ game thành file GIF (xem Quay màn hình).
void	njin::debug_server_stop (context &ctx)
	Đóng cổng debug và ngắt inspector đang kết nối.
bool	njin::debug_server_connected (const context &ctx)
	Có inspector nào đang kết nối không.
void	njin::debug_watch (context &ctx, const char *name, json_value value)
	Đặt một giá trị để xem trực tiếp trong bảng "Watches" của inspector: vận tốc nhân vật, trạng thái AI, số quái còn sống.
void	njin::debug_watch (context &ctx, const char *name, vec2 value)
	Như debug_watch() cho một vec2.
void	njin::debug_component (context &ctx, entt::id_type type, const char *name, debug_component_fn fn, std::size_t bytes=0)
	Đăng ký cách hiện một loại component.
template<class T, class Fn>
void	njin::debug_component (context &ctx, const char *name, Fn fn)
	Đăng ký cách hiện component T của game bằng một hàm nhận const T &.
render_info	njin::render_info_get (const context &ctx)
	Số liệu vẽ của frame vừa rồi.

Gizmo
Hình vẽ để debug: đường, mũi tên, khung, nhãn chữ, trong thế giới 2D hoặc 3D. Gọi được ở mọi phase (cả phase_update và phase_fixed_update), không cần nằm trong lúc vẽ: engine gom lại và vẽ đè lên trên cùng của thế giới (không bị hình nào che), đường mảnh 1 pixel, chữ cỡ cố định trên màn hình. Gizmo 2D vẽ qua camera 2D; gizmo 3D vẽ ở end_3d() qua camera của lần vẽ 3D đó (không có begin_3d() thì không hiện). Khi njin_inspector đang nối, gizmo cũng hiện trong ô World của nó. duration là số giây gizmo còn hiện: 0 (mặc định) là chỉ frame này, nên gọi lại mỗi frame; lớn hơn để giữ lại một vết (đường đạn, điểm va chạm). njin::gizmo_arrow(ctx, pos, pos + velocity * 0.2f, njin::colors::yellow); njin::gizmo_text(ctx, pos + njin::vec2{0, -20}, "đang nhảy"); njin::gizmo_box3d(ctx, enemy_pos, {1, 2, 1}, njin::colors::red); njin::gizmo_line3d(ctx, muzzle, hit, njin::colors::yellow, 1.0f); // giữ 1 giây
void	njin::gizmo_line (context &ctx, vec2 a, vec2 b, rgba color=colors::green, f32 duration=0.0f)
	Đoạn thẳng 2D.
void	njin::gizmo_arrow (context &ctx, vec2 from, vec2 to, rgba color=colors::green, f32 duration=0.0f)
	Mũi tên 2D từ from tới to.
void	njin::gizmo_rect (context &ctx, rect r, rgba color=colors::green, f32 duration=0.0f)
	Khung hình chữ nhật 2D.
void	njin::gizmo_circle (context &ctx, vec2 center, f32 radius, rgba color=colors::green, f32 duration=0.0f)
	Đường tròn 2D.
void	njin::gizmo_point (context &ctx, vec2 p, rgba color=colors::green, f32 duration=0.0f)
	Một điểm 2D: dấu chữ thập nhỏ, cỡ cố định trên màn hình.
void	njin::gizmo_text (context &ctx, vec2 pos, const char *text, rgba color=colors::white, f32 duration=0.0f)
	Nhãn chữ tại một điểm của thế giới 2D, cỡ cố định trên màn hình.
void	njin::gizmo_line3d (context &ctx, vec3 a, vec3 b, rgba color=colors::green, f32 duration=0.0f)
	Đoạn thẳng 3D.
void	njin::gizmo_arrow3d (context &ctx, vec3 from, vec3 to, rgba color=colors::green, f32 duration=0.0f)
	Mũi tên 3D từ from tới to.
void	njin::gizmo_box3d (context &ctx, vec3 center, vec3 size, rgba color=colors::green, f32 duration=0.0f)
	Khung hộp 3D, các cạnh song song với trục.
void	njin::gizmo_sphere3d (context &ctx, vec3 center, f32 radius, rgba color=colors::green, f32 duration=0.0f)
	Khung cầu 3D: ba đường tròn lớn.
void	njin::gizmo_axes3d (context &ctx, vec3 pos, f32 size=1.0f, f32 duration=0.0f)
	Ba trục tọa độ tại pos: x đỏ, y xanh lá, z xanh dương.
void	njin::gizmo_point3d (context &ctx, vec3 p, rgba color=colors::green, f32 duration=0.0f)
	Một điểm 3D: dấu chữ thập nhỏ, cỡ cố định trên màn hình.
void	njin::gizmo_text3d (context &ctx, vec3 pos, const char *text, rgba color=colors::white, f32 duration=0.0f)
	Nhãn chữ gắn vào một điểm 3D, cỡ cố định trên màn hình.
void	njin::gizmos_set_visible (context &ctx, bool visible)
	Bật hay tắt việc vẽ gizmo.
bool	njin::gizmos_visible (const context &ctx)
	Gizmo có đang được vẽ không.

Mô tả chi tiết

Cổng debug cho njin_inspector: số liệu, entity, watches, log, điều khiển thời gian, gizmo.

Thông tin về hàm

debug_server_start()

bool njin::debug_server_start	(	context &	ctx,
		const debug_server_desc &	desc = {} )

Mở cổng debug để chương trình njin_inspector (một process riêng) kết nối vào: FPS, biểu đồ thời gian frame, danh sách entity và component, khung collider vẽ trên bản đồ, log, giá trị theo dõi, và điều khiển thời gian (dừng, chạy từng frame, tua chậm) và quay cửa sổ game thành file GIF (xem Quay màn hình).

Game không vẽ gì thêm: mọi giao diện debug nằm ở cửa sổ inspector. Chỉ nghe trên 127.0.0.1, nên máy khác không kết nối được; không có inspector nào kết nối thì chi phí gần như bằng không. Không bao giờ chặn game: inspector chậm thì dữ liệu bị bỏ bớt chứ game không đứng.

Thường chỉ bật trong bản debug:

#ifndef NDEBUG
  njin::debug_server_start(*ctx);
#endif

Log: khi một inspector đang kết nối, log đi sang inspector và không in ra console của game nữa; chưa có inspector (hoặc nó đã ngắt) thì log vẫn ra console như thường. Các dòng đã ra trước đó, kể cả lúc mở cửa sổ (tối đa 2000 dòng, chỉ tính từ create()), được gửi cho inspector ngay khi nó kết nối.

Các tham số

ctx	Context của engine.
desc	Cổng và nhịp gửi.

Giá trị trả về

false nếu cổng đang bị chiếm (ví dụ một bản game khác đang chạy).

debug_server_stop()

void njin::debug_server_stop

(

context &

ctx

)

Đóng cổng debug và ngắt inspector đang kết nối.

Các tham số

ctx	Context của engine.

debug_server_connected()

bool njin::debug_server_connected

(

const context &

ctx

)

Có inspector nào đang kết nối không.

Các tham số

ctx	Context của engine.

Giá trị trả về

true nếu có.

debug_watch() [1/2]

void njin::debug_watch	(	context &	ctx,
		const char *	name,
		json_value	value )

Đặt một giá trị để xem trực tiếp trong bảng "Watches" của inspector: vận tốc nhân vật, trạng thái AI, số quái còn sống.

Gọi mỗi frame hay mỗi khi đổi; giá trị cuối cùng được gửi theo nhịp snapshot_hz. Không có inspector thì không làm gì.

njin::debug_watch(ctx, "player.velocity", vel);
njin::debug_watch(ctx, "enemies alive", (njin::i32)enemies.size());

Các tham số

ctx	Context của engine.
name	Tên hiển thị.
value	Giá trị: số, bool, chuỗi, hoặc njin::json_value bất kỳ.

debug_watch() [2/2]

void njin::debug_watch	(	context &	ctx,
		const char *	name,
		vec2	value )

Như debug_watch() cho một vec2.

Các tham số

ctx	Context của engine.
name	Tên hiển thị.
value	Giá trị.

debug_component() [1/2]

void njin::debug_component	(	context &	ctx,
		entt::id_type	type,
		const char *	name,
		debug_component_fn	fn,
		std::size_t	bytes = 0 )

Đăng ký cách hiện một loại component.

Engine đã có sẵn cho mọi component của njin. Component của game không đăng ký vẫn hiện tên trong inspector, chỉ không có giá trị.

Các tham số

ctx	Context của engine.
type	Định danh kiểu của EnTT, entt::type_hash<T>::value().
name	Tên hiển thị.
fn	Hàm chuyển sang JSON.
bytes	Kích thước một component (sizeof), để bảng Memory của inspector tính bộ nhớ. 0 là chưa biết.

debug_component() [2/2]

template<class T, class Fn>

void njin::debug_component	(	context &	ctx,
		const char *	name,
		Fn	fn )

Đăng ký cách hiện component T của game bằng một hàm nhận const T &.

struct health { njin::i32 hp = 3, max = 3; };
njin::debug_component<health>(ctx, "health", [](const health &h) {
  return njin::json_value::make_object().set("hp", h.hp).set("max", h.max);
});

Template Parameters

T	Kiểu component.
Fn	Hàm hoặc lambda json_value(const T &).

Các tham số

ctx	Context của engine.
name	Tên hiển thị.
fn	Hàm chuyển sang JSON.

render_info_get()

render_info njin::render_info_get

(

const context &

ctx

)

Số liệu vẽ của frame vừa rồi.

Đọc trong phase_post_render (hoặc frame sau) thì có số của cả frame; đọc trước đó thì thiếu phần chưa vẽ.

Các tham số

ctx	Context của engine.

Giá trị trả về

Số liệu.

gizmo_line()

void njin::gizmo_line	(	context &	ctx,
		vec2	a,
		vec2	b,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Đoạn thẳng 2D.

Các tham số

ctx	Context của engine.
a	Điểm đầu, tọa độ thế giới.
b	Điểm cuối.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_arrow()

void njin::gizmo_arrow	(	context &	ctx,
		vec2	from,
		vec2	to,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Mũi tên 2D từ from tới to.

Các tham số

ctx	Context của engine.
from	Gốc.
to	Mũi.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_rect()

void njin::gizmo_rect	(	context &	ctx,
		rect	r,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Khung hình chữ nhật 2D.

Các tham số

ctx	Context của engine.
r	Hình chữ nhật, tọa độ thế giới.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_circle()

void njin::gizmo_circle	(	context &	ctx,
		vec2	center,
		f32	radius,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Đường tròn 2D.

Các tham số

ctx	Context của engine.
center	Tâm.
radius	Bán kính.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_point()

void njin::gizmo_point	(	context &	ctx,
		vec2	p,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Một điểm 2D: dấu chữ thập nhỏ, cỡ cố định trên màn hình.

Các tham số

ctx	Context của engine.
p	Vị trí.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_text()

void njin::gizmo_text	(	context &	ctx,
		vec2	pos,
		const char *	text,
		rgba	color = colors::white,
		f32	duration = 0.0f )

Nhãn chữ tại một điểm của thế giới 2D, cỡ cố định trên màn hình.

Các tham số

ctx	Context của engine.
pos	Vị trí góc trên trái của chữ.
text	Chữ (UTF-8). nullptr bị bỏ qua.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_line3d()

void njin::gizmo_line3d	(	context &	ctx,
		vec3	a,
		vec3	b,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Đoạn thẳng 3D.

Các tham số

ctx	Context của engine.
a	Điểm đầu.
b	Điểm cuối.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_arrow3d()

void njin::gizmo_arrow3d	(	context &	ctx,
		vec3	from,
		vec3	to,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Mũi tên 3D từ from tới to.

Các tham số

ctx	Context của engine.
from	Gốc.
to	Mũi.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_box3d()

void njin::gizmo_box3d	(	context &	ctx,
		vec3	center,
		vec3	size,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Khung hộp 3D, các cạnh song song với trục.

Các tham số

ctx	Context của engine.
center	Tâm.
size	Kích thước theo x, y, z.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_sphere3d()

void njin::gizmo_sphere3d	(	context &	ctx,
		vec3	center,
		f32	radius,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Khung cầu 3D: ba đường tròn lớn.

Các tham số

ctx	Context của engine.
center	Tâm.
radius	Bán kính.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_axes3d()

void njin::gizmo_axes3d	(	context &	ctx,
		vec3	pos,
		f32	size = 1.0f,
		f32	duration = 0.0f )

Ba trục tọa độ tại pos: x đỏ, y xanh lá, z xanh dương.

Các tham số

ctx	Context của engine.
pos	Gốc.
size	Độ dài mỗi trục.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_point3d()

void njin::gizmo_point3d	(	context &	ctx,
		vec3	p,
		rgba	color = colors::green,
		f32	duration = 0.0f )

Một điểm 3D: dấu chữ thập nhỏ, cỡ cố định trên màn hình.

Các tham số

ctx	Context của engine.
p	Vị trí.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmo_text3d()

void njin::gizmo_text3d	(	context &	ctx,
		vec3	pos,
		const char *	text,
		rgba	color = colors::white,
		f32	duration = 0.0f )

Nhãn chữ gắn vào một điểm 3D, cỡ cố định trên màn hình.

Không hiện khi điểm ở sau camera.

Các tham số

ctx	Context của engine.
pos	Vị trí.
text	Chữ (UTF-8). nullptr bị bỏ qua.
color	Màu.
duration	Số giây còn hiện. 0 là chỉ frame này.

gizmos_set_visible()

void njin::gizmos_set_visible	(	context &	ctx,
		bool	visible )

Bật hay tắt việc vẽ gizmo.

Mặc định bật. Khi tắt, các lệnh gizmo_* gần như không tốn gì; dùng để có một phím bật tắt, hoặc tắt trong bản phát hành.

Các tham số

ctx	Context của engine.
visible	true để vẽ.

gizmos_visible()

bool njin::gizmos_visible

(

const context &

ctx

)

Gizmo có đang được vẽ không.

Các tham số

ctx	Context của engine.

Giá trị trả về

Giá trị đặt bởi gizmos_set_visible().