Nhiễu, luật làm bản đồ tự nhiên, sinh màn top-down và platformer, Wave Function Collapse. Tiếp...

Classes
struct	njin::tile_grid
	Một lưới ô hình chữ nhật, kích thước cố định, để sinh và sửa bản đồ trước khi đưa vào njin::tilemap. Tiếp...
struct	njin::noise_desc
	Tham số của một nguồn nhiễu. Tiếp...
struct	njin::autotile_rule
	Một luật bo góc: những ô nào là cùng một địa hình và vẽ bằng bộ ô nào. Tiếp...
struct	njin::biome
	Một vùng đất của bản đồ top-down: ô nào đặt ở chỗ có độ cao và độ ẩm nào. Tiếp...
struct	njin::topdown_gen_desc
	Tham số sinh bản đồ top-down. Tiếp...
struct	njin::topdown_gen_result
	Kết quả của generate_topdown(). Tiếp...
struct	njin::platformer_gen_desc
	Tham số sinh màn platformer, nhìn ngang, đi từ trái sang phải. Tiếp...
struct	njin::platformer_gen_result
	Kết quả của generate_platformer(). Tiếp...
struct	njin::wfc_rules
	Luật của Wave Function Collapse: có những ô nào, mỗi ô hay gặp đến đâu, và ô nào được đứng cạnh ô nào theo từng hướng. Tiếp...
struct	njin::wfc_desc
	Tham số của wfc_generate(). Tiếp...

Enumerations
enum	njin::noise_type { njin::noise_perlin , njin::noise_value }
	Loại nhiễu cơ bản. Tiếp...
enum	njin::noise_fractal { njin::fractal_none , njin::fractal_fbm , njin::fractal_ridged , njin::fractal_billow }
	Cách chồng nhiều lớp nhiễu (octave) lên nhau. Tiếp...
enum	njin::grid_side : u8 { njin::side_up = 1 , njin::side_down = 2 , njin::side_left = 4 , njin::side_right = 8 , njin::side_all = 15 }
	Các phía của một ô, cộng lại được: side_up \| side_down. Tiếp...
enum	njin::autotile_layout { njin::autotile_edges , njin::autotile_blob }
	Bộ ô dùng để nối một loại địa hình với chính nó. Tiếp...
enum	njin::autotile_neighbor : u8 { njin::neighbor_up = 1 , njin::neighbor_up_right = 2 , njin::neighbor_right = 4 , njin::neighbor_down_right = 8 , njin::neighbor_down = 16 , njin::neighbor_down_left = 32 , njin::neighbor_left = 64 , njin::neighbor_up_left = 128 }
	Các ô kề, cộng lại thành mặt nạ (mask) của một ô. Tiếp...
enum	njin::wfc_dir { wfc_right , wfc_down , wfc_left , wfc_up }
	Hướng từ một ô sang ô bên cạnh, dùng cho luật kề của WFC.

Các hàm
tile_grid	njin::tile_grid_make (i32 width, i32 height, i32 fill=-1)
	Tạo một lưới width x height, mọi ô là fill.
tile_grid	njin::tile_grid_from_text (std::string_view text, std::initializer_list< tile_key > legend)
	Dựng lưới từ bản đồ chữ, cùng quy tắc với tilemap_from_text(): mỗi ký tự một ô, legend cho biết ký tự nào là ô nào.
void	njin::tilemap_from_grid (tilemap &map, const tile_grid &grid, cell origin={})
	Đặt lưới vào tilemap, góc trên trái ở ô origin.
i32	njin::grid_count (const tile_grid &grid, i32 tile)
	Số ô có giá trị tile.
f32	njin::noise_2d (const noise_desc &desc, f32 x, f32 y)
	Giá trị nhiễu tại một điểm, từ 0 đến 1.
f32	njin::noise_1d (const noise_desc &desc, f32 x)
	Nhiễu một chiều, từ 0 đến 1: đường mặt đất của platformer, độ cao theo cột.
void	njin::grid_majority (tile_grid &grid, i32 iterations=1, i32 threshold=5)
	Làm mượt: mỗi ô thành loại ô xuất hiện nhiều nhất trong ô 3 x 3 quanh nó, nếu loại đó có ít nhất threshold ô.
