godot-procedural-generation

用途

本技能为 Godot 引擎中的程序化内容生成（Procedural Content Generation）提供专家级蓝图，覆盖地牢、地形、战利品与关卡等内容的生成。适用于制作类 Rogue 游戏、沙盒游戏或需要动态内容的项目。关键词包括 procedural、generation、FastNoiseLite、Perlin noise、BSP、drunkard walk、Wave Function Collapse、seeding。

主要能力

技能以“带种子的算法 + 噪声函数 + 约束传播”定义可复现的内容生成，并提供算法决策树，按布局或内容需求选择对应算法与脚本：

蜿蜒隧道、河流、简单路径：Drunkard's Walk（drunknard_walk_path.gd）
结构化房间与走廊：BSP（bsp_tree_rooms.gd）
有机洞穴、平滑地形：Cellular Automata（cellular_automata_dungeon.gd）
高度图、生物群系、无限地形：FastNoiseLite → Image（fast_noise_noise2d_master.gd）
树木、岩石、生成点（避免聚集）：Poisson Disk（poisson_disk_sampling_2d.gd）
瓦片邻接、城市街区：Wave Function Collapse（wave_function_collapse_lite.gd 精简版或 wfc_level_generator.gd 完整规则版）
几何之前的房间图：AStar 图布局（proc_gen_graph_layout.gd）
3D 体素、平滑地形网格：Marching Cubes 基础（proc_gen_marching_cubes_base.gd）
无限分块 3D 地形：ArrayMesh + LOD 分块（mesh_gen_infinite_terrain.gd）
植物、分支结构：L-System（l_system_tree_gen.gd）
等高线、元球贴图（2D）：Marching Squares（marching_squares_metaballs.gd）

核心脚本包括：proc_gen_seed_history.gd（带种子的 RandomNumberGenerator，支持 push/pop 状态历史）与 multi_threaded_chunk_gen.gd（WorkerThreadPool → call_deferred 分块最终化模式）。

使用方式

黄金路径（强制）为：种子与 RNG 隔离 → 异步分块 → 主线程提交 → 验证并烘焙导航。

种子与 RNG：每个关卡或分块使用一个 RandomNumberGenerator，持久化 seed 与 state 以支持可分享的运行。
异步分块：使用 WorkerThreadPool.add_task 在线程外计算数据，再通过 call_deferred("_finalize_chunk") 处理场景树与节点工作。
验证并烘焙导航：瓦片或网格在主线程落地后，重新烘焙 NavigationRegion。

示例代码：

var rng := RandomNumberGenerator.new()

func begin_generation(run_seed: int) -> void:
    rng.seed = run_seed
    WorkerThreadPool.add_task(_build_data.bind(run_seed))

func _build_data(seed: int) -> Dictionary:
    var local_rng := RandomNumberGenerator.new()
    local_rng.seed = seed
    var noise := FastNoiseLite.new()
    noise.seed = seed
    return {"heights": noise.get_image(64, 64)}

func _ready() -> void:
    # Worker returns here — safe for nodes
    pass

func _finalize_from_worker(data: Dictionary) -> void:
    # add_child / set_pattern / create_trimesh_collision — main thread only
    pass

注意：不要加载整个 scripts/ 文件夹，只打开与所选算法对应的脚本。

适用场景

类 Rogue 地牢爬行游戏（消费 BSP/WFC/drunkard 生成器与带种子 RNG）
沙盒游戏（基于无限地形与 CA 脚本的体素/分块世界）
开放世界（包装多线程分块生成的流式加载与浮动原点层）
需要可复现、可分享种子的动态内容生成

限制与注意事项

技能明确列出程序化生成中的禁忌：

绝不在主线程生成分块（CPU 密集，会造成帧率尖峰），应使用 WorkerThreadPool 或后台 Thread。
绝不每帧查询 FastNoiseLite，应一次性生成到 Image 或 Array 后从内存采样。
绝不使用 randi() 获取可复现种子，应存储并复用 RandomNumberGenerator 的 seed。
绝不用纯随机放置对象（白噪声会导致聚集与重叠），应使用 Poisson Disk Sampling 或 Jittered Grids。
绝不忘记为循环设界（WFC 或元胞自动机可能进入无限状态），始终包含 max_iterations 安全中断。
绝不从生成线程直接实例化节点，不能在工作线程触碰 SceneTree；应在线程中生成数据，再通知主线程执行 add_child()。
绝不对简单布局使用复杂 WFC，简单路径应使用 Drunkard's Walk 或 BSP。
绝不依赖 TileMap.set_cell() 进行大规模更新，应准备 TileMapPattern 并使用 set_pattern() 或 set_cells_terrain_connect() 批量更新。
绝不忘记在最后烘焙导航，程序化生成的世界需要在运行时重新烘焙 navmesh。
绝不忽略数据序列化，应保存种子与玩家修改，避免保存整个原始分块状态。

参考与相关技能

官方文档涵盖 FastNoiseLite、随机数生成、RandomNumberGenerator、多线程使用、线程安全 API、WorkerThreadPool、ArrayMesh、SurfaceTool、TileMaps、GridMaps、3D 导航介绍与 AStar2D。

相关技能包括前置的 godot-project-foundations、godot-gdscript-mastery、godot-resource-data-patterns；互补的 godot-tilemap-mastery、godot-3d-world-building、godot-navigation-pathfinding、godot-performance-optimization、godot-save-load-systems、godot-scene-management、godot-monte-carlo-balancer；下游的 godot-genre-roguelike、godot-genre-sandbox、godot-genre-open-world；以及 godot-master 库路由。

深入内容（醉汉游走、噪声生物群系、BSP、战利品表、WFC 循环）见 references/algorithm-recipes.md。