# IRONSPORE 的 Unreal Engine 迁移计划

2026-11-13。来源 `D:/vibeCoding/unityRouge`，功能基线提交 `463d898`；目标 `D:/vibeCoding/ueRouge/ueRouge.uproject`，UE 5.8.4，Windows PC 键鼠。

实施路线已确定为独立 **gameFramework 标准 C++ 核心 + UEAdapter + 蓝图/UMG 表现**。核心的定义、接口、构建与验收遵循[解耦架构](../Design/GameFrameworkArchitecture.md)，不能将核心直接做成依赖 UE 的 C++ 模块。

当前状态：首个 UE 可玩迁移版本已实现，模板资产及清单内残留通过引擎工具移除。独立核心、UE 外部库桥接、源资源、仓库/存档、驾驶战斗和搜打撤闭环已接入，Windows Development 包已生成并运行。验收证据和实际范围见[迁移验收](../QA/UE-Migration/README.md)。完整路线的长时驾驶、平衡和持续性能仍按集成测试安排执行，不以短时采样代替。

检查证据与已记录的日志/会话关闭提示见[MCP 检查记录](../QA/GameFrameworkMcpReadiness/2026-11-13-151241/README.md)。

## 阶段和验收

| 阶段 | 交付 | 通过条件 |
| --- | --- | --- |
| M0a 工具和独立核心骨架 | 固定工程绑定的 MCP 检查；gameFramework 的 CMake、头文件、测试入口和依赖检查 | 独立环境不需要 UE 即可编译和运行 CTest；MCP 校验准确工程、版本、关卡与 PIE 状态 |
| M0b UE 桥接与最小打包 | UE C++ 模块、外部库包装、UEAdapter、最小地图与可启动产物 | 链接独立核心库，桥接生命周期和最小 Windows 构建通过；运行时不依赖 MCP |
| M1 源资源与定义 | 两份 Blender/FBX 资产、9 件装备、三底盘、SVG、字体和中英文表；只将普通业务数据传入核心 | 核对单位、朝向、挂点、碰撞、材质与中文；稳定业务 ID 不变 |
| M2 核心规则 | 网格、装备、草案、研究制造、待整理、V1 存档与结算事务 | 原生宿主验证唯一归属、原子写入、坏档/失败保护、预占与回收去重 |
| M3 驾驶与战斗 | UE 角色、双视角、输入、物理查询与表现；核心维护弹药、能源、伤害等数值 | 切视角不改变瞄准和结算规则，菜单交接不会误射击；单位转换一致 |
| M4 搜打撤闭环 | 搜索、主动货舱及中断、安全箱、接应、主动登机、机毁和重载 | 原生宿主与 UE 都完成业务闭环，Windows 程序实际返库和重启核对；此阶段形成首个可玩里程碑 |
| M5 完整 UI | 工业主页、三栏机库、剪影/图标、拖放、HUD、设置、中英语言按钮 | UE UI 只发命令和读快照；四种分辨率、双语、鼠标与键盘实测 |
| M6 内容对齐 | 全部装备行为、三种机体风格、局内改装、路线、首领/护送、试验场和场景效果 | 对照 Unity 已实现功能，明确并修复差异 |
| M7 集成 | 原生测试、UE 自动测试、Windows 实测、截图和集成性能检查 | 单独记录实际通过项；在集成阶段依据测量判断 1080p/60 FPS 与整局节奏 |

## 工具操作边界

UE MCP 使用 `http://127.0.0.1:8000/mcp`。任务使用自己的客户端会话，操作前后核对监听进程及完整 `.uproject` 参数，禁止仅凭端口、项目名或窗口标题判断目标。当前可发现模型/纹理导入、蓝图、UMG、数据资产、保存、PIE、自动测试和截图等接口；能力发现不等于对应写操作或打包已实测。

源码、CMake、配置和工具通过文件操作维护。资源操作通过引擎 API；源码构建和打包使用独立 CMake 与 UE 官方构建工具，并记录实际工具链及产物。MCP 的受限 Python 编排环境用于调用工具，不作为运行时玩法脚本环境。

执行阶段已通过 MCP 导入源模型和派生图标/声音，创建独立地图、材质、蓝图及 UMG 子类，运行 PIE 和 UE 自动测试。调试结束保存本任务资料并关闭独占客户端连接及临时程序；是否保留编辑器以最终状态记录为准，不停止其他任务正在使用的服务。

## 资源和存档

- Blender 源与 SVG 保留为可编辑源文件；FBX 不叠加 Unity `globalScale=100`，在 UE 中按实际包围盒校验。SVG 首版可派生透明纹理供 UMG 使用。
- 字体从归档 TTF 及 OFL 许可重新导入，Unity 字体图集不迁移。现有声音主要为代码合成，应重建或离线导出后导入。
- `.unity`、Unity 材质、C# 和 USS 按行为重新实现；不将 Unity 专用序列化资产直接复制为 UE 内容。
- V1 的业务模型、稳定 ID、回收事件键和事务规则归 gameFramework；宿主负责实际存储路径与原子写入实现。UE 使用独立存档目录，不自动读取或覆盖 Unity 玩家进度，不新增旧版迁移层。
- 新增素材核实许可并归档原件、作者和 SHA-256。来源工程的敏感记录、缓存和工作区副本不复制；目标 Git 初始化、分支、提交和推送另按用户明确要求执行。

## 首轮实施重点

M0–M6 的核心、宿主与原型功能已有实现：97 项原生检查包含两条五区路线、首领结算重试、护送装甲、回收计时及失败回滚；UE 宿主覆盖真实原子存档。独立 Windows 程序验证了实际出击、一次主动回收、等待接应后主动登机、再次出击机毁与安全箱保全，并进行了双语、多分辨率及真实键鼠检查。首领/护送的完整手工驾驶节奏、长时间压力与性能采样仍属于后续集中集成验收范围。