void	njin::grid_smooth (tile_grid &grid, i32 solid, i32 open, i32 iterations=3, i32 threshold=5)
	Làm mượt hai loại ô kiểu hang động (automat tế bào): một ô thành solid nếu ít nhất threshold trong 8 ô quanh nó là đặc, còn không thì thành open.
i32	njin::grid_remove_small (tile_grid &grid, i32 tile, i32 min_size, i32 replace)
	Xoá các vùng nhỏ của một loại ô: mỗi vùng liền nhau (theo 4 hướng) của tile có ít hơn min_size ô thì thành replace.
i32	njin::grid_merge_small (tile_grid &grid, i32 min_size)
	Như grid_remove_small() cho mọi loại ô: vùng nhỏ hơn min_size hoà vào loại ô bao quanh nó nhiều nhất.
i32	njin::grid_keep_largest (tile_grid &grid, std::initializer_list< i32 > walkable, i32 replace)
	Giữ mọi chỗ đi được liền một khối: trong các ô thuộc walkable, chỉ vùng liền nhau (4 hướng) lớn nhất được giữ, các vùng khác thành replace.
i32	njin::grid_border (tile_grid &grid, i32 tile, i32 touching, i32 replace, u8 sides=side_all, i32 distance=1)
	Viền: ô tile nằm cách touching không quá distance ô (theo các phía trong sides) thì thành replace.
i32	njin::grid_scatter (tile_grid &grid, i32 on, i32 place, f32 chance, u32 seed, i32 min_distance=0)
	Rải ngẫu nhiên: mỗi ô on có xác suất chance thành place, và hai ô được rải cách nhau ít nhất min_distance ô (0 là không giới hạn).
i32	njin::grid_scatter (tile_grid &grid, i32 place, f32 chance, u32 seed, const std::function< bool(const tile_grid &, i32, i32)> &where, i32 min_distance=0)
	Như bản trên, nhưng chỗ nào được rải do hàm where quyết định: bụi cây chỉ ở ô trống ngay trên mặt đất, đuốc chỉ trên tường...
i32	njin::autotile_count (autotile_layout layout)
	Số ô của một bộ.
i32	njin::autotile_index (u8 mask, autotile_layout layout=autotile_blob)
	Số thứ tự ô (trong bộ, từ 0) ứng với một mặt nạ.
i32	njin::grid_autotile (tile_grid &grid, const std::vector< autotile_rule > &rules)
	Thay mọi ô thuộc rules[i].tiles bằng ô của bộ tương ứng, chọn theo các ô kề: chỗ nào địa hình hở ra thì ô có mép, hai mép gặp nhau thì có góc tròn (lồi), chỗ địa hình lõm vào thì có góc lõm.
topdown_gen_result	njin::generate_topdown (const topdown_gen_desc &desc)
	Sinh bản đồ top-down từ nhiễu.
platformer_gen_result	njin::generate_platformer (const platformer_gen_desc &desc)
	Sinh màn platformer từ nhiễu.
i32	njin::wfc_add_tile (wfc_rules &rules, i32 tile, f32 weight=1.0f)
	Thêm một ô vào luật (hoặc đổi độ hay gặp nếu đã có).
void	njin::wfc_allow (wfc_rules &rules, i32 a, wfc_dir dir, i32 b)
	Cho phép b đứng ở hướng dir của a, và (đối xứng) a đứng ở hướng ngược lại của b.
wfc_rules	njin::wfc_learn (const tile_grid &sample, bool periodic=false)
	Học luật từ một mẫu: mọi cặp ô cạnh nhau trong mẫu thành luật kề, số lần xuất hiện thành độ hay gặp.
bool	njin::wfc_generate (const wfc_rules &rules, const wfc_desc &desc, tile_grid &out)
	Sinh một lưới thoả mọi luật kề, bằng Wave Function Collapse (mô hình ô, không quay lui: gặp mâu thuẫn thì làm lại từ đầu với dãy ngẫu nhiên khác, tối đa attempts lần).

Mô tả chi tiết

Nhiễu, luật làm bản đồ tự nhiên, sinh màn top-down và platformer, Wave Function Collapse.

