Integrate endings rewards consumables and docs

[xinxiangchen]

新版系统整合改动详细说明

本文档记录本次新版整合中已经落地的代码改动，方便负责地图、角色、UI、系统逻辑、后续 C++ 重构的同学理解当前实现边界。

一、版本融合与分支基础

本次开发前先从 GitHub 主仓库拉取了最新 origin/master，并将本地已有改动与远端合并后的版本融合。

本次改动基于当前主流程继续开发，没有重新推翻原有架构。主要目标是把轮回、结局、关间奖励、消耗品、饰品掉落等玩法逻辑接入主程序，同时尽量保持模块职责清晰。

二、轮回与家族选择逻辑

相关文件：

• systems/run/lineage_director.gd
• ui/character_select.gd
• ui/heir_select_panel.gd
• app_entry.gd
• world.gd

已实现内容：

1. 轮回档案中记录当前家族、已登基家族、当前皇帝家族。
2. 第一轮通关后进入下一轮时，会禁用已经登基过的家族。
3. 选人界面支持接收禁用家族列表，并在 UI 上禁用对应角色。
4. 三个家族都登基后，再次完成最终 Boss 且未触发真结局时，会进入“戴上王冠”的坏结局。
5. 后继者加点逻辑由“直接加点”改成“属性转移”：从一个属性扣 1 点，给另一个属性加 1 点。
6. 评分到点数变化规则已经接入：S/A/B/C/D 分别影响下一代基础点数。

当前设计边界：

• 杀死阶段 Boss 不是大结局，只是轮回推进节点。
• 大结局必须由明确结局条件触发。
• 每一次选人/继承仍有 5 个血脉火种。

三、结局与存档封存

相关文件：

• systems/run/save_manager.gd
• systems/run/lineage_director.gd
• ui/save_slot_select.gd
• ui/result_screen.gd
• world.gd

已实现内容：

1. 存档二进制记录新增 ending_type 字段。
2. 最终结局触发后调用 SaveManager.seal_active_ending() 封存档案。
3. 已封存档案不能继续进入游戏。
4. 创档/选档界面会显示结局类型。
5. 封存保护不会覆盖已有结局，避免真结局被后续开放结局覆盖。

当前支持的结局类型：

• break_crown：打碎王冠，真结局。
• ember_extinguished：五个火种耗尽，火种熄灭结局。
• escape：奔向远方，开放结局。
• crown_bad：三个家族都成为皇帝后仍戴上王冠，坏结局。

当前开放结局实现：

• 普通阶段通关结果界面允许长时间停留触发“奔向远方”。
• 真结局界面不再允许被开放结局覆盖。

四、关间奖励三选一

相关文件：

• world.gd
• ui/stage_reward_panel.gd

已实现内容：

1. 普通关卡清场后，不再直接自动发奖励。
2. 普通关卡清场后会打开独立的“关间奖励三选一”面板。
3. 三张卡中混合出现“下一张小地图临时状态”和“消耗品”。
4. 每次三选一至少包含 1 个状态奖励和 1 个消耗品奖励。
5. 选择状态奖励后，会写入 RunDirector 的 pending encounter prep，只在下一张小地图生效。
6. 选择消耗品后，会加入消耗品栏。
7. 选择完成后才进入下一张地图。

状态稀有度：

• D：50%
• C：30%
• B：15%
• A：5%

当前状态池：

• 战斗专注：下一张图提高攻击伤害。
• 迅步：下一张图提高移动速度。
• 守势呼吸：下一张图提高护甲和生命上限。
• 澄心：下一张图缩短技能冷却。

注意：

• 旧的 run_event_panel 仍保留，后续商店、教堂、军需库可以继续使用或重构。
• 新的关间奖励面板 stage_reward_panel.gd 与商店事件解耦，不直接处理金币交易。

五、消耗品系统

相关文件：

• systems/consumables/consumable_manager.gd
• ui/consumable_bar.gd
• world.gd
• project.godot

已实现内容：

1. 新增 ConsumableManager 自动加载单例。
2. 新增 1-6 数字键消耗品栏。
3. 消耗品栏显示图标、快捷键编号、数量。
4. 消耗品可以由关间奖励获得，也可以由怪物掉落获得。
5. 消耗品使用逻辑封装在 ConsumableManager 中，世界主流程只调用公开 API。

