unity/Docs/Production/EquipmentSystemPlan.md

# 搜打撤装备系统扩展计划

2026-11-12。工作区：`D:/vibeCoding/unityRouge/workTree/tree1`；分支：`codex/models-weapons-equipment-animation`。

首个装备数据切片已接入运行时，验证记录见 [装备验证](../QA/Equipment/DataFoundation.md)。关联文档：[玩法设计](../Design/GameDesign.md)、[总实施计划](ImplementationPlan.md)、[文件规范](ProjectConventions.md)。

## 目标与决策状态

将现有的蓝图解锁与局内换件，扩展为装备实物循环：**机库配装 → 携装出击 → 搜索与换装 → 主动货舱/整机回收或机毁安全箱弹射 → 整理、制造与维修 → 再次出击**。每件装备有独立身份，上一局带出的那件武器可以成为下一局的带入装备。

2026-11-12，用户已确认：**装备实物可带出入库、下局带入；机毁时安全箱自动弹射回基地，箱内物品保全，箱外携带装备与未回收物资损失，机库库存保留。** 安全箱可装下任何尺寸合适的未安装物品，包括完整武器与机体模块；库存采用可旋转的二维格子。[玩法设计](../Design/GameDesign.md)已据此更新；局内临时强化仍在出击结束时重置。本轮使用独立 v2 存档。

| 决策 | 状态 | 方案与影响 |
| --- | --- | --- |
| 装备跨局归属与损失 | 用户已确认 | 实物装备可回收入库、下局带入；机毁保全安全箱内容，损失箱外装备和未回收货物。底盘解锁、蓝图和已入库物资继续保留。 |
| 弹射式安全箱 | 用户已确认 | 机毁自动发射返基地，任何放得下的未安装物品均可放入，包括完整武器与模块。 |
| 多格库存 | 用户已确认 | 物品有长宽，在二维格子中实际摆放，可旋转；容量不再只按物品条目数判断。 |
| 存档演进 | 用户已确认 | 本阶段从 v2 新档开始，正式档与试验场档分别保存。旧档迁移延后。 |

具体容量、制造、救济装和后续配件等细则仍按推荐方案规划。弹射箱与格子规则详见[弹射式安全箱与多格库存计划](EjectionSafeCaseAndGridPlan.md)，其 S1–S6 合入本计划首个可玩工作包。

## 开发前的工程基线

| 位置 | 已有能力 | 本次需要补齐 |
| --- | --- | --- |
| [EquipmentDefinition.cs](../../Assets/Game/Scripts/Equipment/EquipmentDefinition.cs) 与 `Assets/Game/Data/Equipment/` | 9 件静态定义；主武器、副武装、推进器、防护四槽；载重、功率、伤害、射速、速度系数等字段。 | 独立实物实例、内容索引、明确的装备效果和模型绑定。 |
| [GameSession.cs](../../Assets/Game/Scripts/Runs/GameSession.cs) | 初始配装、预算检查、三项蓝图研究、局内替换和跨战区状态。 | 真实库存扣取、旧件去向、实例归属；换装提交失败时不能应用外观或显示成功。当前 `Install` 没有处理提交返回值。 |
| [ProfileStore.cs](../../Assets/Game/Scripts/Save/ProfileStore.cs) | v1 快照、材料与蓝图、4 格货仓、2 格货舱、回收事件去重、备份与写入失败处理。 | 装备入库/携出/损失、容器余量、迁移与未知版本保护。当前装备是 `int[4]` 索引；`Bank` 会将合金、电芯以外的物品当作蓝图处理。 |
| [WarzoneDirector.cs](../../Assets/Game/Scripts/Runs/WarzoneDirector.cs) | 固定灰盒搜索点、搜索来源编号、部分箱体附带换件选项。 | 可保留剩余物品的容器、真实装备掉落与地面旧件。当前领取材料/蓝图与换件选项绑定。 |
| [MechPilot.cs](../../Assets/Game/Scripts/Mechs/MechPilot.cs) | 共用双视角命中、武器伤害与射速、推进器速度、防护减伤。 | 配装后的统一属性结果、实际装备模型和枪口挂点。当前枪口位置为代码偏移，`ApplyLoadout` 主要处理机体缩放。 |
| [GameHud.cs](../../Assets/Game/Scripts/UI/GameHud.cs) | 机库轮选配装、简单部件比较、货舱选择、研究与双语刷新。 | 实物库存、装备详情、明确的换装/丢弃/回收动作和收益明细。 |
| [ProfileStoreTests.cs](../../Assets/Tests/EditMode/ProfileStoreTests.cs) | 原有 6 项存档与回收测试。 | 保留去重与故障恢复覆盖，容量断言按二维规则更新；新增实例、迁移、格子与安全箱场景。已有验收记录不代表 tree1 已通过本轮测试。 |

