# 项目协作约定

本文件适用于仓库及其子目录。默认用中文交流，按现有方案完成常规实现；涉及玩法方向、平台、存档格式等重大决策时向用户确认。用户已经授权的操作持续有效。

## 工程与工作入口

- 项目为 IRONSPORE：Windows PC 键鼠机甲搜打撤原型，含越肩和第一人称、配装、局内改装及中英双语。
- 使用 `ProjectSettings/ProjectVersion.txt` 指定的 Unity 版本，当前为 `6000.6.8f1`。依赖版本以 `Packages/manifest.json` 和锁定文件为准。
- 开始相关工作前按需阅读 [README](README.md)、[玩法设计](Docs/Design/GameDesign.md)、[实施计划](Docs/Production/ImplementationPlan.md) 和 [文件规范](Docs/Production/ProjectConventions.md)。沿用现有结构，避免无关重构。

## Unity 与 Blender

- 引擎操作使用 **Unity MCP**。场景、组件、预制体、导入设置和构建修改前，回读目标工程的完整路径、活动场景与编辑器状态；操作后检查保存结果及 Console。
- 多实例操作明确绑定准确的 `Name@hash`，逐次核对完整工程路径，不以项目名或路径前缀推断目标。不同目录分别维护缓存和 MCP 会话。
- C#、USS、JSON、工具脚本和文档可以通过文件工具修改。运行时代码修改后，通过 Unity MCP 刷新并等到编译与域重载结束，再测试或构建。现有桥接入口为 `Tools/Unity/McpClient.py`。
- 3D 建模、修整、导出使用 **Blender MCP**。先读当前文件、场景和对象；在任务自己的场景或集合中操作，保留已有未参与任务的内容。
- Blender 源文件保存在 `SourceAssets/Blender/`，导出模型进入 `Assets/Game/Art/Models/`。尺寸以米为单位，核对朝向、碰撞和武器/驾驶舱挂点。
- 不通过重建全部原型场景来完成局部修改；编辑器生成工具只在任务明确需要时运行。

## 文件、资源与数据

- 源码按功能放入 `Assets/Game/Scripts/`，配置放入 `Assets/Game/Data/`，场景放入 `Assets/Scenes/`，UI 和本地化沿用各自现有目录。
- Unity 资产与对应 `.meta` 一起维护，保留 GUID。已导入资产的移动或重命名通过 Unity MCP 完成并检查引用。
- 允许从公开网站下载免费的模型、声音、字体或代码。核实具体许可，保留原件、作者、版本/日期及 SHA-256，在 [素材台账](Docs/Production/AssetSources.md) 登记；许可原文放入 `Docs/Production/Licenses/`，发布包附必要署名。
- 下载原件放入 `SourceAssets/ThirdParty/<发行方>/<资源包>/`，Unity 导入物放入 `Assets/ThirdParty/` 对应目录；项目适配代码和派生资源使用项目自身目录。
- 翻译使用稳定文本键和完整句式参数，保留物品 ID、蓝图 ID、存档字段及回收事件编号。已有通知和结算也应随语言切换刷新。
- 存档、回收去重与写入失败处理属于核心行为；修改时保留现有版本兼容，并验证状态没有重复结算。

## 本地资源目录与版本控制

- `workTree/`、`worktrees/`、`.worktrees/` 和 `tree1/`、`tree2/`、`tree3/` 是本地工作区或资源副本目录，排除在主仓库提交及云端推送之外。不要使用强制添加将其纳入 Git。
- 已初始化的 tree 资源副本尚无独立分支或 worktree 注册。运行前核对目录内的 `WorkspaceInfo.json` 和实际路径；移动后的旧清单不能作为正确连接目标的依据。
- 并行运行前分别隔离测试存档与 PlayerPrefs，并为各目录完成 Unity 导入和 MCP 实例绑定。资源复制通过不等于编译、运行或性能验收通过。
- 分支、worktree 的创建和合并按用户明确要求执行。推送前检查暂存区、完整待推送路径及远程状态，使用正常推送，不擅自强制覆盖远程历史。
- 维护忽略规则：不提交 Library、Temp、Logs、Builds、UserSettings、IDE 缓存、生成的工程文件或凭据。已整理的 Docs/QA 验收摘要、测试结果及截图可以提交。
- 仓库地址通过 Git remote 管理。密码、令牌和带凭据的 URL 不写入本文件、源码、提交说明或可上传的日志。

## 验证与交付

- 根据实际修改选择必要检查。纯文档或 Git 配置变更检查链接、暂存范围与忽略规则；玩法、存档和本地化修改运行相关测试，修复失败后再继续。
- 当前自动化测试在 `Assets/Tests/EditMode/`，Unity MCP 测试命令在 `Tools/Unity/Commands/Tests.json`，结果通过对应 job 查询到完成。
- UI 变更核对实际分辨率、文本溢出、中文字符和鼠标/键盘交互。Windows 构建通过 MCP 发起并轮询到结束，启动完整产物目录验证实际行为。
- QA 记录放入 `Docs/QA/<阶段>/`，构建产物放入 `Builds/Windows/x64/`。明确区分静态检查、编辑器测试和独立程序实测，仅记录实际完成的验证。
- 60 FPS 与完整出击节奏为验收目标，不以未测量的推断代替结果。并行开发后的性能采样在单独运行的测试实例中进行。