Thông tin về Enumeration Type

◆ noise_type

enum njin::noise_type

Loại nhiễu cơ bản.

Enumerator
noise_perlin	Nhiễu gradient (Perlin): mượt, tròn trịa. Mặc định, hợp cho địa hình.
noise_value	Nhiễu giá trị: rẻ hơn, hơi vuông vức. Hợp cho vết, đốm.

◆ noise_fractal

enum njin::noise_fractal

Cách chồng nhiều lớp nhiễu (octave) lên nhau.

Enumerator
fractal_none	Một lớp. Hình to, trơn.
fractal_fbm	Cộng các lớp càng lúc càng nhỏ và nhạt: địa hình tự nhiên. Mặc định.
fractal_ridged	Gờ nhọn: dãy núi, sống đá, dòng sông khi lấy vùng thấp.
fractal_billow	Gợn tròn phồng lên: mây, đồi thấp, đá cuội.

◆ grid_side

enum njin::grid_side : u8

Các phía của một ô, cộng lại được: side_up | side_down.

Enumerator
side_up	Ô phía trên.
side_down	Ô phía dưới.
side_left	Ô bên trái.
side_right	Ô bên phải.
side_all	Cả bốn phía.

◆ autotile_layout

enum njin::autotile_layout

Bộ ô dùng để nối một loại địa hình với chính nó.

Enumerator

autotile_edges

16 ô, nhìn bốn ô kề (trên, phải, dưới, trái).

Góc lồi (hai phía liền nhau để hở) tròn được; góc lõm (ô chéo hở) thì không. Đủ cho tường và đường đi.

autotile_blob

47 ô, nhìn cả tám ô kề. Có cả góc lồi lẫn góc lõm: đất, nước, mặt đá liền tự nhiên. Mặc định.

◆ autotile_neighbor

enum njin::autotile_neighbor : u8

Các ô kề, cộng lại thành mặt nạ (mask) của một ô.

Ô chéo chỉ tính khi cả hai ô kề thẳng cạnh nó cũng cùng loại, nên chỉ còn 47 kiểu mặt nạ (chứ không phải 256).

Enumerator
neighbor_up	Ô phía trên.
neighbor_up_right	Ô chéo phải trên.
neighbor_right	Ô bên phải.
neighbor_down_right	Ô chéo phải dưới.
neighbor_down	Ô phía dưới.
neighbor_down_left	Ô chéo trái dưới.
neighbor_left	Ô bên trái.
neighbor_up_left	Ô chéo trái trên.

Thông tin về hàm

◆ tile_grid_make()

tile_grid njin::tile_grid_make	(	i32	width,
		i32	height,
		i32	fill = -1 )

Tạo một lưới width x height, mọi ô là fill.

Các tham số

width	Số cột.
height	Số hàng.
fill	Giá trị ban đầu, mặc định -1 (trống).

Giá trị trả về: Lưới mới. Kích thước âm được coi là 0.

◆ tile_grid_from_text()

tile_grid njin::tile_grid_from_text	(	std::string_view	text,
		std::initializer_list< tile_key >	legend )

Dựng lưới từ bản đồ chữ, cùng quy tắc với tilemap_from_text(): mỗi ký tự một ô, legend cho biết ký tự nào là ô nào.

Ký tự không có trong legend thành -1. Lưới rộng bằng dòng dài nhất. Dùng để viết mẫu cho wfc_learn(), hoặc để chỉnh tay một lưới rồi cho luật chạy tiếp.

Các tham số

text	Bản đồ chữ.
legend	Bảng ký tự.

Giá trị trả về: Lưới.

◆ tilemap_from_grid()

void njin::tilemap_from_grid	(	tilemap &	map,
		const tile_grid &	grid,
		cell	origin = {} )

Đặt lưới vào tilemap, góc trên trái ở ô origin.

Ô -1 của lưới không xóa ô đang có (như bản đồ chữ), nên chồng được nhiều lưới; muốn sinh lại từ đầu thì gọi tilemap_clear() trước.

Các tham số

map	Tilemap.
grid	Lưới.
origin	Ô của góc trên trái.

◆ grid_count()

i32 njin::grid_count	(	const tile_grid &	grid,
		i32	tile )

