# gameFramework 与 Unreal Engine 解耦架构

2026-11-13。目标工程 `D:/vibeCoding/ueRouge/ueRouge.uproject`，UE 5.8.4，Windows PC 键鼠。用户已确定 C++ 核心与蓝图/UMG 表现，并要求核心独立于 UE，名称为 **gameFramework**。

gameFramework 是独立标准 C++ 规则库。UE 是调用该库的宿主之一，命令行程序和原生测试也能作为宿主。该库使用 CMake 构建，公共接口不出现 UE 类型；能够在未安装 UE 的环境中独立构建和测试，是解耦的验收条件。

状态：独立核心、UE 外部库链接、宿主、Actor 与 UMG 已实现。核心已通过 97 项原生行为检查及复制源码树的独立构建；UE 编译、Windows 打包与独立程序出击闭环已经验证。实际记录见[迁移验收](../QA/UE-Migration/README.md)，验证范围以其中列出的产物和截图为准。

端口、实例、工具能力与实际截图的核验见[本次检查记录](../QA/GameFrameworkMcpReadiness/2026-11-13-151241/README.md)。

## 依赖方向

```text
UE 输入 / Actor / UMG / 蓝图
            |
            v
        UEAdapter --------------------+
            |                        | 实现宿主接口
            v                        v
       gameFramework ------------> Ports
            ^                  （接口属于核心）
            |
    原生命令行宿主 / 原生测试
```

编译依赖只能指向核心和核心定义的接口。UEAdapter 将引擎输入转换为普通命令，将查询结果转换为事实，将核心快照和事件转换为展示。核心不会反向导入适配层，也不会主动调用全局 UE API。

## 职责划分

| 范围 | gameFramework | UEAdapter 与表现层 |
| --- | --- | --- |
| 装备与底盘 | 稳定 ID、四槽、载重/功率、数值定义、装备合法性 | DataAsset 装载与转换、模型、挂点、材质 |
| 库存与经济 | 10×24 仓库、4×4 货仓、2×2 安全箱/主动舱、旋转、堆叠、拆并、预占、制造、待整理、唯一归属 | 网格绘制、鼠标位置、DPI 换算、拖拽反馈；提交摆放命令 |
| 出击与结算 | 出击状态、回收去重、借用件、损失/保全、目标达成与返航分离、跨区状态、局内强化 | 关卡加载、Actor 生命周期、交互提示、撤离运输机表现 |
| 战斗与资源 | 弹药、装填、冷却、伤害、装甲、能源、推进消耗等数值规则 | 输入采集、碰撞/射线查询、CharacterMovement、镜头、动画、声音和特效 |
| AI 与任务 | 可复用决策条件、目标/任务状态、奖励和失败规则 | 导航、感知、世界对象查找及实际运动；向核心传递事实 |
| 存档 | V1 数据模型、校验、序列化契约、结算事务与恢复规则 | 平台路径和原子存储实现；测试宿主可使用内存或故障注入实现 |
| 文本与设置 | 语义错误码、必要的稳定文本键与参数、可复用设置值和策略 | FText、语言切换、控件、实际显示/音频设置、键位 API 和偏好存储 |

物理系统提供“某实体命中另一实体”等事实；核心决定伤害、资源消耗和状态变化。用纯数据的 MovementIntent/MovementResult 交换移动需求与实际结果，UE 的厘米与核心的米在适配层转换。

UI 与蓝图读取快照并提交命令，不直接更改权威库存、货币、出击状态或事件账本。Actor 上的展示字段是快照的投影，不是第二份业务状态。

## 公共接口和事务

公共接口使用标准 C++ 类型、明确的枚举和普通结构体。建议以 `Definitions`、`Command`、`Result`、`Snapshot`、`DomainEvent` 组织协议，接口中只出现稳定实体/物品 ID，不出现 UObject 指针、软资产路径或 World 引用。

核心定义以下宿主接口；接口和测试替身均不依赖 UE：

- `IProfileStorage`：读取快照和原子提交快照，返回可判断的成功/失败结果；负责磁盘替换的实现位于宿主侧。
- `IClock` 或显式时间输入：提供可测试时间，核心不读取 UE Tick、TimeSeconds 或真实墙钟。
- `IRandomSource`、`IIdGenerator`：提供种子和 ID，测试可重放；核心校验实例 ID 的唯一性。
- 必要的世界查询接口：输入输出普通几何数据和实体 ID；碰撞、命中和导航查询的实现留在宿主。

需持久化的库存和结算命令按以下顺序执行：

1. 根据当前状态创建候选状态，验证前置条件、预算、占格、唯一归属和回收事件键。
2. 请求宿主原子提交候选快照。
3. 提交成功后发布权威状态及对应领域事件；失败则保持原状态并返回稳定错误码。

