godot-procedural-generation

程序化生成

带种子的算法、噪声函数和约束传播共同定义了可重放的内容生成。不要粘贴内联算法教程——请加载以下必需脚本。

程序化生成中绝对不要做的事

• 绝不要在主线程上生成区块——程序化生成会大量占用 CPU，导致帧率骤降。使用 WorkerThreadPool 或后台 Thread，以保持 UI 响应流畅。
• 绝不要每帧查询 FastNoiseLite——每帧采样噪声（尤其是在 _process 中）会造成巨大的资源浪费。将地图生成到 Image 或 Array 中，然后从内存采样 [NoiseSampling]。
• 绝不要使用 randi() 来生成可复现的种子——始终在随机数生成器（RandomNumberGenerator.new()）中存储并复用特定的 seed，以确保世界生成结果一致。
• 绝不要仅靠纯随机来放置对象——纯随机（白噪声）会导致对象聚集和重叠。请使用泊松圆盘采样或抖动网格，以获得自然的分布。
• 绝不要忘记限制循环次数——如果约束无法满足，程序化循环（如 WFC 或元胞自动机）很容易进入无限状态。务必添加 max_iterations 安全退出条件。
• 绝不要在程序化生成线程中直接实例化节点——你不能在工作线程中操作 SceneTree。在线程中生成数据，然后通知主线程执行 add_child()。
• 绝不要对简单布局使用复杂的 WFC——波函数坍缩功能强大，但用于简单路径时过于复杂。简单结构化布局可使用醉汉漫步或BSP。
• 绝不要依赖 TileMap.set_cell() 进行大规模更新——逐个更新 10,000 个单元格会很慢。准备一个 TileMapPattern，并使用 set_pattern() 或 set_cells_terrain_connect() 批量更新。
• 绝不要忘记在最后烘焙导航——程序化生成的世界需要在运行时重新烘焙导航网格，否则 AI 会撞上墙壁。
• 绝不要忽略数据序列化——如果你生成了世界，就必须能够保存种子和任何玩家修改。只要可行，就不要尝试保存整个原始区块状态。

---

标准流程（必需）

每个生成器都从这里开始——隔离种子、异步处理数据、在主线程提交：

1. 种子和 RNG——必需 proc_gen_seed_history.gd：每个关卡／区块使用一个 RandomNumberGenerator；持久化 seed + state，以便分享运行结果。
2. 异步生成区块——必需 multi_threaded_chunk_gen.gd：WorkerThreadPool.add_task → 在线程外计算数据 → 使用 call_deferred("_finalize_chunk") 处理 SceneTree／节点操作。
3. 验证 → 烘焙导航——瓦片／网格在主线程中就位后，重新烘焙 NavigationRegion（参见 godot-navigation-pathfinding）。

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/ 文件夹。只打开下方算法对应的脚本。

算法决策树

布局 / 内容需求	算法	脚本（选用时必须使用）
蜿蜒隧道、河流、简单路径	随机游走	必须 drunknard_walk_path.gd
结构化房间 + 走廊	BSP	必须 bsp_tree_rooms.gd
有机洞穴 / 平滑地形	元胞自动机（4/5）	必须 cellular_automata_dungeon.gd
高度图、生物群系、无限地形	FastNoiseLite → Image	必须 fast_noise_noise2d_master.gd
树木、岩石、生成点（不聚集）	泊松圆盘采样	必须 poisson_disk_sampling_2d.gd
图块邻接 / 城市街区	波函数坍缩	必须 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

选择提示： 简单路径 → 随机游走；矩形房间 → BSP；约束图块 → WFC 轻量版；开放世界分块 → 噪声 + multi_threaded_chunk_gen.gd。对于 Roguelike 运行流程编排，请交由 godot-genre-roguelike 处理。

可用脚本

核心（始终从这里开始）

• proc_gen_seed_history.gd — 必须 使用带有推入 / 弹出状态历史的 RandomNumberGenerator 设定种子
• multi_threaded_chunk_gen.gd — 必须 使用 WorkerThreadPool → call_deferred 分块最终化模式

2D 布局与摆放

• drunknard_walk_path.gd — 必须 用于隧道 / 路径（传入本地 RNG，绝不使用全局 randi()）
• bsp_tree_rooms.gd — 必须 用于结构化平面布局
• cellular_automata_dungeon.gd — 必须 用于有机洞穴
• poisson_disk_sampling_2d.gd — 必须 用于蓝噪声道具 / 敌人摆放
• wave_function_collapse_lite.gd — 必须 轻量版 WFC，带有熵 + max_iterations
• wfc_level_generator.gd — 完整版 WFC，包含图块库邻接规则
• proc_gen_graph_layout.gd — 通过 AStar2D/3D 实现先构图再生成几何

