# 弹射式安全箱与多格库存计划

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

本计划扩展[装备系统计划](EquipmentSystemPlan.md)，统一弹射保全、二维格子库存和机毁结算。首个可玩切片与实测范围见[装备验证](../QA/Equipment/DataFoundation.md)。

## 已确认的玩法与首测参数

用户已确认以下规则：

- 增加**弹射式安全箱**。机体被摧毁时，安全箱自动发射回基地，保护箱内物品。
- **任何放得下的未安装物品都能放入安全箱**，包括完整武器和机体模块。准入按装配状态与空间判断，不按物品类别限制。
- 库存采用**二维格子**，物品有宽、高，可旋转，必须实际放进连续空位。
- 安全箱是已确认的机毁损失例外：普通携带装备及货物仍会损失，基地库存与已经回收的物品保留。

以下容量和物品尺寸为首轮试玩建议值，可依据实际收益和背包操作调整，尚不是最终平衡数值。本阶段使用新建的 v2 存档。

| 容器 | 建议尺寸 | 使用方式 |
| --- | --- | --- |
| 普通货仓 | 4×4，16 格 | 携带战利品和卸下的装备，机毁损失。替代原先“最多 4 个条目”的容量规则。 |
| 主动货舱 | 2×2，4 格 | 每次出击 1 次，继续原地准备 3 秒后发射；按装舱布局校验，替代原先“至多 2 个条目”的选择限制。 |
| 弹射式安全箱 | 2×2，4 格 | 独立保护空间；机毁自动返库，正常撤离随整机回收。后续可配置更大型号。 |
| 基地库存 | 首轮沿用无硬上限的库存与收货列表 | 显示物品尺寸并支持整理；回收不能因基地摆不下而失败。以后增加有限网格仓库时提供待整理区。 |

两种回收舱分别记录状态与次数。主动货舱发射不消耗安全箱，安全箱也不占主武器、副武装、推进器或防护槽。

## 多格物品与二维摆放

### 物品占格示例

| 物品 | 建议占格 | 说明 |
| --- | --- | --- |
| 合金、电芯材料堆 | 1×1 | 每堆最多 10 个，1–10 个仍占同一块空间；第 11 个需要另一个堆叠与空位。 |
| 蓝图 | 1×1 或 1×2 | 不同型号可以有不同尺寸，单张不可堆叠。 |
| 小型电子配件 | 1×1 或 1×2 | 作为后续配件内容的尺寸约定，首轮不要求先完成配件玩法。 |
| 紧凑副武器 | 1×2 | 可整体放入建议的 2×2 安全箱。 |
| 轻型主武器 | 1×3 | 占 3 格，但两个朝向都放不进 2×2 安全箱。 |
| 标准主武器 | 2×3 | 占 6 格，需要普通货仓或更大的安全箱。 |
| 重型主武器 | 2×4 | 占 8 格，以占用空间形成携带取舍。 |
| 推进器、防护模块 | 1×2 或 2×2 | 完整模块只要尺寸匹配即可放入安全箱。 |

具体型号通过物品配置填写尺寸，不根据模型包围盒推算，也不通过名称或品质猜测。首轮使用矩形占格；附件或折叠状态以后若改变尺寸，需重新校验完整摆放，不能挤出或删除其他物品。

### 摆放与流转规则

1. 配置记录 `width`、`height`；摆放记录容器、格子坐标与朝向。旋转为 90°，宽高互换，面积不变。所有未安装矩形物品支持旋转。
2. 放置需要每个覆盖格都在边界内且未被占用。既检查面积，也检查形状；总空格足够仍可能摆不下。
3. 拖拽时显示物品轮廓和有效/无效位置，R 键旋转。保留点击选择物品再选择目标容器、键盘确认/取消的操作途径，避免必须依赖精确拖拽。
4. 自动放置按稳定次序寻找连续空位，并提示采用的方向。自动放置不移动其他物品；整理只在玩家明确操作的容器内进行。
5. 容器之间移动、交换与旋转全部先预检，再一次提交。失败、取消或保存失败时保持原位置和数量；交换时同时计算双方移出后的空位。
6. 材料支持拆分、合并与部分转移。数量总和保持，拆分产生新堆叠 UID，合并退休被合并堆叠的 UID；装备实例 UID 始终不变。
7. 已安装装备先卸下才进入货仓或安全箱。直接卸入安全箱时要在同一事务中清空装备槽并放入；放不下则整个动作失败。
8. 局内允许卸件后出现空槽。运行时使用明确的无装备状态：空主/副武器槽不能射击，空推进器/防护槽只保留底盘固有能力，不以索引回退偷偷生成默认装备。
9. 占格、物品数量、质量与额定功率分别定义。二维体积不直接换算载重；已安装装备继续遵守底盘配装预算。