Số ô có giá trị tile.

Các tham số

grid	Lưới.
tile	Số thứ tự ô (có thể là -1).

Giá trị trả về: Số ô.

◆ noise_2d()

f32 njin::noise_2d	(	const noise_desc &	desc,
		f32	x,
		f32	y )

Giá trị nhiễu tại một điểm, từ 0 đến 1.

Các tham số

desc	Tham số.
x	Toạ độ, thường là cột của ô.
y	Toạ độ, thường là hàng.

Giá trị trả về: Số trong [0, 1]. Với fractal_fbm giá trị dồn quanh 0.5, hiếm khi ra ngoài 0.2 đến 0.8; generate_topdown() tự kéo giãn cho đủ 0 đến 1 (xem njin::topdown_gen_desc::normalize).

◆ noise_1d()

f32 njin::noise_1d	(	const noise_desc &	desc,
		f32	x )

Nhiễu một chiều, từ 0 đến 1: đường mặt đất của platformer, độ cao theo cột.

Các tham số

desc	Tham số.
x	Toạ độ.

Giá trị trả về: Số trong [0, 1].

◆ grid_majority()

void njin::grid_majority	(	tile_grid &	grid,
		i32	iterations = 1,
		i32	threshold = 5 )

Làm mượt: mỗi ô thành loại ô xuất hiện nhiều nhất trong ô 3 x 3 quanh nó, nếu loại đó có ít nhất threshold ô.

Xoá các chấm lẻ và răng cưa mà nhiễu để lại, với mọi loại ô cùng lúc.

Các tham số

grid	Lưới.
iterations	Số lần làm.
threshold	Trong 9 ô, cần bao nhiêu (5 là đa số).

◆ grid_smooth()

void njin::grid_smooth	(	tile_grid &	grid,
		i32	solid,
		i32	open,
		i32	iterations = 3,
		i32	threshold = 5 )

Làm mượt hai loại ô kiểu hang động (automat tế bào): một ô thành solid nếu ít nhất threshold trong 8 ô quanh nó là đặc, còn không thì thành open.

Ô đặc là mọi ô khác open, kể cả ngoài lưới, nên hang không thủng ra mép. Chỉ đổi những ô đang là solid hoặc open.

Các tham số

grid	Lưới.
solid	Ô đặc (vách).
open	Ô trống (lòng hang, thường -1).
iterations	Số lần làm, 2 đến 5 là thường.
threshold	5 là luật hang cổ điển.

◆ grid_remove_small()

i32 njin::grid_remove_small	(	tile_grid &	grid,
		i32	tile,
		i32	min_size,
		i32	replace )

Xoá các vùng nhỏ của một loại ô: mỗi vùng liền nhau (theo 4 hướng) của tile có ít hơn min_size ô thì thành replace.

Bỏ ao tí xíu, đảo một ô, mảng đá lạc.

Các tham số

grid	Lưới.
tile	Loại ô.
min_size	Kích thước tối thiểu.
replace	Ô thay vào.

Giá trị trả về: Số vùng đã xoá.

◆ grid_merge_small()

i32 njin::grid_merge_small	(	tile_grid &	grid,
		i32	min_size )

Như grid_remove_small() cho mọi loại ô: vùng nhỏ hơn min_size hoà vào loại ô bao quanh nó nhiều nhất.

Các tham số

grid	Lưới.
min_size	Kích thước tối thiểu.

Giá trị trả về: Số vùng đã hoà.

◆ grid_keep_largest()

i32 njin::grid_keep_largest	(	tile_grid &	grid,
		std::initializer_list< i32 >	walkable,
		i32	replace )

Giữ mọi chỗ đi được liền một khối: trong các ô thuộc walkable, chỉ vùng liền nhau (4 hướng) lớn nhất được giữ, các vùng khác thành replace.

Dùng cho top-down để không có góc nào bị cô lập.

Các tham số

grid	Lưới.
walkable	Các loại ô đi được.
replace	Ô thay cho vùng bị bỏ.

Giá trị trả về: Số ô đã thay.

◆ grid_border()

i32 njin::grid_border	(	tile_grid &	grid,
		i32	tile,
		i32	touching,
		i32	replace,
		u8	sides = side_all,
		i32	distance = 1 )