噪声与 3D

• fast_noise_noise2d_master.gd — 必须 使用 FastNoiseLite → Image 生成高度图
• mesh_gen_infinite_terrain.gd — 运行时 ArrayMesh 地形，可支持 LOD
• proc_gen_marching_cubes_base.gd — 根据体素数据生成 3D 网格
• marching_squares_metaballs.gd — 2D 等高线提取
• l_system_tree_gen.gd — 程序化植物 / 树木语法

专家级程序化模式

1. 通过 ArrayMesh 生成 3D 地形（Marching Cubes）

对于类似体素或平滑有机风格的地形，可使用 ArrayMesh 通过代码生成几何体。

• 逻辑：在工作线程中计算顶点、法线和索引。
• 提交：使用 add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, arrays) 创建网格。
• 性能：仅对当前区块使用 create_trimesh_collision()，以加快物理更新。

2. 基于图的地牢逻辑

不要先生成地牢几何体，而应使用 AStar2D 构建逻辑图。

• 顶点：表示“房间”。
• 边：表示“走廊”或“门”。
• 优点：生成任何网格之前，即可轻松运行验证（是否每个房间都可到达？）。

深入了解（按需加载）

Drunkard walk、噪声生物群系、BSP、战利品表、WFC 循环——references/algorithm-recipes.md。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；需要切换到相关领域时再加载相关技能——不要预加载整个技能体系。

官方文档

• FastNoiseLite — 用于高度图和生物群系遮罩的种子、频率、噪声类型，以及 get_image()/get_noise_2d()。
• 随机数生成 — 为什么每个生成器使用单独的 RandomNumberGenerator 种子，比使用全局 randi() 更适合可分享的游戏进程。
• RandomNumberGenerator — 用于确定性序列和可撤销 RNG 历史记录的 seed/state API。
• 使用多个线程 — 将区块/WFC 工作转移到其他线程，避免主循环卡顿。
• 线程安全 API — 工作线程可以调用哪些 Godot API；SceneTree/节点创建仍须在主线程中进行。
• WorkerThreadPool — 用于异步区块生成的 add_task + call_deferred 收尾模式。
• 使用 ArrayMesh — 提交顶点/法线/索引数组，以生成 Marching Cubes 和无限地形网格。
• 使用 SurfaceTool — 为运行时平面逐步构建顶点并生成法线。
• 使用 TileMaps — 在 BSP、CA、WFC 或 Drunkard walk 网格生成后，批量写入 TileMapLayer/图案。
• 使用 GridMaps — 用于地牢/地形生成器的模块化 3D 单元放置后端。
• 导航简介（3D） — 程序化几何体生成后，重新烘焙 NavigationRegion 网格。
• AStar2D — 生成瓦片或网格之前，验证房间/走廊图。

相关技能

前置条件

• godot-project-foundations — 在生成器输出 TileMaps、GridMaps 或 ArrayMeshes 之前，了解场景、资源和导入基础知识。
• godot-gdscript-mastery — 掌握每个生成器脚本都会用到的类型化数组、call_deferred 和 WorkerThreadPool 任务模式。
• godot-resource-data-patterns — 使用由 Resource 支持的瓦片库、邻接规则和种子配置，而不是硬编码的魔法表。

配套技能

• godot-tilemap-mastery — 批量使用 set_pattern / 地形连接，避免大型 CA/WFC 网格逐个瓦片调用 set_cell。
• godot-3d-world-building — 使用 GridMap/MeshLibrary/CSG 放置后端来处理房间图和高度图。
• godot-navigation-pathfinding — 在房间、洞穴或地形区块生成完毕后，于运行时烘焙导航网格。
• godot-performance-optimization — 为网格提交、碰撞三角网格和生成后的 MultiMesh 道具散布设定预算。
• godot-save-load-systems — 持久化种子和玩家差异数据，而不是序列化每个生成的区块。
• godot-scene-management — 对封装生成数据的区块场景进行线程化加载/卸载。
• godot-monte-carlo-balancer — 在发布前，根据种子分布抽样评估生成密度、战利品表和房间难度。

下游 / 使用方

• godot-genre-roguelike — 使用 BSP/WFC/醉汉游走生成器和带种子的 RNG 的局内制地牢爬行游戏。
• godot-genre-sandbox — 基于无限地形和 CA 脚本构建的体素/区块世界及元胞自动机沙盒。
• godot-genre-open-world — 封装多线程区块生成的区块流送和浮动原点层。

主技能

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。