37 lines
4.8 KiB
Markdown
37 lines
4.8 KiB
Markdown
# 项目协作约定
|
||
|
||
本文件适用于 `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 和 UE 的边界
|
||
|
||
- 核心部分名称固定为 **`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/`，不放入独立核心。锁定编译器和运行库兼容条件，异常不得穿越宿主边界。
|
||
- 开始实现前阅读 [架构方案](Docs/Design/GameFrameworkArchitecture.md) 和 [迁移计划](Docs/Production/UnrealMigrationPlan.md)。
|
||
|
||
## 存档和资源
|
||
|
||
- 当前进度存档固定为 **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 目录及凭据。创建分支、提交或推送按用户明确要求执行。
|