Viền: ô tile nằm cách touching không quá distance ô (theo các phía trong sides) thì thành replace.

Bãi cát giữa nước và cỏ, cỏ trên mặt đất (chỉ phía trên chạm ô trống), rìa đá.

Các tham số

grid	Lưới.
tile	Ô bị đổi.
touching	Ô gây ra viền.
replace	Ô viền.
sides	Các phía được xét.
distance	Độ dày viền, tính bằng ô.

Giá trị trả về: Số ô đã đổi.

◆ grid_scatter() [1/2]

i32 njin::grid_scatter	(	tile_grid &	grid,
		i32	on,
		i32	place,
		f32	chance,
		u32	seed,
		i32	min_distance = 0 )

Rải ngẫu nhiên: mỗi ô on có xác suất chance thành place, và hai ô được rải cách nhau ít nhất min_distance ô (0 là không giới hạn).

Hoa trên cỏ, đá trên đất, cây trong rừng.

Các tham số

grid	Lưới.
on	Ô được rải lên.
place	Ô rải.
chance	Xác suất, 0 đến 1.
seed	Hạt giống.
min_distance	Khoảng cách tối thiểu (Chebyshev).

Giá trị trả về: Số ô đã rải.

◆ grid_scatter() [2/2]

i32 njin::grid_scatter	(	tile_grid &	grid,
		i32	place,
		f32	chance,
		u32	seed,
		const std::function< bool(const tile_grid &, i32, i32)> &	where,
		i32	min_distance = 0 )

Như bản trên, nhưng chỗ nào được rải do hàm where quyết định: bụi cây chỉ ở ô trống ngay trên mặt đất, đuốc chỉ trên tường...

njin::grid_scatter(grid, 14, 0.2f, 7, [](const njin::tile_grid &g, njin::i32 x, njin::i32 y) {
  return g.get(x, y) == -1 && g.get(x, y + 1) == 0; // trống, và ngay dưới là cỏ
});

Các tham số

grid	Lưới.
place	Ô rải.
chance	Xác suất.
seed	Hạt giống.
where	Ô (x, y) có được rải không.
min_distance	Khoảng cách tối thiểu.

Giá trị trả về: Số ô đã rải.

◆ autotile_count()

i32 njin::autotile_count ( autotile_layout layout )

Số ô của một bộ.

Các tham số

layout Kiểu bộ.

Giá trị trả về: 16 hoặc 47.

◆ autotile_index()

i32 njin::autotile_index	(	u8	mask,
		autotile_layout	layout = autotile_blob )

Số thứ tự ô (trong bộ, từ 0) ứng với một mặt nạ.

Với autotile_edges: up + 2 * right + 4 * down + 8 * left, mỗi số là 1 nếu ô kề đó cùng loại (bỏ qua ô chéo); ô tách rời hoàn toàn là 0, ô ở giữa vùng là 15. Với autotile_blob: thứ hạng của mặt nạ (đã bỏ ô chéo thừa) trong 47 mặt nạ hợp lệ xếp tăng dần; ô tách rời là 0, ô ở giữa vùng là 46. Vẽ bộ ô theo đúng thứ tự này (trang Sinh bản đồ có bảng).

Các tham số

mask	Các bit neighbor_* của ô kề cùng loại.
layout	Kiểu bộ.

Giá trị trả về: Số thứ tự trong [0, autotile_count()).

◆ grid_autotile()

i32 njin::grid_autotile	(	tile_grid &	grid,
		const std::vector< autotile_rule > &	rules )

Thay mọi ô thuộc rules[i].tiles bằng ô của bộ tương ứng, chọn theo các ô kề: chỗ nào địa hình hở ra thì ô có mép, hai mép gặp nhau thì có góc tròn (lồi), chỗ địa hình lõm vào thì có góc lõm.

Mọi luật đọc từ cùng một bản chụp lưới trước khi đổi, nên thứ tự các luật không ảnh hưởng và số thứ tự ô mới không bị nhầm với ô cũ. Một ô khớp nhiều luật thì luật đầu thắng.

Gọi sau cùng, sau mọi luật khác (grid_border(), grid_scatter()...): vì ô đã đổi thành ô của bộ.