## 首个可玩版本的装备规则提案

### 1. 配装与装备价值

- 沿用四槽：主武器、副武装、推进器、防护模块。先复用现有 9 件定义，保存其 ID 与 GUID；底盘仍作为永久解锁的平台。
- 同型号可拥有多件实物，分别用唯一 `instanceId` 区分。型号配置与物品实例分开，界面按物品实例进行携出、换装和回收。
- 出击前从机库选择实物。开始出击的一次成功保存，将所选装备从机库转入本次出击；配装预览不转移所有权。
- 蓝图研究解锁制造配方；制造消耗库存材料并产生一件实物。研究费用与制造费用分别配置，已研究不再等同于无限免费携装。
- 新存档获得一次基础四槽装备。无可用配装时可使用绑定本次出击的低配救济装；借用件可以按尺寸放入容器和安全箱，返基地时归还救济池，不能转成个人永久库存或制造材料，避免资源循环套利。
- 首轮直接比较伤害、射速、机动、防护、载重和功率。型号需要有明确取舍；更强火力也可能带来更高负担。

### 2. 搜索、存放与换装

- 物品按定义的宽高在二维容器中摆放，支持 90° 旋转。首测建议普通货仓 4×4、主动货舱 2×2、安全箱 2×2，具体数值可调；每次出击仍只有 1 次主动货舱发射。材料每堆最多 10 个，装备不可堆叠，不同装备可占多格。
- 搜索箱显示实际物品，玩家逐件领取、比较或直接换装。领取后剩余内容仍保存在容器中，满仓不会消耗物品或锁死来源。
- 换装时重新校验槽位兼容、载重、功率和旧件去向。旧件可进入货仓；没有位置时需明确选择交换回原容器或放到地面，不能静默删除。
- 地面装备与容器剩余装备均有稳定实例 ID，跨存档重载保持；卸件、拾取、交换、丢弃均按一次完整事务提交。
- 安装中的武器、推进器和防护模块参与额定功率与配装载重检查；携带的货物不消耗额定功率。普通货仓、安全箱及主动货舱分别校验边界、重叠与可用形状，货物重量影响机动列入后续平衡。
- 可将装备直接卸入安全箱：校验并保存后清空槽位，不能通过默认索引重新生成装备。局内空槽采用明确的无武器/无模块行为。
- 局内菜单沿用现有输入与暂停规则；打开装备界面交接战斗输入，关闭后需要重新按射击键，完整保留双视角操作。

### 3. 主动货舱、安全箱、撤离与机毁

