unity/Docs/Production/ImplementationPlan.md

# 机甲射击落地开发计划

本计划把 [玩法设计](../Design/GameDesign.md) 拆成有前置依赖的开发任务，按 [项目规范](ProjectConventions.md) 存放产出。Unity 工程操作通过 Unity MCP 完成，3D 制作和导出通过 Blender MCP 完成。首个交付是 Windows PC 键鼠驾驶试验场，随后交付一个能搜索、运货、整机撤离并正确保存收益的战区，再扩展为 20–30 分钟的完整出击。

## 工程起点

tree1–tree3 最初的普通目录与资源副本已按 [资源初始化计划](TreeInitializationPlan.md) 完成，结果见 [初始化验收](../QA/Workspaces/Initialization.md)。该初始化阶段未创建分支或注册 worktree。

2026-11-12，`tree3` 已接入地图改善分支 `codex/map-improvement` 的独立 worktree。真实灯光、遮挡和动态阴影按 [地图光影优化计划](LightingOptimizationPlan.md) 实施。光照、独立动态阴影及功能回归通过；本机原生 1080p 中等档正式六组无限帧采样 P95 为 5.67–6.31 ms，三个候选画质档均通过。默认 60 FPS 限帧实测平均 60.01 FPS，但 P95 17.23–17.28 ms 未通过严格 16.7 ms 判据；烘焙、精确阴影增量和其他未验证范围见 [光影验收记录](../QA/Lighting/Acceptance.md)。

2026-11-12 增补的主页语言切换及全局双语工作按 [多语言实施计划](LocalizationPlan.md) 的 L1–L7 执行，完成后继续原有美术、实战与性能工作。

多语言增量已交付简体中文、English、主页右下角即时切换与独立偏好。验证与 Windows 产物见 [多语言验收记录](../QA/Localization/Acceptance.md)。

本轮已交付首个灰盒可运行原型，Windows 构建与自动化检查见 [原型验收记录](../QA/Prototype/Acceptance.md)。阶段 0–2 已有对应工程和核心流程验证，阶段 3–4 已接入配装、路线和终局状态。独立战区内容、动画、战斗平衡、20–30 分钟整局试玩与规范性能采样继续按表中任务推进。

以下工程起点与连接情况为执行前记录。

本次核查时，工程使用 Unity 6000.6.8f1，Assets 中只有示例场景与编辑器目录。示例场景包含相机和方向光，Windows 构建入口尚未登记，玩法脚本和首版资产需要随下列任务制作。

2026-11-11 的只读连接检查确认 Blender MCP 可访问 Blender 4.5.10 LTS，插件版本为 1.8，场景是尚未保存的默认场景。工程内已安装 MCP for Unity 10.3.0，包清单锁定 Git 提交 81542a7e86292b5c4c21b1782c5af23b567f45ce。当前会话的工具列表尚未提供 Unity MCP 调用，0.0 需要完成客户端联通与目标工程回读。Blender 的资产库集成当前未启用，素材获取先走公开网页下载与本地文件导入。

| 项目 | 当前情况 | 实施安排 |
| --- | --- | --- |
| 渲染 | 工程使用 Built-in 渲染配置。 | 灰盒与首版素材按此配置制作，导入时核对材质。 |
| 输入 | 包清单尚未包含 Input System，当前使用旧输入后端。 | 在 0.2 安装编辑器兼容的正式版 Input System，锁定包版本，切换输入后端并验证重启后的工程。 |
| 场景 | 现有 SampleScene，构建场景列表为空。 | 按阶段建立启动入口、机库、驾驶试验场和各战区场景。 |
| MCP 通道 | Blender MCP 已完成只读连接检查，Unity MCP 包已安装。 | 0.0 验证 Unity 客户端工具、目标工程身份和场景读取。 |
| 原型状态 | 玩法方案与文件规范已经归档。 | 工具检查已有上述记录，其余开发与模型导入验证随任务执行。 |

## 已采用的实施默认值