当前消耗品：

• bandage_pack：绷带包，恢复 22% 最大生命。
• healing_vial：急救瓶，恢复 35% 最大生命。
• medkit：医疗箱，恢复 55% 最大生命。
• armor_patch：轻甲包，恢复 45% 最大护甲。
• inspiration_ampoule：守护蜡烛，恢复 45% 最大灵感。
• edge_oil：磨刀油，使下一场战斗攻击伤害提升 10%。

已接入的消耗品素材：

• assets/ui/consumable/bandage_pack.png
• assets/ui/consumable/first_aid_bottle.png
• assets/ui/consumable/medkit.png
• assets/ui/consumable/light_armor_pack.png
• assets/ui/consumable/protective_candle.png
• assets/ui/consumable/sharpening_oil.png

六、怪物掉落与地图拾取物

相关文件：

• world.gd
• systems/pickups/run_pickup.gd

已实现内容：

1. RunPickup 支持外部传入 icon，可以显示真实 PNG 图标。
2. 消耗品掉落会显示对应消耗品素材。
3. 饰品掉落会显示对应饰品素材。
4. 没有图标时仍保留旧的代码绘制图形作为兜底。

掉落规则：

• 小怪死亡：3% 概率掉落消耗品。
• 小怪死亡：0.1% 概率掉落饰品。
• Boss 死亡：随机掉落 1-2 个消耗品。
• Boss 死亡：100% 掉落饰品。
• 饰品稀有度按 D/C/B/A = 50/30/15/5 抽取后映射到现有饰品稀有度。

七、饰品展示位置

相关文件：

• ui/inventory_panel.gd
• world.gd
• systems/accessories/accessory_manager.gd

当前建议与实现方向：

1. 战斗主 UI 只保留“当前装备饰品摘要”，避免战斗界面信息过载。
2. 背包系统继续负责展示：
   • 当前饰品。
   • 饰品描述。
   • 饰品历史。
   • 饰品图鉴/目录。
3. 地图掉落中拾取饰品后会立即装备，并记录进背包历史。

后续如果要做“饰品背包多件持有”，建议不要直接塞进战斗 UI，而是在背包里做独立页签：

• 当前装备
• 已持有饰品
• 消耗品
• 图鉴

八、主流程变化

相关文件：

• world.gd

旧流程：

1. 选人。
2. 自动弹初始饰品。
3. 战斗。
4. 关间事件/饰品选择。

新流程：

1. 选人。
2. 直接进入第一张地图战斗。
3. 普通关清场。
4. 弹出关间奖励三选一。
5. 选择奖励。
6. 进入下一张地图。
7. Boss / 最终 Boss 清场后进入阶段结算或最终结局判断。

九、测试更新

相关文件：

• tests/smoke_run_flow.gd
• tests/smoke_accessory_flow.gd
• tests/smoke_lineage_save.gd

已更新内容：

1. 主流程测试不再要求“选人后必须弹初始饰品”。
2. 主流程测试改为检查选人后直接进入战斗。
3. 主流程测试新增关间奖励面板检查。
4. 饰品测试改为手动打开饰品面板，验证饰品系统仍可生成选择并装备。
5. 轮回/存档测试覆盖新增字段和继承逻辑。

已通过的 smoke 测试：

• tests/smoke_run_flow.gd
• tests/smoke_accessory_flow.gd
• tests/smoke_lineage_save.gd
• tests/smoke_story_endings.gd
• tests/smoke_ui_screens.gd

说明：

Godot headless 测试结束时仍会打印 RID/resource 泄漏警告，这是当前项目中已有的 headless 退出警告；本次验证以进程退出码为准，以上测试退出码均为 0。

十、后续建议

1. 背包系统后续应增加“消耗品页签”和“已持有饰品页签”，现在只是消耗品栏和饰品历史。
2. 商店、教堂、军需库应该复用 ConsumableManager 和后续武器升级 API，不要直接改角色字段。
3. 关间奖励池应继续配置化，后续可从 JSON 或资源表读取。
4. 饰品掉落目前是立即装备，未来如果要多件持有，需要引入饰品库存模块。
5. C++ 重构时优先抽离：
   • 存档记录读写。
   • 轮回评分与家族状态。
   • 奖励抽取与掉落表。
   • 消耗品栏数据结构。