## 弹射式安全箱的使用

- 每台机体出击时携带一个独立安全箱。首轮视为底盘的基础保全功能，箱体本身不作为可重复刷取的战利品；安全箱内容是有实际归属的库存物品。
- 玩家可以在出击前或局内把物品放入安全箱，也可以取回普通货仓或安装。放入成功保存后即显示“机毁可保全”；拖拽预览和未完成转移不形成保护。
- 所有普通未安装物品一视同仁，包括武器、模块、材料、蓝图。没有按价值、品质或装备类别设置的准入黑名单。容器尺寸、空位、当前归属与事务锁仍需有效。
- 救济借用件若装入安全箱，返基地后归还救济池；保留其借用来源，不转换为个人永久装备或材料。该来源规则不改变普通物品的占格与准入方式。
- 机体被摧毁时自动触发一次弹射，首轮可靠返基地，不设置额外按键、准备条、费用、成功概率或途中被击毁的判定。
- 正常撤离时安全箱内容随整机一起入库，不额外再结算一次弹射。普通退出、切换战区、断开视角或手动关闭菜单都不触发返库。
- 致命状态锁定后不能再塞物品、拆分、卸件或改摆放；弹射内容取自机毁时最后一份有效归属快照。
- 空箱机毁可显示“无保全物品”，但仍将本次机毁与箱状态一并完成，重复回调不能再次产生收益。

安全箱内的高价值整件装备同样可保全，机毁的实际损失取决于玩家此前如何分配空间。容量升级的费用与获取方式在基础循环实测后设计，不改变准入原则。

## 三种回收方式与结算顺序

| 事件 | 回收范围 | 后续状态 |
| --- | --- | --- |
| 主动发射货舱 | 普通货仓中选定且可实际装进主动货舱的物品。允许拆分材料后再选取。 | 发射成功即入库，货舱已用；安全箱与机上其余物品仍属当前出击。 |
| 正常登机撤离 | 已安装装备、普通货仓与安全箱内容，按实际归属回收。 | 结束出击；不生成机毁弹射收益。 |
| 机体被摧毁 | 仅安全箱中已保存的物品自动弹射返库。 | 普通货仓、已安装装备和留在战区的物品损失，结束出击。此前主动送回的收益保留。 |
| 致命帧与货舱发射同时发生 | 先锁定致命状态；此前已经成功提交的主动回收保留，尚未提交的发射取消。 | 同一物品只按一次已完成的所有权转移处理。 |
| 写入失败 | 不提前改变物品归属，不播放返库成功。 | 锁定机毁现场并重试；从有效快照恢复后继续同一笔结算。 |

建议为弹射保留独立事件键 `<runId>:secure_eject`，原 `<runId>:cargo` 与 `<runId>:return` 保持不变。具体新字段和事件常量随存档方案确认后冻结。

机毁流程按以下顺序实现：

1. 识别并锁存机毁，关闭库存操作、换装、主动货舱提交和登机入口。`GameSession` 必须优先处理致命状态，避免当前“交互/货舱之后才检查生命”的顺序允许临终补放物品。
2. 在候选快照记录待结算的毁坏状态及安全箱条目引用，冻结其内容与本次事件键。此步骤不将条目同时复制到基地；待结算记录不是第二个所有者。
3. 计算完整机毁结果：安全箱内容转基地库存或收货区，清除箱内归属；记录弹射收据；清除普通出击物品；结束本次出击并记录既有 `:return` 收据。上述变更一次写入后共同生效。
4. 成功保存后播放脱离、点火、返航效果和机毁报告；动画结束或取消都不再修改库存。报告分列“主动送回”“安全箱保全”“机毁损失”。
5. 若最终写入失败，保留可重试的待结算状态，不能返回可自由操作的战区。重载发现待结算机毁或已保存的零装甲活动出击时，先恢复结算再开放输入。

待结算记录也无法写入时，不声称未落盘的机毁已经持久化；保持当前锁定状态重试，重启按上一份完整有效快照恢复。基地库存后来若引入硬容量，自动弹射物品进入待整理区，不因摆放失败而丢失，整理也不重新发放收益。

## 数据、迁移与界面安排

| 模块 | 扩展内容 |
| --- | --- |
| 物品配置 | 物品类型、基础长宽、堆叠上限和尺寸版本；装备型号 ID、实例 ID、蓝图 ID 保持稳定。 |
| 容器定义与运行记录 | 容器类型、宽高、物品摆放坐标与朝向；普通货仓、安全箱、主动装舱布局分别记录，避免共用一个物品列表。 |
| 网格服务 | 放置/移出/旋转/交换/拆并堆叠/自动摆放的预检与事务；每个格子的占用从权威摆放记录派生。 |
| 出击与存档 | 安全箱状态、物品唯一归属、待机毁结算记录与弹射收据；与既有回收、完整快照和备份逻辑共用一个提交入口。 |
| 装备与属性 | 支持空槽与按实例卸装；保存成功后才刷新属性、模型和预算显示。 |
| UI 与本地化 | 普通货仓/安全箱并列展示、物品尺寸、旋转与错误原因、可保全标记、装舱预览、保全/损失明细，完整支持中英文与键鼠。 |

