godot-genre-roguelike

绝对不要做（专家反模式）

生成与随机数生成器

• 绝对不要让游戏进程依赖纯随机数生成器；务必提供缓解机制（重掷、商店、保底计时器），确保每次游戏进程都能获胜。
• 绝对不要使用未设种子的随机数生成器生成世界；务必使用可预测的种子初始化独立的 RandomNumberGenerator，以支持每日游戏进程和调试。
• 绝对不要依赖 @GlobalScope.randi() 处理关键逻辑；务必使用本地随机数生成器实例，防止污染全局状态。
• 绝对不要使用 Array.pick_random() 生成关键内容掉落；务必使用洗牌袋，避免出现统计上不公平的连续结果。
• 绝对不要在主线程上生成大型地牢；务必使用 WorkerThreadPool.add_task() 或 add_group_task() 将生成工作分配到多个核心，避免帧冻结。
• 绝对不要在后台线程中与 SceneTree 交互；务必先在线程安全的 Array/PackedByteArray 中生成地牢数据，再在主线程上解析。

数据与状态

• 绝对不要允许读档作弊；务必在加载时立即删除游戏进程中的存档文件，以强制执行永久死亡机制。
• 绝对不要让玩家看到“世界边缘”；务必使用战争迷雾或有限视野锥，维持未知事物的神秘感。
• 绝对不要每帧计算复杂的“导演”启发式逻辑；务必使用帧分片（Engine.get_process_frames()），每 60-120 帧才运行一次繁重的节奏控制逻辑，以提高 CPU 效率。
• 绝对不要在程序化生成期间按像素值单独移动房间；务必使用预先制作的场景中的 Marker2D 连接点计算精确偏移量，确保房间无缝拼接。
• 绝对不要让游戏进程状态泄漏到元进度状态中；务必为 RunManager 和 MetaManager 使用独立的单例或资源。
• 绝对不要让元进度成长过强（伤害 +100%）；务必将升级效果控制在较低幅度（+5-15%），以维持以技巧为主的玩法。
• 绝对不要忘记对基础属性资源调用 duplicate(true)；未执行深度复制会导致所有实体共享同一个生命值实例。
• 绝对不要将游戏进程状态保存到 .tscn 文件；务必序列化为 JSON 或二进制数据并保存到 user://，以避免文件臃肿。
• 绝对不要依赖 SceneTree 作为网格逻辑的真实数据源；务必在独立的 Dictionary 或 Array 中维护网格数据。

网格与性能

• 绝对不要忘记处理导航重新烘焙；务必在放置程序化图块之后重新烘焙 NavigationRegion2D。
• 绝对不要对图块网格使用 AStar2D；务必使用 AStarGrid2D 并设置 jumping_enabled = true（跳点搜索），以实现 O(1) 查询，并在开放区域中进行高性能寻路。
• 绝对不要在修改状态后忘记对 AStarGrid2D 调用 update()；这能确保寻路查询不会使用过期数据。
• 绝对不要使用浮点数（Vector2）表示离散网格坐标；务必使用 Vector2i，避免精度漂移。
• 绝对不要对八方向移动使用曼哈顿启发式；务必使用 HEURISTIC_CHEBYSHEV 或 HEURISTIC_OCTILE。
• 绝对不要在 GDScript 中遍历每个单元格坐标（0 到 W,H）；务必使用 get_used_cells() 优化图块访问。
• 绝对不要使用 free() 清除程序化关卡；务必使用 queue_free()，避免帧中途发生段错误。
• 绝对不要立即向网格广播大规模状态更改；务必使用 call_deferred() 或 call_group_flags，避免回合切换期间出现帧峰值。
• 绝对不要使用开销大的 TileMapLayer 节点实现高分辨率战争迷雾；务必通过 ColorRect 和使用 RenderingServer.texture_2d_update() 更新的 ImageTexture，采用 GPU 着色器蒙版。

🛠 专家组件（scripts/）

开始实现生成、种子共享或元进度解锁之前，必须先阅读以下内容（不要重新发明内联示例中已有的实现）：

• dungeon_generator_walker.gd — 醉汉漫步算法，使用本地 RandomNumberGenerator（rng.randi() % n，绝不使用 Array.pick_random()）。
• seeded_rng_resource.gd — 用于可分享／每日挑战的种子持久化。
• meta_progression_manager.gd — 永久解锁货币 + 存档边界与本轮游戏状态的区分。

不要为了单个任务加载整个 scripts/ 文件夹。只打开与下方阶段对应的脚本。

原始专家模式

• meta_progression_manager.gd - 基础元进度逻辑，包含安全的数据持久化和货币解锁。
• roguelike_patterns.gd - 10 个必备 Roguelike 专家代码片段（AStar、BSP、WorkerThreadPool、ShuffleBag 等）。

