godot-genre-metroidvania

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

世界设计与探索

• 绝对不要允许出现玩家被困住的“软锁”；如果玩家通过单向路径（“阀门”）进入，他们必须能够使用当前能力离开。始终设计故障安全逃生路线。
• 绝对不要创建空荡荡的死路；如果玩家折返到偏远区域，必须获得收藏品、背景故事或货币作为奖励。空房间就是设计失败。
• 绝对不要让折返变成纯粹重复的过程；随着玩家获得移动能力（Dash/Teleport），穿越旧区域的速度必须加快。开放捷径，绕过漫长的前期路线。
• 绝对不要在没有“线索”的情况下隐藏关键路线；使用鲜明的地标、独特的灯光或环境叙事，帮助玩家建立心智地图。
• 绝对不要设计只有一种用途的能力；必须严格实现兼具探索和战斗功能的双重用途（例如，既能跨越间隙又能躲避攻击的“Dash”）。

持久化与地图

• 绝对不要忘记保存持久房间状态；如果玩家打开了宝箱或击败了 Boss，那么离开并返回时，该状态必须仍然保存。
• 绝对不要通过 load() 同步加载互连房间；必须严格使用 ResourceLoader.load_threaded_request() 实现无缝过渡。
• 绝对不要在局部房间脚本中追踪全局进度；必须严格使用Autoload Singleton 保存全局能力标志和世界状态。
• 绝对不要在网格坐标（小地图/战争迷雾）中使用浮点类型；必须严格使用 Vector2i，以避免精度抖动。
• 绝对不要直接从后台加载线程操作 SceneTree；必须严格使用 call_deferred()。

物理与控制

• 绝对不要在 _process() 中计算跳跃轨迹或 Dash；必须严格使用 _physics_process()，以避免卡顿。
• 绝对不要在调用 move_and_slide() 之前将 CharacterBody2D 的速度乘以 delta；引擎会在内部处理。
• 绝对不要在 _physics_process() 中轮询 is_action_just_pressed() 来实现输入缓冲；必须严格在 _unhandled_input() 中捕获事件。
• 绝对不要在高频能力检查中使用标准字符串；必须严格使用 StringName（&"dashing"）进行指针速度比较。
• 绝对不要遍历每个节点来广播更新；必须严格使用 SceneTree.call_group() 进行高效的批量通信。
• 绝对不要通过 free() 删除活跃的房间/玩家节点；必须严格使用 queue_free()，以避免段错误。

---

🛠 专家级组件（scripts/）

黄金路径顺序（必须阅读）

1. 持久化 / 标志 — metroid_game_state.gd + persistent_progression_system.gd
2. 能力定义 / 门控 — ability_unlock_resource.gd + progression_gate_manager.gd
3. 房间流式加载 / 切换 — background_room_streamer.gd + safe_scene_switcher.gd
4. 地图迷雾 — minimap_fog_manager.gd（协调器），搭配 minimap_fog.gd / minimap_fog_revealer.gd

原创专家模式

• minimap_fog.gd - 基于网格的战争迷雾，追踪已访问的房间，并通过全局存档数据持久保存。
• progression_gate_manager.gd - 负责能力门控进度（锁/钥匙）和世界持久化的中央管理器。
• metroid_game_state.gd - 必须使用 Autoload 形式的世界/能力/收藏品状态（不要粘贴本地 game_state 教程）。
• ability_unlock_resource.gd - 必须使用供门控查询的可解锁能力 Resource 定义。
• minimap_fog_manager.gd - 必须使用与进度/存档同步的 Vector2i 迷雾协调。

模块化组件