| 事件 | 装备与货物归属 |
| --- | --- |
| 发射准备被移动、受击或松键打断 | 物品继续在机上，货舱可重试；首轮沿用 3 秒准备。 |
| 成功发射货舱 | 从普通货仓装入可实际放进主动货舱网格的未安装物品；扣货、入库、货舱已用、事件编号在同一快照中保存。安全箱状态不变，不能继续按“至多 2 个条目”限选。 |
| 运输机抵达但未登机 | 所有剩余装备和货物仍在本次出击；沿用 15 秒接应等待与主动登机。 |
| 主动登机 | 已安装装备、普通货仓和安全箱内容按实际归属回收，借用件归还救济池，结束出击；不额外结算一次弹射。 |
| 机毁 | 先锁存机毁，安全箱中已保存物品自动弹射返库；清除箱外携带和留在战区内的装备、货物。安全箱入库、机毁损失与结束出击共同提交；之前已送回的物品、永久解锁和终局战果保留。 |
| 写入失败 | 普通操作保留原归属并可重试；机毁则锁定待结算现场，不开放库存或战斗输入。不先移除物品、播放成功回收或应用新配装。 |
| 正常退出或重载当前出击 | 恢复已保存的装备、容器、地面物品、货舱与收据；退出不直接触发返库。 |

货舱仍用既有 `<runId>:cargo`，整机结算仍用 `<runId>:return` 去重；安全箱拟用独立 `<runId>:secure_eject`，在具体存档方案中冻结。相同物品不会同时归属基地与安全箱，致命状态锁存后不能临时补塞物品。蓝图、材料、装备按明确类型分别入库，禁止继续依靠“其他物品就是蓝图”的分支。

### 4. 首轮内容与后续扩展

| 层级 | 交付内容 |
| --- | --- |
| 首个可玩切片 | 现有 9 件定义、四槽实物配装、机库库存、制造、二维货仓与旋转、多格物品、弹射式安全箱、旧件流转、主动货舱/撤离/机毁与旧档迁移；装备界面随各步骤提供基本操作。 |
| 模型与动作接入 | 先完成 1 把主武器及 1 件替换部件的独立模型与实际挂接，再覆盖现有 9 件；补充开火后坐、瞄准、推进和换装展示。 |
| 下一轮装备深度 | 装备耐久与维修；少量固定品质与型号变体；瞄准、枪口、供能类配件及兼容规则；基于完整出击收益调整制造消耗与掉落。 |
| 另行设计的扩展 | 有限弹药与装填、仓库扩容、额外机体槽、保险、交易及随机词条。各项需单独评估对经济、动作和存档的影响。 |

首轮保留现有射击与能源规则，品质、配件、耐久不会一次性引入；核心循环通过后再逐项增加。

## 数据与实现安排

| 数据/模块 | 拟定职责 |
| --- | --- |
| `EquipmentDefinition` 与内容索引 | 保留稳定型号 ID 与槽位编号；明确蓝图/配方映射及效果，绑定展示资源。用内容索引查询，避免把数组顺序继续写进新存档。 |
| `EquipmentInstance` | 保存实物唯一 ID、型号 ID 与来源标记；耐久和配件随对应阶段新增，静态数值由定义读取。 |
| 机库、出击槽、普通货仓、安全箱、容器、地面记录 | 一个实例同时只属于一处。各处持有实例或稳定引用的具体序列化方式在 E1 冻结；归属只保留一个权威来源，界面列表由它派生。 |
| 物品条目与容器快照 | 显式区分材料、蓝图、装备；记录物品长宽及尺寸版本、容器大小、坐标、朝向、剩余条目和掉落结果。以出击/战区/来源组成稳定键，重载不会重新抽取或改变布局。 |
| `EquipmentService` / 网格与配装校验 | 在候选快照内处理制造、携出、换装、卸件、旋转、拆并堆叠和流转；统一校验唯一归属、摆放合法性、兼容与预算。支持局内空槽；先成功保存，再通知运行时与 UI。 |
| 有效属性与外观绑定 | 根据已安装定义计算属性结果；在配装变更时更新，战斗读取同一结果。模型/动作按定义挂接，枪口判定读取实际挂点并保留近墙检测。 |
| `ProfileStore` | 延续快照提交、备份与既有事件语义，接入布局迁移、待机毁结算、安全箱弹射与装备回收。玩法服务执行校验，存档层负责完整状态落盘。 |