模块化组件

• dungeon_generator_walker.gd - 用于生成程序化房间和洞穴的醉汉漫步算法。
• fov_raycast_calculator.gd - 使用物理服务器查询进行高性能视线检测。
• seeded_rng_resource.gd - RNG 状态持久化，支持确定性和可分享的回放。
• turn_manager_decoupled.gd - 以信号驱动的回合协调，实现实体逻辑解耦。
• astar_grid_handler.gd - 专用的 AStarGrid2D 封装，用于优化 Roguelike 寻路。
• weighted_loot_table.gd - 采用原生优化的加权随机物品掉落，并支持掉落率控制。
• json_state_serializer.gd - 持久化序列化程序化实体数据和本轮游戏状态。
• fog_of_war_masker.gd - 基于 TileMapLayer 的可见性遮罩和探索系统。
• meta_progression_resource.gd - 分离永久游戏解锁项和技能树的数据。
• move_command_object.gd - 为可撤销的回合制行动实现命令模式。
• dungeon_generator.gd - 用于生成房间与走廊布局的高层程序化协调器。
• run_manager.gd - 自动加载的本轮游戏种子／楼层／库存生命周期管理器（start_run / end_run）。
• director_ai.gd - 节奏管理器——根据玩家实力和本轮游戏时长调整生成强度。
• room_assembler.gd - 基于标记，从预制场景中程序化拼接房间。
• synergy_manager.gd - 检测遗物标签协同效果并应用叠加修正值。
• example_relic_vampirism.gd - Relic Resource 钩子示例（on_damage_dealt）。

核心循环

1. 准备：选择角色，装备元升级（参见 meta_progression_resource.gd）。
2. 本轮游戏：完成程序化生成的关卡（dungeon_generator_walker.gd），获取临时强化。
3. 挑战：使用 A* 寻路（astar_grid_handler.gd）在难度不断提升的遭遇战中存活。
4. 死亡／胜利：本轮游戏结束，结算资源。
5. 元进度：使用资源解锁永久内容（meta_progression_resource.gd）。
6. 重复：以新能力开始新一轮游戏。

技能链

阶段	技能	用途
1. 架构	godot-autoload-architecture、godot-state-machine-advanced	划分运行状态与元状态的边界
2. 世界生成	godot-procedural-generation、godot-tilemap-mastery	每次运行生成独特关卡（漫游者／BSP／噪声）
3. 战斗	godot-combat-system、godot-ai-navigation	高风险遭遇战 + 视野／寻路
4. 成长	godot-inventory-system、godot-resource-data-patterns	单局道具／遗物 + 类型化 Resource
5. 持久化	godot-save-load-systems	元进度解锁 + 防止单局中途删除存档以钻空子
6. 平衡	godot-monte-carlo-balancer	胜率与元进度等级的关系；检测无用道具

架构概览

Roguelike 需要严格区分运行状态（临时）和元状态（持久）。

• 单局生命周期／种子：使用一个死亡时重置的 AutoLoad；通过强制使用的 seeded_rng_resource.gd 设置种子。切勿将单局 HP／金币泄漏到元进度存档中。
• 元进度解锁：强制使用 meta_progression_manager.gd + meta_progression_resource.gd——仅提供细微的永久加成（+5–15%）。
• 序列化：优先使用 json_state_serializer.gd／user:// JSON 二进制；绝不要将 .tscn 当作单局存档。

关键机制（对应 scripts/ 中的脚本）

程序化地牢生成

• 醉汉漫步：强制使用 dungeon_generator_walker.gd——传入本地的、有种子的 RandomNumberGenerator；通过 rng.randi() % directions.size() 获取方向（绝不要使用 Array.pick_random()）。
• 关键掉落／公平性：使用 roguelike_patterns.gd 中的洗牌袋模式，或 weighted_loot_table.gd 中的权重。
• BSP／房间编排器：dungeon_generator.gd；更深入的 WFC／噪声 → 同级技能 godot-procedural-generation。
• 生成后的寻路：astar_grid_handler.gd——编辑实心单元格后调用 update()；若使用导航网格，则重新烘焙 NavigationRegion2D。

遗物、回合、战争迷雾、节奏

• 遗物钩子／协同标签：Resource 子类 + weighted_loot_table.gd；物品栏相关技能 godot-inventory-system。
• 回合：turn_manager_decoupled.gd + move_command_object.gd。
• 战争迷雾／视线：fog_of_war_masker.gd、fov_raycast_calculator.gd。
• 导演式节奏控制：使用 Engine.get_process_frames() % N 分帧处理（参见 NEVER）；不要将启发式逻辑放进每帧运行的 _process 中。

常见问题