• platformer_jump_buffer.gd - 模块化的宽容时间和跳跃缓冲，实现高保真移动。
• background_room_streamer.gd - 使用 ResourceLoader 线程安全地预加载后台房间。
• safe_scene_switcher.gd - 延迟场景切换模式，稳定地切换跨房间世界状态。
• minimap_fog_revealer.gd - 基于 Vector2i 的战争迷雾清除逻辑，与玩家位置同步。
• persistent_progression_system.gd - 用于追踪全局能力／收集品标记的 Autoload 模式。
• ability_state_machine.gd - 针对移动／战斗状态优化的 StringName 模式匹配。
• fast_wall_detector.gd - 直接查询 PhysicsServer，实现高性能墙体检测。
• save_station_broadcast.gd - 与存档交互时，基于分组重置实体并执行治疗逻辑。
• decoupled_hazard_logic.gd - 用于通用伤害交互的接口式模式。
• smooth_room_camera_transition.gd - 基于 Tween 的摄像机边界插值，实现无缝房间移动。

---

核心循环

1. 探索 → 被锁阻挡
2. 发现 → 关键能力／Boss
3. 获取 → 新的移动／战斗工具
4. 回溯 → 捷径 + 双用途能力
5. 推进 → 解锁新生物群系

技能链

阶段	技能	用途
1. 角色	godot-characterbody-2d、godot-state-machine-advanced	紧凑的移动体验 + 能力状态
2. 世界	godot-tilemap-mastery、godot-scene-management	房间、生物群系、线程化切换
3. 系统	godot-save-load-systems、godot-ability-system	持久化闸门／收集品；解锁钥匙
4. UI	godot-ui-containers、godot-inventory-system	地图／库存／HUD
5. 平衡	godot-monte-carlo-balancer	软锁风险、回溯距离

---

架构（以脚本为先——不使用内联配方）

1. 游戏状态与持久化

必须：metroid_game_state.gd + persistent_progression_system.gd。房间绝不拥有全局能力标记。房间元数据使用 resource_local_to_scene，避免实例化的房间共享收集品状态。

2. 房间切换与快速旅行

必须：background_room_streamer.gd + safe_scene_switcher.gd。

快速旅行必须遵循 NEVER（线程化加载 + 延迟切换）——绝不能使用 ResourceLoader.load()／同步 change_scene：

class_name FastTravelSystem extends Node

var _pending_path: String = ""
var _spawn_id: StringName = &""

func travel_to_room(scene_path: String, spawn_id: StringName) -> void:
    _pending_path = scene_path
    _spawn_id = spawn_id
    var err := ResourceLoader.load_threaded_request(scene_path)
    if err != OK:
        push_error("Fast travel request failed: %s" % scene_path)
        return
    set_process(true)

func _process(_delta: float) -> void:
    var status := ResourceLoader.load_threaded_get_status(_pending_path)
    if status == ResourceLoader.THREAD_LOAD_IN_PROGRESS:
        return
    set_process(false)
    if status != ResourceLoader.THREAD_LOAD_LOADED:
        push_error("Fast travel load failed: %s" % _pending_path)
        return
    var packed := ResourceLoader.load_threaded_get(_pending_path) as PackedScene
    # SceneTree work must be deferred — never from a worker thread
    call_deferred("_swap_room", packed, _spawn_id)

func _swap_room(packed: PackedScene, spawn_id: StringName) -> void:
    GlobalState.target_spawn_id = spawn_id
    get_tree().change_scene_to_packed(packed)

3. 能力门控

必须：ability_unlock_resource.gd + progression_gate_manager.gd + ability_state_machine.gd。闸门从 Autoload 查询 StringName 能力——不要在房间脚本中硬编码能力字符串。

4. 地图／战争迷雾

必须：minimap_fog_manager.gd。仅使用 Vector2i 单元格。

---

设计原则（来自 Dreamnoid）

• 能力多用性 — 兼具移动与战斗用途
• 练习房间 — 先教学，再惩罚
• 地标 — 无需明确标记，构建心智地图
• 物品微故事 — 无需冗长过场动画，也能传达背景故事

常见陷阱

1. 单向阀导致软锁——始终确保玩家能用当前能力脱困
2. 回溯枯燥乏味——解锁后提供捷径 + 更快移动方式
3. 空荡的死路——每条偏僻路径都需要有奖励
4. 同步加载房间——违反 NEVER；使用线程化请求 + 延迟切换

