项目协作约定

本文件适用于 D:/vibeCoding/ueRouge 及其子目录。默认使用中文交流。项目是 Windows PC 键鼠机甲搜打撤游戏 IRONSPORE；按已确定的玩法迁移，重大玩法、平台及存档版本决策由用户确认。

工程和工具

使用 ueRouge.uproject 绑定的 UE 版本，当前为 5.8.4。用户已明确授权不保留 UE 项目模板；建立 Content/IRONSPORE/ 的替代入口后，通过引擎工具按依赖清单移除模板资产，不删除无关用户内容或引擎内置资源。
引擎操作优先使用 UE MCP，当前地址为 http://127.0.0.1:8000/mcp。每次操作前确认监听进程对应本工程完整 .uproject 路径，并回读引擎版本、活动关卡和 PIE 状态。
并行任务使用独立 MCP 客户端会话，固定绑定各自实例；同一编辑器的修改操作串行执行。不接管其他任务的实例，不停止仍在使用的共享服务。
C++、CMake、配置、工具和文档可以通过文件工具维护。资产导入、移动、重命名和引用修改通过引擎工具进行，不直接拼写或修改二进制 .uasset、.umap。
Blender 建模与导出继续使用 Blender MCP，先读取当前场景并保留无关内容。按米制源文件和实际包围盒校验 UE 厘米制导入结果，不盲目叠加 Unity 导入缩放。

核心部分名称固定为 gameFramework，是项目根目录下独立的标准 C++ 库，使用 CMake 构建；必须能在没有 UE、UHT、UBT 和编辑器的环境下构建并运行测试。
gameFramework 的公共头文件和实现不得依赖 UE 头文件、UE 模块、UObject、UCLASS、USTRUCT、UPROPERTY、FString、FVector、TArray、TMap、*.generated.h、蓝图或资产路径。核心构建不得依赖 .uproject、.Build.cs 或 UE 安装路径。
核心负责装备与库存规则、准备草案、预算、制造、出击和回收状态、伤害与资源数值、V1 数据模型及校验。UE 适配层负责 Actor、物理查询、输入、镜头、UMG、渲染、声音和平台服务。
UE 通过普通 C++ 数据、命令、快照、结果及领域事件与核心交互；引擎类型转换和 DataAsset 映射放在适配层。UMG 和蓝图不复制库存、扣费、损失或结算规则。
文件写入、时钟、随机数、ID 生成和必要的世界查询由宿主实现核心定义的接口。核心不读取 UE 全局状态，不持有 Actor 或控件指针。
UE 的外部库链接规则与桥接模块放在 Source/，不放入独立核心。锁定编译器和运行库兼容条件，异常不得穿越宿主边界。
开始实现前阅读架构方案和迁移计划。

当前进度存档固定为 V1。除非用户明确要求，不改变版本；版本不变时无需增加旧结构兼容或迁移层。UE 存档和测试数据使用独立目录，不自动读取或覆盖 Unity 玩家数据。
保留稳定物品 ID、UID、蓝图 ID、回收事件键及唯一归属。需要持久化的结算先通过存储提交成功，再发布入库或消耗结果；保留原子写入、备份、损坏档保护、去重和失败回滚。
自制源文件进入 SourceAssets/，UE 资产进入 Content/IRONSPORE/。公开免费素材必须核实具体许可、保留原件和 SHA-256，登记作者与来源，发布包附所需署名。
不复制 Unity 缓存、Unity 引擎专用资产、原工作区副本或含凭据的文档；仓库地址通过 Git remote 管理，密码和令牌不写入源码、文档、提交说明或可上传日志。

按修改范围验证。核心逻辑先运行独立 CMake/CTest 测试，再验证 UE 桥接；UE 编译、PIE、打包和独立程序实测分别记录。Unity 的测试通过不能代替 UE 测试通过。
子阶段完成必要编译、自动测试和短时功能检查；长时间帧率、压力和整局性能采样集中在集成阶段进行。
每次调试结束退出本任务启动的 PIE，保存修改和验收资料，关闭本任务独占的 MCP 连接及临时进程；核对资源归属，不影响其他任务。编辑器是否退出按用户要求执行。
QA 记录与实际截图放入 Docs/QA/，截图注明关卡、实际分辨率和编辑器或独立程序环境，交付报告直接展示关键截图并链接记录。纯文档和架构阶段说明验证范围，不把规划当成运行验收。
版本控制包含核心、UE 源码、配置、Content、必要插件源码、工具、文档和整理后的验收资料；排除 Binaries/、Intermediate/、Saved/、DerivedDataCache/、Builds/、IDE 缓存、worktree 目录及凭据。创建分支、提交或推送按用户明确要求执行。