1. RNG 依赖：不要让单局结果完全取决于运气。优秀的 Roguelike 会让玩家能用技巧弥补 RNG 带来的不利影响。
2. 元进度失衡：如果元升级过于强大，游戏就会变成“刷到赢”，而非“学会赢”。
3. 缺乏多样性：程序化生成的效果取决于它所编排的内容。你需要大量内容（房间、敌人、道具），才能保持新鲜感。
4. 存档读档：玩家会尝试退出游戏来避免死亡。仅在楼层转换或退出时保存状态，并在读取时删除存档（可选，但严格的 Roguelike 通常会这样做）。

Godot 专属提示

• 有种子的单局：始终使用种子初始化 RandomNumberGenerator。这样玩家就可以分享特定单局的布局。
• ResourceSaver：使用 ResourceSaver 保存元进度，但要小心深层嵌套资源中的循环引用。
• 将场景用作房间：将“房间”构建为独立场景（Room1.tscn、Room2.tscn），并将它们实例化到生成的布局中，以便在程序化布局中保留手工制作的品质。
• 导航：如果使用 2D 导航，在生成地牢布局后于运行时重新烘焙 NavigationRegion2D。

进阶技巧

• 协同系统：为物品添加标签（fire、projectile、companion），并检查标签组合，以创造涌现式强化效果。
• 导演 AI：一种隐形的“导演”系统，会追踪玩家的生命值／压力，并动态调整生成速率（类似 Left 4 Dead）。

必须阅读：若要深入了解决策树和脚本目录之外的内容，请参阅 roguelike-meta-systems-deep.md。首次接线时不要加载此文件——先使用内置的 scripts/。

参考

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

官方文档

• 使用 TileMaps — 用于程序化生成地板／墙壁的 TileMapLayer 单元格、源和运行时放置。
• TileMapLayer — 在 walker／BSP 生成和战争迷雾清除后使用的 set_cell／get_used_cells API。
• AStarGrid2D — 网格寻路，支持启发式算法、对角线模式，以及在编辑实心单元格后调用 update()。
• RandomNumberGenerator — 使用带种子的 PCG32 生成可分享的游戏进程；优先使用本地实例，而非全局 randi()。
• WorkerThreadPool — 将繁重的地牢生成任务卸载到后台，避免主线程卡顿。
• 使用多个线程 — 了解何时可以安全使用 WorkerThreadPool／任务，以及 SceneTree 所有权规则。
• 线程安全 API — 在线程外生成数据，然后仅在主线程中应用图块／节点。
• 保存游戏 — 用于元进度解锁和防止中途删档刷结果的 user:// 持久化模式。
• 资源 — 基于 Resource 的元进度／游戏进程数据、duplicate(true)，以及 .tres／自定义资源的保存和加载。
• 单例（自动加载） — 将 RunManager 与 MetaManager 分开，避免游戏进程死亡时清除永久进度。
• 射线投射 — 使用 PhysicsDirectSpaceState 查询视野／视线，避免大量使用 Area2D。
• FastNoiseLite — 使用噪声场生成洞穴风格地图，再通过 AStarGrid2D 验证连通性。

相关技能

前置条件

• godot-project-foundations — 在拆分游戏进程／元进度前，了解项目布局、自动加载项和 Resource 基础知识。
• godot-tilemap-mastery — 掌握 TileMapLayer 的制作，以及程序生成器写入的运行时单元格编辑。
• godot-resource-data-patterns — 掌握遗物／元进度属性所需的 Resource 复制、类型化数据和便于保存的数据结构。
• godot-autoload-architecture — 了解单例的职责边界，以便在重置 Run 状态时不影响 Meta 状态。

补充技能

• godot-procedural-generation — 更深入的 Walker/BSP/WFC 生成器，为此类游戏的地牢循环提供内容。
• godot-navigation-pathfinding — 不使用纯 AStarGrid2D 时的 NavigationRegion 重烘焙和 Agent 寻路。
• godot-combat-system — 生成楼层中的命中/受击流程和按回合推进的遭遇战。
• godot-inventory-system — 局内背包、遗物槽位，以及战利品表使用的物品资源。
• godot-save-load-systems — JSON/二进制持久化、楼层切换存档，以及永久死亡时加载即删除。
• godot-signal-architecture — 解耦的回合/楼层/局内信号，不将 SceneTree 作为网格的真实数据源。
• godot-performance-optimization — 大规模场景下的线程池、雾效 GPU 遮罩和按帧切片的导演启发式算法。

下游 / 消费者

• godot-monte-carlo-balancer — 通过带种子的运行模拟胜率与元进度等级、怜悯计时器和无效物品检测。
• godot-genre-action-rpg — 常会使用 Roguelike 局内/元进度模式的动作 RPG 战斗与成长层。

主技能

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