主要代码放在现有 `Scripts/Equipment/`、`Scripts/Save/`、`Scripts/Runs/`，物品与容器按职责进入 `Scripts/Loot/`。配置沿用 `Data/Equipment/`，未来掉落表进入 `Data/Loot/`。计划中的新路径在实际实施时建立。

装备 UI 消费查询结果与明确的装备操作接口，地图通过容器来源 ID 和掉落配置接入，便于界面与地图工作整合。避免把库存、掉落和展示继续集中追加到 `GameSession` 或 `GameHud`。

### 当前存档与恢复

正式档为 `profile-v2.json`，试验场档为 `range-v2.json`。编辑器在各自工程的 `UserSettings/Ironspore/` 下运行。物品 UID、格子坐标、朝向、已装槽位和收据随完整快照写入，机毁结算失败后使用同一出击编号重试。v1 迁移留待后续独立安排。

## 实施顺序与完成条件

| 编号 | 依赖 | 工作与交付 | 完成条件 |
| --- | --- | --- | --- |
| E0 | 跨局规则已确认 | 核对 tree1 完整路径，完成独立存档与 PlayerPrefs 隔离；用准确 `Name@hash` 绑定 Unity MCP，完成导入、编译并记录原测试基线。需要建模时另读 Blender 当前文件与场景。 | 目标工程和测试数据路径明确，原有测试实际通过，能够独立启动当前原型。 |
| E1 | E0 | 固定槽位/型号映射，建立装备实例、物品尺寸、二维容器、安全箱与待机毁记录、唯一归属校验，合入 S1/S2 并冻结字段清单。 | 非法索引、未知版本、重复实例、无效布局和写入失败均保留有效原状态。 |
| E2 | E1 | 机库实物库存、出击配装、一次性基础装与救济装、研究配方与制造；提供最小库存/配装 UI。 | 预览不扣库存；出击仅携出所选实例；制造正确扣料；不能从同一库存实例装两处或刷救济收益。 |
| E3 | E2 | 可持久化容器、二维摆放/旋转、逐件领取、比较换装、卸入安全箱及空槽行为，合入 S3；接入载重/功率与有效属性。 | 面积与形状均合法才转移；完整武器/模块可按尺寸保全；旧件始终有去向；重载保留布局，换装失败保持属性、模型和库存一致。 |
| E4 | E3 | 主动货舱改按实际摆放装载，扩展整机回收、机毁自动弹射、待结算恢复与报告明细，合入 S4，沿用既有结算编号。 | 同一实物带出后可在下一局再次带入；安全箱保全、普通损失与出击结束共同提交；重复货舱、弹射、登机或机毁回调不会增物。 |
| E5 | E2–E4 | 完成库存筛选、尺寸/旋转、装备详情、预算差值、制造材料、装舱预览与保全/损失报告，覆盖双语、焦点和快捷操作。 | 鼠标拖拽和键盘替代操作均可用；切换语言保持布局、选择和页面；1280×720、1920×1080、2560×1440 中关键操作可见、无溢出。 |
| E6 | E1 定义与挂点接口；联调依赖 E3 | Blender MCP 制作可拆换的模型，沿用 `Mount_Primary`、`Mount_Secondary`、`View_Cockpit`，约定新增推进/防护挂点；Unity MCP 导入组装并连接动作。 | 先验证一把武器和一个替换件；挂载、枪口、碰撞、第一人称视野、后坐与命中一致，重复导入保持 GUID 与引用。 |
| E7 | E4、E5、E6 | 通过 Unity MCP 完成 EditMode、编辑器回放与 Windows x64 构建，轮询任务结束；启动完整产物目录试玩并归档。 | 下方验收用例实际通过，Console 与报告可查；完整出击与单独实例性能采样有实测记录。 |