| 部分 | 实施方式 | 选择依据与检查点 |
| --- | --- | --- |
| 输入 | 一个 Input Actions 资产，包含驾驶与界面动作。默认键位沿用玩法设计。 | Actions 承载按键和动作关系。驾驶与界面切换时明确交接鼠标和开火输入。安装与后端切换遵循 [Input System 官方说明](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.20/manual/Installation.html)。 |
| 机体移动 | CharacterController 配合一个共享移动组件，轻、中、重三套配置。 | 水平移动、跳跃、升空、重力和能源都由机体逻辑计算。Move 接收位移且需要自行处理重力，详见 [Unity 6.6 API](https://docs.unity.com/en-us/engine/6000.6/script-reference/unityengine/charactercontroller/move)。 |
| 相机与武器 | 一个相机控制器切换越肩和驾驶舱挂点。武器共用瞄准目标与枪口检测。 | M1 检查近墙、视角切换和精瞄，确保镜头视野、枪口遮挡与实际命中可理解。 |
| 配置 | 底盘、装备、掉落和战区用 ScriptableObject 保存静态定义，使用稳定的内容编号。 | 当局耐久、能源、装备和战利品保存在运行数据中，编辑配置与存档数据各有明确用途。 |
| HUD 与菜单 | UI Toolkit 承载屏幕 HUD、货仓、机库和路线图。 | 使用 UXML、USS 与运行时组件。先验证简化驾驶舱和鼠标货仓交互，参见 [Unity 运行时 UI 说明](https://docs.unity3d.com/cn/6000.0/Manual/ui-systems/introduction-ui-toolkit.html)。 |
| 保存 | 本地带版本号的存档快照，同时包含机库、当前出击与已结算事件。 | 新状态写入成功后反馈入库，支持临时文件、完整快照替换和上一份有效备份。结算按出击编号和事件类型去重。 |
| 关卡 | 手工灰盒布局、任务和物资配置组合成分层路线图。 | 每个战区放置地面通路、搜索点、推进目标、下一站出口与整机撤离点。 |
| 模型与声音 | 用 Unity MCP 搭建占位战区，用 Blender MCP 制作机体、舱框和道具，并修整下载模型。声音按公开免费条目获取后导入。 | 在 0.4 用一个样件验证完整导出导入流程。每次替换资产后核对尺寸、挂点、材质与来源记录。 |

## MCP 工作分工

| 工作 | 执行通道 | 落盘与回读 |
| --- | --- | --- |
| 读当前工程、编辑场景与组件、组装预制体 | Unity MCP | 先读取当前工程路径和活动场景，使用相应场景、对象、组件和预制体工具修改，保存后回读层级与引用。 |
| C#、UXML、USS、配置文本与文档 | 工作区文件工具编写，Unity MCP 导入验证 | 代码按功能目录保存。修改后触发 Unity 刷新，等待编译结束，读取 Console，再进入播放验证。 |
| 建模、模型修整、挂点、材质和导出 | Blender MCP | 先读取当前文件与场景，在项目资产集合中工作，保存源 blend，按选定对象导出，回读尺寸并检查多角度预览。 |
| 免费素材获取 | 公开资源页与下载工具 | 保存原始文件、条目地址、许可和校验值，再交给 Blender MCP 或 Unity MCP 导入。登记在 [素材台账](AssetSources.md)。 |
| 编辑器测试、播放检查和画面检查 | Unity MCP | 定向运行测试并等待任务完成，读取结果与 Console。越肩和驾驶舱各保留实际画面截图。 |
| Windows 构建与试玩 | Unity MCP 发起构建，本机启动产物 | 等构建状态完成，确认可执行文件和日志，再实际启动试玩并写入验收记录。 |

Unity 工具名已对照工程内插件源码核查。场景使用 manage_scene，对象与组件使用 manage_gameobject、manage_components，资产与预制体使用 manage_asset、manage_prefabs，包使用 manage_packages，编译与错误读取使用 refresh_unity、read_console。测试使用 run_tests 并以 get_test_job 取结果，构建使用 manage_build 并轮询其 status。实施时以客户端实际提供的参数为准，先读后改，运行结果回写到阶段记录。

每轮 Unity 操作采用「读取工程和场景 → 小批修改 → 保存并等待导入／编译 → 读取结果 → 播放或测试 → 截图与日志归档」。涉及脚本重编译或编辑器重启时，恢复后重新读取工程和活动场景，再继续当前任务。

## Blender 与 Unity 的资产交接

1. 在 Unity MCP 中确定占位体尺寸和机体朝向，用同一份尺寸参照供 Blender 制作。源文件以米为尺度，机体根节点、武器挂点和驾驶舱视点使用稳定名称。
2. Blender MCP 保存 SourceAssets/Blender 下的源文件，导出选中的模型、骨架和必要挂点。自制 FBX 放到 Assets/Game/Art/Models，纹理和动画分别进入对应目录。原始下载文件进 SourceAssets/ThirdParty，导入的外部包进 Assets/ThirdParty。
3. Unity MCP 刷新导入并检查模型的实际尺寸、朝向、材质和挂点。项目自己的驾驶组件、碰撞体和控制逻辑组装在 Assets/Game/Prefabs 的预制体中。
4. 将资产放入试验场，用轻、中、重配置及两种相机检查碰撞、枪口遮挡和舱框视野。记录 Blender 预览和 Unity 实际画面，完成后再替换下一项。
5. 导出与修整中复用的 Blender 脚本保存到 Tools/Blender。重复导入同一资产时沿用已有文件与引用，保留 Unity 生成的 meta。

以下任务按编号跟踪。依赖完成后即可开始对应任务，每个阶段交付一份 Windows x64 可执行构建和对应的操作记录。

## 0 · 工程基线

| 编号 | 依赖 | 工作与文件产出 | 完成条件 |
| --- | --- | --- | --- |
| 0.0 | 工程起点 | 核对 Unity MCP 客户端连接与 Blender MCP。Unity 回读目标工程路径、编辑器状态、活动场景和 Console，Blender 回读版本、当前文件与场景。 | Unity 工程路径为本仓库，两个 MCP 均可成功只读调用。将结果归档到 Docs/QA/Environment。 |
| 0.1 | 0.0 | 通过 Unity MCP 核对编辑器、Windows 构建模块与现有包锁。建立版本控制基线，按规范配置 Unity 生成目录与构建产物的忽略规则。 | 工程可打开，包可解析，资产与 meta 可追溯。记录本机可构建的编辑器版本。 |
| 0.2 | 0.1 | 通过 Unity MCP 配置 Input System。动作资产放在 Assets/Game/Input/GameInput.inputactions，输入读取放在 Scripts/Input。建立 Bootstrap.unity 与最小启动逻辑。 | 编译通过，驾驶动作与界面动作可分别启用。切出窗口后重新聚焦，按键状态恢复正确。 |
| 0.3 | 0.2 | 通过 Unity MCP 建立 Windows x64 构建入口并发起构建，跟踪到完成。启动场景能进入一个空试验场。 | 从可执行文件启动并进入场景，用 Esc 释放鼠标并正常退出。 |
| 0.4 | 0.1 | Blender MCP 制作带尺寸参照和一个挂点的样件，保存源 blend 并导出 FBX，Unity MCP 导入后组装一个测试预制体。 | 在 Unity 回读尺寸、朝向、材质和挂点，截图留证。再次导出导入后，预制体组件与模型引用正常。 |

## 1 · 双视角驾驶试验场

| 编号 | 依赖 | 工作与文件产出 | 完成条件 |
| --- | --- | --- | --- |
| 1.1 | 0.2 | Mechs 下的移动与能源组件，Data/Mechs 下的轻、中、重配置，三套占位预制体。 | WASD、冲刺、跳跃可操作。轻型可短时升空，中型可短冲刺换位，重型可沿地面路线抵达目标。能源消耗与恢复可见。 |
| 1.2 | 1.1 | 共享相机控制、越肩挂点、简化驾驶舱挂点与 HUD。 | V 连续切换时保留朝向，右键在当前视角精瞄。移动、推进、精瞄均可在两种视角下使用。 |
| 1.3 | 1.2 | Combat 下的一种主武器、伤害接收和一个可受击目标。 | 枪口遮挡有反馈，两种视角瞄准同一目标时命中规则一致。打开再关闭界面后，重新按左键才开火。 |
| 1.4 | 1.3、0.3、0.4 | Unity MCP 组装 MechTestRange.unity，含掩体、地面坡道与高差路线。输出阶段构建与操控记录。 | 三套底盘均完成一段驾驶与射击。记录近墙、空中切视角、窗口切换和鼠标捕获的检查结果。 |

第一个工作包按 0.0 → 0.1 → 0.2 → 0.3 → 0.4 → 1.1 → 1.2 → 1.3 → 1.4 执行。它需要的资产为往返测试样件、占位机甲、基础掩体、目标靶和驾驶舱边框。

## 2 · 单战区搜打撤

| 编号 | 依赖 | 工作与文件产出 | 完成条件 |
| --- | --- | --- | --- |
| 2.1 | 1.4 | Loot 下的物品定义、搜索交互、随身货仓和货物选择界面。固定样本为一张蓝图、合金和电芯。 | 搜索后可选取物资。随身 4 格、材料每组 10 个作为首测值。超出格数或堆叠上限时明确显示余量。 |
| 2.2 | 2.1 | Save 下的版本化存档，Runs 下的出击状态，一次性入库逻辑和基础机库库存页。 | 同一次货舱或整机结算重试两遍，机库只增加一次。写入失败时保留原状态，玩家可重试。 |
| 2.3 | 2.2 | Extraction 下的货物回收舱，选择至多 2 格，原地按住 G 准备发射。 | 每次出击仅 1 舱。移动、松键或受击时可中断，舱与物资保留。成功升空时扣货、入库、标记舱已用一起保存。 |
| 2.4 | 2.2 | 本区撤离点、接应倒计时、运输机占位体和主动登机交互。 | 任意任务进度均可到点呼叫，等待期间能移动作战。运输机到达后再次按 E 登机才结算。 |
| 2.5 | 2.3、2.4 | WarzonePrototype.unity，含一项推进目标、搜索物、一个守卫和下一站出口。 | 完成目标开放出口。目标完成前可以搜物资、发射货舱或整机撤离。每次成功返航在基础机库库存页查看所得。 |
| 2.6 | 2.5 | Windows 单战区构建，结算逻辑测试与实机操作记录。 | 跑完下方「关键结算验证」。重开游戏后，机库物资、舱使用状态、机毁损失符合记录。 |

这一阶段的重点样例是「搜到蓝图 → 货舱送回 → 机甲被击毁 → 回机库看到蓝图，机上其余物资丢失」。

## 3 · 配装与分支出击

| 编号 | 依赖 | 工作与文件产出 | 完成条件 |
| --- | --- | --- | --- |
| 3.1 | 2.6 | Equipment 下的四槽装配、载重与额定功率检查，局内候选部件比较与替换。 | 替换推进器或防护模块，下一场立即体验到动作差异。装配超预算时能看见原因，三种底盘共用这套规则。 |
| 3.2 | 3.1 | Hangar.unity、蓝图解锁、材料消耗与初始配装方案。 | 蓝图和材料来自实际回收。解锁后可在下次出击初装，开始新出击时重置当局装备、强化与货舱次数。 |
| 3.3 | 3.2 | Runs 下的路线生成、节点情报、普通目标与中段终局分流。 | 地图公开任务与物资类别，具体战利品入场才发现。中段选首领或护送方向，任务完成后可继续搜再进下一站。 |
| 3.4 | 3.3 | 战区切换与当前出击存档，三个普通战区布局及轮换任务。 | 进入下一站保留机体状态、当局装备、随身物资和已用货舱标记。每站都能呼叫整机撤离。 |

## 4 · 完整试玩版

| 编号 | 依赖 | 工作与文件产出 | 完成条件 |
| --- | --- | --- | --- |
| 4.1 | 3.4 | BossArena.unity 的首领目标与 EscortRoute.unity 的护送工程机。 | 两条路线均能达成终局。分别记录任务达成与物资撤出，护送目标损毁时存活玩家可撤离。 |
| 4.2 | 4.1，美术制作可从 1.4 后开始 | 补齐三种主武器、两种副武装、两种推进器、两种防护与三类普通敌人。Blender MCP 制作和修整机体、工业组件，由 Unity MCP 导入组装，并接入免费音效。 | 三种机体风格可独立完成两种终局。资产尺度、挂点、材质、碰撞和来源记录齐全。 |
| 4.3 | 4.2 | 单局节奏、掉落价值、回收时机和敌群压力调整。 | 三类底盘各完成两种终局，记录至少六次完整通关的用时与回收收益。围绕 20–30 分钟目标调整，记录提前撤离的收益。 |
| 4.4 | 4.3 | Windows x64 试玩构建、性能采样与回归记录。 | 键鼠完成完整循环。指定测试机在 1080p、中等画质下采样，按项目规范核查 60 FPS 目标并记录实际结果。 |

按阶段记录实际工作量，再用已完成阶段校准后续排期。关键依赖为双视角操控、回收结算、跨战区状态、两种终局和完整出击调试。

## 数据归属与结算顺序

| 数据 | 谁持有 | 何时保存或变化 |
| --- | --- | --- |
| 底盘、部件、战区定义 | Data 下的配置资产 | 制作阶段调整，以内容编号关联。 |
| 永久解锁、机库材料和配装方案 | 玩家存档 | 解锁或成功回收时提交。 |
| 出击编号、随机种子、当前节点、机体状态、当局装备和货仓 | 当前出击 | 出击开始、进入战区、成功回收、返航或机毁时提交对应状态。 |
| 舱可用／准备中／已用 | 当前出击中的货舱记录 | 准备中锁住所选货物，成功发射后提交已用。加载一个发射前的完整快照时，从可重试状态恢复。 |
| 接应未呼叫／等待中／可登机 | 当前战区 | E 呼叫后进入等待。可登机时玩家主动交互返航。进入下一战区后，由该区自己的撤离点接应。 |
| 终局达成与物资返航 | 两类独立事件记录 | 首领或护送目标达成时记战果，登机时结算机上可回收物资。 |

货舱和整机结算都先校验物资、机体状态与事件编号，在新快照中计算扣货与入库。写入成功后采用新状态并显示完成。损坏的临时文件从上一份完整备份恢复，相关流程用针对性的存档测试覆盖。

## 关键结算验证

| 操作 | 预期结果 | 首次验收 |
| --- | --- | --- |
| 选择 3 张蓝图装入 2 格舱 | 可选择至多 2 张，第三张留在机甲上。 | 2.3 |
| 发射准备期间松键、移动或受击 | 原有物资仍在随身清单，货舱可再次使用。 | 2.3 |
| 发射成功后机甲被击毁 | 已回收货物在机库，机上货物丢失。 | 2.6 |
| 已用货舱后进入下一站，再打开货仓 | 舱保持已用，格位与机库物资正确。 | 3.4 |
| 运输机到达但玩家尚未登机 | 玩家仍可操作，随身货物仍由机甲携带。 | 2.4 |
| 已完成终局但尚未登机，随后机毁 | 终局战果保留，未送回的随身物资丢失。 | 4.1 |
| 同一事件回调重复、保存后重开游戏 | 同一份货物只结算一次。货舱回收后还可正常结算整机返航。 | 2.6 |
| 结算写入失败或临时快照损坏 | 可从有效状态恢复，背包、机库与结算标记相互一致。 | 2.6 |

结算去重、写入失败和货舱中断适合做小范围自动化测试。驾驶手感、切视角、两种终局和完整节奏在可执行构建中实际试玩。

## 美术与资产工作包

1. 在驾驶试验场确定机体基准尺寸、地面通路、武器挂点与驾驶舱视点，导出一份尺寸参照。
2. Blender MCP 先制作一台可驾驶的机体和共用驾驶舱边框，再围绕底盘参数制作轻、中、重外观。源文件进 SourceAssets/Blender，Unity MCP 用导出模型组装预制体。
3. 工业组件先覆盖地板、坡道、掩体、货箱、维修设施与撤离标识，组成三个可辨认的普通战区。
4. 音效先覆盖推进、开火反馈、受击、交互完成、货舱升空和运输机抵达。画面与声音共同提示状态。
5. 每份引入的免费模型、声音和代码在 [素材台账](AssetSources.md) 登记来源、版本、许可与实际路径。导入后在现有灰盒场景逐项替换并核对玩法挂点。

## 每阶段归档内容

构建产物放在 Builds/Windows/x64 对应阶段目录。记录包含构建编号、入口场景、使用的底盘与装备、复现操作、实际结果，以及需要跟进的问题，归档到 Docs/QA 对应阶段。截图进入该阶段 Screenshots，测试结果和 Console／构建日志进入 TestResults 与 Logs。Unity MCP 截图时指定这些输出位置，Blender 多角度预览与导出检查也使用相同阶段记录。首次性能记录同时填写测试机 CPU、GPU、内存、分辨率和画质。

0.0 的联通、0.4 的模型交接、1.4 的驾驶原型和 2.6 的核心回收结算已形成工程产出。后续按验收记录中的内容制作与实战测试项继续完成首版。