专家知识（按需）

**大模型无知规则：**如果通用 Agent 在阅读前不会知道某项知识，就加载参考资料——绝不要删除专家补充内容。

• expert-metroidvania-patterns.md — 恢复基础教学内容（架构、原因、实现深度）
• room_metadata.gd
• progression_manager.gd
• fast_travel_system.gd

参考资料

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

官方文档

• 使用 CharacterBody2D — 用于土狼时间／输入缓存跳跃和冲刺移动的 move_and_slide、地面检测及速度规则。
• 空闲与物理处理 — 在 _physics_process 中处理跳跃弧线、冲刺和贴墙滑行；在输入回调中捕获输入缓存。
• InputEvent — 使用 _unhandled_input 缓存跳跃／能力输入，避免按键操作在物理帧之间丢失。
• 后台加载 — 使用 ResourceLoader.load_threaded_request 预加载相邻房间，避免明显卡顿。
• 手动切换场景 — 延迟切换房间、生成点门 ID，以及安全地对即将退出的房间调用 queue_free。
• 保存游戏 — 在不同会话间保存能力、已开启的闸门、收藏品和已访问的地图单元格。
• 单例（自动加载） — 由全局进度／游戏状态统一管理，避免房间保留相互冲突的能力标记。
• 资源 — 将能力解锁定义和房间元数据保存为 .tres 数据，并进行安全复制。
• 使用 Tilemaps — 使用 TileMapLayer 和 Vector2i 单元格揭示小地图迷雾并追踪网格房间。
• Camera2D — 使用房间 limit_* 边界和补间限界交接，实现无缝的镜头房间切换。
• 使用 Area2D — 通过 body_entered 触发门、存档站和危险区域，无需场景间硬耦合。
• 群组 — 使用 call_group 广播存档站治疗／重生操作，而不必遍历整个场景树。

相关技能

前置条件

• godot-project-foundations — 在叠加房间流式加载和全局进度系统前，先了解自动加载、场景布局和项目设置。
• godot-characterbody-2d — 精准的平台游戏角色移动是能力门控式移动（冲刺、贴墙滑行、二段跳）的基础。
• godot-tilemap-mastery — 掌握分层 TileMap/TileMapLayer 的制作，用于游戏碰撞、地标和小地图迷雾网格。
• godot-autoload-architecture — 掌握能力标记和世界持久化的单例所有权模式，避免房间重复管理这些状态。

补充

• godot-scene-management — 线程化加载队列和延迟房间切换，让互联地图切换时不卡顿。
• godot-save-load-systems — 持久化的数据结构，用于在长时间探索过程中记录收集品、Boss 标记和已访问区域。
• godot-camera-systems — 房间边界、RemoteTransform 跟随和转场润色，超越基础 Camera2D 边界设置。
• godot-ability-system — 可解锁的移动/战斗能力，供门和状态机查询并作为“钥匙”使用。
• godot-state-machine-advanced — 层级式玩家状态，用于实现冲刺/蹬墙滑行/二段跳，避免嵌套的 if/elif 代码泛滥。
• godot-2d-physics — 图层、Area2D 门和危险区域，以及用于墙壁检测和避免软锁的阀门的直接空间查询。
• godot-inventory-system — 收集品/关键物品追踪，为地图奖励和能力获取界面提供数据。

下游 / 使用方

• godot-monte-carlo-balancer — 在门和奖励密度可调后，模拟能力解锁顺序、回溯距离和软锁风险。
• godot-genre-platformer — 纯粹的移动手感模式；移除能力门槛后，类银河战士恶魔城的探索玩法便以此为基础。
• godot-signal-architecture — ability_unlocked / gate_opened / map_revealed 信号总线，让 HUD 和房间能观察进度，而无需负责管理进度。

主入口

• godot-master — 库路由器和镜像模块入口；发现同级技能或在编辑 Domain Skill 后同步共享脚本镜像时使用。