// cỏ và đất là một địa hình, đá nối liền với nó; ngoài lưới thì trời phía trên
njin::grid_autotile(grid, {{.tiles = {grass, dirt}, .joins = {stone}, .base = 0, .outside = njin::side_all & ~njin::side_up},
                           {.tiles = {stone}, .joins = {grass, dirt}, .base = 47}});

Các tham số

grid	Lưới.
rules	Các luật.

Giá trị trả về: Số ô đã thay.

◆ generate_topdown()

topdown_gen_result njin::generate_topdown ( const topdown_gen_desc & desc )

Sinh bản đồ top-down từ nhiễu.

Các tham số

desc Tham số.

Giá trị trả về: Bản đồ, độ cao và điểm xuất phát.

◆ generate_platformer()

platformer_gen_result njin::generate_platformer ( const platformer_gen_desc & desc )

Sinh màn platformer từ nhiễu.

Các tham số

desc Tham số.

Giá trị trả về: Màn, mặt đất, điểm xuất phát và đích.

◆ wfc_add_tile()

i32 njin::wfc_add_tile	(	wfc_rules &	rules,
		i32	tile,
		f32	weight = 1.0f )

Thêm một ô vào luật (hoặc đổi độ hay gặp nếu đã có).

Các tham số

rules	Luật.
tile	Ô.
weight	Độ hay gặp.

Giá trị trả về: Chỉ số của ô trong rules.tiles.

◆ wfc_allow()

void njin::wfc_allow	(	wfc_rules &	rules,
		i32	a,
		wfc_dir	dir,
		i32	b )

Cho phép b đứng ở hướng dir của a, và (đối xứng) a đứng ở hướng ngược lại của b.

Ô chưa có được thêm vào với độ hay gặp 1.

Các tham số

rules	Luật.
a	Ô thứ nhất.
dir	Hướng từ a sang b.
b	Ô thứ hai.

◆ wfc_learn()

wfc_rules njin::wfc_learn	(	const tile_grid &	sample,
		bool	periodic = false )

Học luật từ một mẫu: mọi cặp ô cạnh nhau trong mẫu thành luật kề, số lần xuất hiện thành độ hay gặp.

Viết mẫu bằng tile_grid_from_text(). Mẫu nhỏ và đa dạng cho kết quả tốt; mẫu thiếu cặp nào thì cặp đó không bao giờ xuất hiện.

Các tham số

sample	Mẫu.
periodic	true: coi mẫu lặp lại, mép phải nối mép trái, mép dưới nối mép trên.

Giá trị trả về: Luật.

◆ wfc_generate()

bool njin::wfc_generate	(	const wfc_rules &	rules,
		const wfc_desc &	desc,
		tile_grid &	out )

Sinh một lưới thoả mọi luật kề, bằng Wave Function Collapse (mô hình ô, không quay lui: gặp mâu thuẫn thì làm lại từ đầu với dãy ngẫu nhiên khác, tối đa attempts lần).

Các tham số

rules	Luật.
desc	Tham số.
out	Nhận lưới nếu thành công; không đổi nếu thất bại.

Giá trị trả về: true nếu thành công. false khi luật quá chặt, ràng buộc mâu thuẫn, hoặc hết số lần thử.

Classes

Enumerations

Các hàm

Mô tả chi tiết

Thông tin về Enumeration Type

◆ noise_type

◆ noise_fractal

◆ grid_side

◆ autotile_layout

◆ autotile_neighbor

Thông tin về hàm

◆ tile_grid_make()

◆ tile_grid_from_text()

◆ tilemap_from_grid()

◆ grid_count()

◆ noise_2d()

◆ noise_1d()

◆ grid_majority()

◆ grid_smooth()

◆ grid_remove_small()

◆ grid_merge_small()

◆ grid_keep_largest()

◆ grid_border()

◆ grid_scatter() [1/2]

◆ grid_scatter() [2/2]

◆ autotile_count()

◆ autotile_index()

◆ grid_autotile()

◆ generate_topdown()

◆ generate_platformer()

◆ wfc_add_tile()

◆ wfc_allow()

◆ wfc_learn()

◆ wfc_generate()