69 lines
5.8 KiB
Markdown
69 lines
5.8 KiB
Markdown
# 项目开发规范（强制遵守）
|
||
|
||
> 以下规范在**所有**开发活动中强制生效，不限于单次会话。创建、命名、放置任何脚本 / ScriptableObject / 预制体 / 场景 / 场景物体 / 目录前，必须先对照规范。
|
||
|
||
## 1. 命名与目录规范
|
||
|
||
创建/命名任何资产、脚本、预制体、场景、目录时，**必须遵守** `Docs/Standards/` 下的规范：
|
||
|
||
- **`Docs/Standards/AssetFolderSpec.md`** — 目录结构与命名（`_Game/` 父目录、各类资产的前缀与路径，如 `EVT_`/`PLY_`/`ENM_`/`WPN_`/`SKL_`/`CHM_`/`MAP_`/`UI_`/`SET_`/`ICN_` 等；场景命名 `Persistent.unity`/`MainMenu.unity`/`Room_{Region}_{NN}.unity`/`Boss_{Name}.unity`）
|
||
- **`Docs/Standards/AddressablesLabelSpec.md`** — Addressable 地址（`AddressKeys.cs` 常量，禁止硬编码字符串）与标签规范
|
||
- **`Docs/Standards/LayerSpec.md`** — 物理层 / 排序层（Sorting Layer）规范
|
||
|
||
## 2. 必须用 Editor 脚手架创建（不裸建）
|
||
|
||
创建场景物体 / UI / 预制体 / SO 资产时，**优先用 `Assets/_Game/Scripts/Editor` 下的脚手架**（编辑器扩展），由工具保证路径、命名、Addressables 注册、组件引用绑定符合规范。**不要**用裸 `new GameObject` / `AddComponent` / 手动 `CreateAsset` 直接搭建。
|
||
|
||
主要脚手架（菜单 / 静态方法均可经 MCP 调用）：
|
||
- 场景结构：`SceneScaffoldTools.ScaffoldPersistentScene/ScaffoldMainMenuScene/ScaffoldGameRoom`
|
||
- UI：`HUDScaffoldWizard.ScaffoldHUDCanvas`、`InventoryHubScaffoldWizard.ScaffoldInventoryHub`
|
||
- 场景物体：`SceneObjectPlacerTool.Place*`（Player/SavePoint/Enemy/CameraArea 等，自动绑事件频道与碰撞层）
|
||
- 预制体：`WeaponHitBoxWizard`、`SkillHitBoxWizard`
|
||
- SO 资产：`CreateEventChannelAssets.CreateAll`、`ProjectAssetSetup.CreateAll`、`CharacterWizardWindow`、`DataHubWindow`
|
||
- Addressables：`CoreSceneRegistrar.RegisterCoreScenes`、`AddressableManagerWindow`、`AddressKeyValidator`
|
||
|
||
若某类资产**没有**对应脚手架，应**先补脚手架**（参考现有脚手架的 `AssignReference`/`AssignAsset` 绑定模式），再用它创建——使后续创建都走规范路径。
|
||
|
||
## 3. 创建后自检
|
||
|
||
完成创建后，运行项目验证工具确认合规：
|
||
- `BaseGames/Tools/Validation/Validate All ScriptableObjects`（SOValidationRunner）
|
||
- `BaseGames/Addressables/Validate Address Keys`（AddressKeyValidator）
|
||
- `BaseGames/Tools/Maintenance/Physics2D Layer Matrix/Check`（LayerSpec 校验）
|
||
|
||
## 4. 代码命名与注释：禁止引用其他游戏
|
||
|
||
编写或修改任何 C# 代码时，**命名（变量名/方法名/类名）、注释（`//`、`///`）、`[Tooltip]`、`[Header]` 字段标签** 中均不得出现其他游戏的专有名称、专属机制/道具名称，或"对齐/仿/参考/类比 XX 游戏"等措辞。完整规则、对照表与允许保留的通用术语见 **`.github/skills/no-game-references/SKILL.md`**。
|
||
|
||
- ❌ 禁止：`// 对齐空洞骑士手感`、`[Tooltip("HK ~0.12s")]`、`ApplyHKComposerDefaults(...)`
|
||
- ✅ 替换为只描述功能特点：`// 下落比上升更快，手感紧实`、`[Tooltip("推荐 0.12s")]`、`ApplyComposerDefaults(...)`
|
||
- 允许保留的通用业界术语：`Pogo`、`Charm`、`platformer`/横版平台游戏、`Metroidvania`、`手感`/`风格`。
|
||
|
||
## 5. 及时 Git 提交
|
||
|
||
完成一个可独立工作的改动后（功能、修复、重构、文档等），应**及时 git 提交**，不要积压大量未提交改动：
|
||
|
||
- 每完成一个逻辑单元就提交一次，保持提交粒度小、可回溯。
|
||
- 提交信息遵循现有风格（中文 + 类型前缀，如 `feat(ui):` / `refactor:` / `docs:` / `fix:`）。
|
||
- 提交示例：`git add ... && git commit -m "..."`。
|
||
|
||
## 6. 根因修复，禁止下游兜底掩盖问题
|
||
|
||
修复任何问题时，**必须定位并修复根因，使功能在正常路径上如预期正确运行**；**禁止**用兜底 / 回退 / 容错分支在下游把症状盖住、让问题表面上"不再出现"。
|
||
|
||
- ❌ 禁止：在消费端加 fallback 自动补一个默认值/默认对象来掩盖上游漏配（例：探测器发现交互物没有提示子节点，就运行时自动实例化一个默认提示——这掩盖了"创建链路没产出正确对象"的真问题）。
|
||
- ❌ 禁止：用 `try/catch` 吞异常、`?? 默认值`、`if(null) return` 等手段让错误静默通过，而不修产生该错误的源头。
|
||
- ✅ 正确：让**创建链路（脚手架）本身产出完整正确的对象**；已存在的错误数据，直接**修正为正确状态**（如把误置的物理层改回规范层、补齐漏绑的引用），而不是在运行时绕过。
|
||
- ✅ 正确：源头无法即时修复时，应**显式报错 / 校验失败**（写入自检工具、抛出明确异常），把问题暴露出来，而非隐藏。
|
||
- 判据：问"如果去掉这段代码，问题会不会暴露出来？"——若答案是"会，且暴露的是真问题"，那这段就是在掩盖问题，应删除并改修根因。
|
||
- 兜底/默认值仅允许用于**合法的业务缺省**（如可选配置留空有明确语义），不得用于**遮盖本应正确配置却没配好**的情况。
|
||
|
||
## 7. 文档分区：开发文档与长期文档
|
||
|
||
开发过程中产生的文档，按用途分放两处：
|
||
|
||
- **`Docs_Dev/`** — 开发过程中的临时性 / 阶段性文档：实现计划、开发笔记、验证清单、评估报告、调试记录、一次性任务的 spec 等（会随开发推进而过时的文档）。
|
||
- **`Docs/`** — 项目长期文档：指导手册（`Docs/Guides/`）、架构设计、命名/目录/规范（`Docs/Standards/`）等需要长期维护、对项目持续有效的文档。
|
||
|
||
判据：问"这份文档在对应功能开发完成后是否还需要长期查阅？"——需要长期查阅（手册、架构、规范）放 `Docs/`；只服务于当前开发阶段的放 `Docs_Dev/`。
|