第一个开发工作包按 **E0 → E1 → E2 → E3 → E4** 推进，各步附带必要 UI。E5 完成界面回归，E6 完成模型与动作；二者通过后进入 E7。完成首个切片后，再安排耐久、配件与经济扩展的独立工作包。

安全箱箱体、弹射挂点、脱离与返航效果随 E6/S5 制作，库存提交由数据层负责，动画回调不发放收益。S6 与 E7 共用测试、构建和试玩归档。

## 模型与动作交付约定

- Blender 源文件进入 `SourceAssets/Blender/Mechs/` 或相应装备子目录，导出进入 `Assets/Game/Art/Models/`；源、导出物、预制体与定义使用可追溯的资产编号。
- 保留既有机体与挂点名称。装备模型单独挂接到项目预制体，重复导出检查单位、朝向、原点和枪口，避免更换武器时重做整台机甲。
- 首轮动作覆盖待机/移动中的开火与瞄准、后坐恢复、推进反馈及换装后外观更新。两种视角读取同一次开火事件和枪口，动作不另行决定伤害。
- 在现有试验场及战区中逐件替换和验证。独立模型、挂点、动画、材质与必要音效按[素材台账](AssetSources.md)登记来源；下载内容保留许可。

## 验收用例与归档

| 场景 | 必须观察到的结果 |
| --- | --- |
| 同型号两件、同一实例重复选择 | 两件独立保存并显示；同一实例不能装入两个位置。 |
| 携装出击后重载/继续出击 | 机库不保留同一件实物，活动出击持有它，继续出击不再次扣取。 |
| 出击开始、制造、换装、拾取或回收写入失败 | 材料、装备、来源、收据与运行时属性仍为操作前的完整状态，可安全重试。 |
| 满仓换武器、取消换装、原地丢弃并拾回 | 玩家明确选择旧件去向；实例 ID 不变，无删除、复制或满仓吞物。 |
| 部分搜取后重载、重复打开同一容器 | 只显示剩余物品；型号、数量、实例 ID 保持一致。 |
| 送回装备后机毁 | 已主动送回装备在库，安全箱内容自动保全；箱外已装与剩余货物损失，各自只结算一次。 |
| 运输机抵达但未登机，随后登机 | 到场时不入库，主动登机后才将已装装备与剩余货物一起入库。 |
| 终局完成但未登机，随后机毁 | 战果保留，安全箱物品保全，箱外未回收装备和物资损失。 |
| 一件装备完成“出击→回收→再次出击” | UID 持续相同；每个检查点恰好处于一个位置。 |
| 救济装拆解、转移、安全箱保全或普通回收 | 借用来源保持，返基地归还救济池，各入口不能产生个人永久物品或资源；正常实物仍按规则带出。 |
| 多格摆放、旋转与安全箱完整保全 | 几何空间合法才放置；未安装完整武器/模块不按类别拒绝，机毁按原 UID 保全。详见 S1–S6 验收。 |
| 载重/功率超限、试验场退出、语言反复切换 | 预算提示准确；正式库存不被试验场修改；页面上下文、提示与已有报告正确刷新。 |
| 两种视角换装与近墙射击 | 枪口与命中保持一致，装备不遮挡关键视野；菜单关闭及失焦恢复后不误开火。 |

自动化重点为数据归属、状态流转、迁移、去重与写入失败，放入 `Assets/Tests/EditMode/`；通过 Unity MCP 定向运行并查询 job 到完成。UI、双视角和动作在编辑器与独立程序中分别实际核对。

阶段记录进入 `Docs/QA/Equipment/`，构建进入 `Builds/Windows/x64/Equipment/`。记录区分静态检查、编辑器测试和独立程序实测。60 FPS 按 1080p、中等画质、指定测试机与 P95 帧耗时目标采样；单局 20–30 分钟继续通过完整出击记录验收。

已执行的用例和剩余工作以本阶段验证记录为准。