准备草案不提前扣实物，确认出击才做一次持久化提交。普通模拟推进不逐帧写磁盘；自动保存与必须落盘的结算由明确策略区分。返回事件由宿主消费，核心提交期间不允许经回调重入并修改状态。

V1 编解码契约属于核心，不能把 `FJsonObject`、`FJsonObjectConverter` 或 `USaveGame` 放进核心公共接口。确有需要的 JSON 等独立依赖必须锁版并登记许可，不能通过间接依赖引入 UE。

## 目录和构建

```text
ueRouge/
  gameFramework/
    CMakeLists.txt
    include/irons/gameFramework/
    src/
    tests/
    schemas/
  Source/
    ueRouge/                   UE 工程入口和宿主生命周期
    GameFrameworkExternal/     UE 外部库链接规则
    UEAdapter/                 类型、输入、存储和世界适配
  Content/IRONSPORE/           蓝图、UMG、地图和展示数据
  Tools/Framework/             独立构建、测试和边界检查
  Tools/Unreal/                MCP、引擎验证和打包工具
  Builds/gameFramework/        生成的库和测试产物，Git 忽略
```

`gameFramework` 是目录和 CMake 目标名。公共头使用 `irons/gameFramework/` 前缀，避免与 UE 自带的 `GameFramework/` 头文件目录混淆，尤其是 Windows 文件名大小写不敏感的环境。

核心不包含 `.Build.cs`、`.uplugin`、`.uproject` 和 UHT 生成文件。建议标准为 C++20，运行时依赖优先使用标准库；UE 外部库包装放在 `Source/GameFrameworkExternal/`。UE 支持通过 `ModuleType.External` 声明外部库及其头文件/链接设置，见 [Epic 外部库集成说明](https://dev.epicgames.com/documentation/en-us/unreal-engine/integrating-third-party-libraries-into-unreal-engine?application_version=5.8)。

先独立构建静态库，再由 UE 桥接链接该产物；桥接缺少匹配库时明确失败，不偷偷回到 UBT 编译核心源码。两侧必须核对编译器、架构、标准、MSVC 运行库、迭代器调试设置和配置，避免 ABI 不匹配。异常不得穿越宿主边界。

本机 CMake 不在 PATH，但 VS 2022 附带 CMake 3.31.6 可用。构建工具应能发现或显式接收该路径，不把本机绝对工具路径写死在核心 CMake 文件中。

## 解耦验收

| 检查 | 通过条件 |
| --- | --- |
| 依赖边界 | 扫描核心源文件、公共头和传递依赖，无 UE 头文件、模块、反射宏、容器及引擎构建依赖；不能只检查目录名。 |
| 独立构建 | 在没有 UE 安装路径、UE 环境变量和编辑器的独立环境中，CMake 配置和编译通过。 |
| 原生测试 | 原生可执行程序通过 CTest 运行库存、装备、出击、回收、坏档、写入失败和去重测试。CTest 用法见 [CMake 官方说明](https://cmake.org/cmake/help/book/mastering-cmake/chapter/Testing%20With%20CMake%20and%20CTest.html)。 |
| 原生闭环 | 不启动 UE，通过测试宿主执行准备、出击、拾取、主动回收、机毁或返航，并核对 V1 快照。 |
| 宿主一致性 | 相同定义、种子、ID 与命令/事实序列，在原生宿主与 UE 桥接中产生一致的业务结果；浮点几何按明确精度比较。 |
| UE 端到端 | UE 编译、桥接生命周期、PIE、Windows 打包和独立程序分别验证；语言/显示变化只影响表现，不改变核心库存和结算。 |

源码和构建边界检查、独立编译及原生测试必须同时成立，不能用“关闭编辑器但仍使用 UBT/UE 头文件编译”作为引擎独立的证明。

## 实施顺序

先建立核心构建与测试入口，然后迁移库存和存档规则，再实现 UEAdapter，最后接回角色、场景及 UI。原有 64 项测试和 94 项 UI 检查作为行为基线重新映射；引擎独立规则在原生层验证，物理、输入、布局与宿主集成在 UE 中验证，不重复维护两份规则。

当前实现还将十五秒接应、主动回收三秒蓄力及中断、试验场计时和爆炸伤害衰减放在核心。UE 输入时间、落地/静止/命中事实和几何距离；界面中的倒计时字段仅为核心快照的投影。计时与临时场景状态不加入进度 JSON，V1 版本不变。

独立验证复制了仅含 `gameFramework/` 的源码树，清除引擎环境变量，仅用 CMake、MSVC 和 CTest 构建。编译依赖轨迹未出现 UE 头文件；本机仍装有 UE，因此不声称已在另一台卸载 UE 的机器验收。UE 的模块链接生成的静态库，核心目录中不存在 UHT/UBT 构建文件。