本轮按用户要求直接写入新 v2 档。恢复时校验唯一归属、坐标、堆叠上限、已装槽位及回收收据；损坏主文件可从完整备份恢复。旧版迁移延后。

UI 推荐同屏展示普通货仓与安全箱，并始终显示当前箱内内容的保护状态。主动货舱打开单独的装舱预览；选择数量不再限制为 2 个，最终以合法摆放为准。颜色之外提供文字与形状提示，拖拽或旋转不改变当前战斗菜单的输入交接规则。

## 实施顺序

| 编号 | 与装备计划的关系 | 交付与完成条件 |
| --- | --- | --- |
| S1 | E1 数据底座 | 冻结长宽、容器坐标、朝向、空槽、安全箱与待结算结构。 |
| S2 | E2/E3 前置 | 网格预检与转移、旋转、拆并堆叠；覆盖面积够但形状不符、交换和失败回滚，确保无复制或吞物。 |
| S3 | E3 搜刮换装 | 同屏普通货仓/安全箱 UI、卸入安全箱、拖拽旋转与替代键盘操作；跨区和重载保留布局、归属与保护状态。 |
| S4 | E4 回收结算 | 主动货舱改为按布局装载，加入机毁锁存、自动弹射、独立收据与可恢复的完整结算。 |
| S5 | E5/E6 展示 | 保全/损失报告、双语与布局回归；Blender MCP 制作弹射箱及挂点，Unity MCP 接入弹射效果，画面不承担库存结算。 |
| S6 | E7 验收 | Unity MCP 测试、编辑器回放、Windows 构建与实机操作，记录保护收益与空间选择，对首测容量进行平衡。 |

先完成网格与唯一归属，再接安全箱 UI 和自动结算；第一轮可用占位效果验证弹射，不等待最终模型才验证数据行为。

## 必须覆盖的验收

| 场景 | 预期结果 |
| --- | --- |
| 2×2 箱尝试放入 1×3 武器 | 两个朝向都拒绝，虽然面积足够；物品保持原处。 |
| 1×2 武器放入仅有横向连续空位的区域 | 旋转后可放入，重载保留同一 UID、坐标和朝向。 |
| 未安装完整武器或 2×2 模块装入安全箱 | 合法尺寸即可成功，机毁后整体保全，不能按装备类别拒绝。 |
| 已安装武器直接卸入安全箱，成功/放不下/写入失败 | 成功时槽位为空且箱内独占该 UID；失败时原装备、属性、模型和箱布局均保持。 |
| 空格数足够但连续形状不足、越界或重叠 | 拒绝并显示具体原因，取消与拖出界面不丢物。 |
| 材料拆分、合并至上限，移动部分数量进入安全箱 | 各处数量总和守恒，超限部分明确保留；只保全实际放入数量。 |
| 已装满安全箱的正常撤离 | 内容只入库一次，没有额外弹射收益。 |
| 普通货仓有武器、安全箱有另一件武器后机毁 | 安全箱武器以原 UID 返库，普通武器损失；基地原库存保持。 |
| 主动货舱已发射后机毁 | 主动送回与安全箱保全各结算一次，剩余普通物品损失，两个舱互不消耗。 |
| 机毁同帧尝试塞箱、换装、发射、登机或重复机毁回调 | 已锁存机毁阻止后续操作，结果遵守提交顺序，不双结算、不临终补塞。 |
| 待结算快照重载、结算写入失败后重试、动画重复回调 | 使用同一事件键与物品归属重试，只形成一次基地收益。 |
| 普通退出、跨区、试验场机毁 | 不将未结算物品凭空送回；跨区保持箱布局；试验场收据与物品不进入正式档。 |
| 鼠标拖拽、R 旋转、键盘确认/取消、切换中英文 | 逻辑结果一致，错误说明与保护标记完整，物品位置和选中状态保持。 |

原有“3 个条目超过两格货舱”的容量测试需改写为空间断言，不能让过时的条目数量限制继续影响新规则；重复选择、事件去重、写入失败和完整快照恢复覆盖继续保留。

归档沿用 `Docs/QA/Equipment/` 与 `Builds/Windows/x64/Equipment/`。按实际完成情况分别记录静态检查、Unity 编辑器测试、独立程序操作与性能采样；本轮设计文档不代表功能或测试已经交付。