# 游戏设计文档编写规范（GameDesignDocSpec）

> 本规范定义《择灵》所有**游戏设计文档**（`Docs/Game/` 下）的组织方式、目录结构、单文档分节结构、命名与交叉引用约定，以及文案禁忌。
> 新建或修改任何设计文档前，必须先对照本规范。与 `AssetFolderSpec.md`（资产目录）、`AddressablesLabelSpec.md`、`LayerSpec.md` 并列，同属项目长期规范。

| 项 | 值 |
|------|------|
| 文档类型 | 规范（Standard） |
| 版本 | v1.0 |
| 更新日期 | 2026-07-21 |
| 状态 | 已定稿 |
| 适用范围 | `Docs/Game/` 下全部设计文档 |
| 关联文档 | [AssetFolderSpec](AssetFolderSpec.md) · [AddressablesLabelSpec](AddressablesLabelSpec.md) · [LayerSpec](LayerSpec.md) · [CLAUDE.md](../../CLAUDE.md) 第 4 条 |

---

## 一、总原则

1. **一实体一文档，综合成篇。** 每个独立设计对象（一个 Boss、一类小怪、主角、一个 NPC、一个系统）用**一份综合文档**表达，内部按固定分节区分「设计向」「程序向」「美术向」内容，避免同一对象拆成多份文档导致相互漂移。
2. **分节固定、按需留空。** 每类文档的分节顺序与标题固定（见第四章）；某节暂无内容时**保留标题并显式标注 `> ⏳ 待补充`**，不得删除分节，也不得用兜底内容填充。
3. **可读性优先。** 面向人阅读：概述在前、细节在后；能用表格表达的结构化信息一律用表格；状态机、拓扑等用代码块 ASCII 图。
4. **单一事实源。** 同一信息只在一处定义，其他文档通过**交叉引用**指向它（见第六章），不复制粘贴。
5. **文案禁忌。** 设计文档与代码同受约束：**不得出现其他游戏的专有名称或"对齐/仿/参考 XX 游戏"字样**（见第七章）。

---

## 二、目录结构

`Docs/Game/` 按类别分子目录，每个实体独立文件：

```
Docs/Game/
├── README.md              # 导航索引：全部文档一览 + 建议阅读顺序
├── _Templates/            # 各类别空白模板（新建文档时复制）
│   ├── 模板_总览.md
│   ├── 模板_主角.md
│   ├── 模板_小怪.md
│   ├── 模板_Boss.md
│   ├── 模板_NPC.md
│   └── 模板_系统.md
├── 00_总览/
│   └── 游戏总览.md         # 游戏概述 / 核心玩法 / 系统索引 / 能力解锁节点 / 主线拓扑
├── 主角/
│   └── 主角能力设定.md
├── 敌人/
│   ├── 敌人总览.md         # 分类体系 + 编号规则 + 通用开发规范
│   ├── 小怪/
│   │   └── E0NN_名称.md
│   └── Boss/
│       ├── Boss总览.md     # 全体 Boss 总表
│       └── 名称.md
├── NPC/
│   ├── NPC总览.md
│   └── 名称.md
├── 系统/
│   └── 系统名.md           # 收集系统 / 魂蝶收集 / …
└── 剧情/
    └── 世界观与剧情.md
```

- 类别子目录可随项目扩展新增（如后续加 `关卡区域/`、`数值/`）；新增类别须在本规范第四章补对应分节模板，并在 `README.md` 登记。
- 目录名用中文类别词；`00_总览` 用数字前缀确保排在最前。

---

## 三、通用文档结构（所有文档共有）

每份设计文档必须包含**文档头元数据表**（正文第一个 `#` 标题之后）与**文末修订记录表**。

### 3.1 文档头

```markdown
# {文档标题}

| 项 | 值 |
|------|------|
| 文档类型 | 总览 / 主角 / 小怪 / Boss / NPC / 系统 / 剧情 |
| 版本 | v1.0 |
| 更新日期 | YYYY-MM-DD |
| 状态 | 草稿 / 进行中 / 已定稿 |
| 负责模块 | 对应的程序/资产模块（如 `BaseGames.Enemies.AI`、`ENM_` 资产等），无则填 — |
| 关联文档 | [相对链接](...) · … |
```

- **状态**取值：`草稿`（仅骨架）、`进行中`（部分成稿，仍有待补充节）、`已定稿`（本版本内容完整）。
- **更新日期**用绝对日期 `YYYY-MM-DD`，不写"今天/上周"等相对表述。

### 3.2 文末修订记录

```markdown
## 修订记录

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| 1.0 | YYYY-MM-DD | 初始版本 | — |
```

### 3.3 待补充标注

任一分节暂无内容时保留标题，正文写：

```markdown
> ⏳ **待补充**：（说明缺什么、需谁提供，如"技能数值待策划填写"）
```

---

## 四、各类别文档分节结构

以下为**必备分节**及顺序。分节标题统一用二级标题 `##`。可在必备分节内按需加三级标题。

### 4.1 总览（游戏总览）

1. `游戏概述` — 名称/类型/主题/平台等基础信息表
2. `核心玩法机制` — 战斗资源循环、核心系统一览
3. `系统索引` — 指向各系统/主角/敌人/剧情文档的交叉引用表
4. `能力解锁节点` — 能力 × 获取时机表
5. `主线流程拓扑` — 拓扑图（图片或 ASCII）
6. `待补充` — 全局级 TODO（模块/项/优先级）
7. `修订记录`

### 4.2 主角

1. `概述` — 定位、形态体系一句话说明
2. `输入定义` — Input Action 表（名称/类型/说明）
3. `基础能力` — 能力总表（能力/输入/触发条件/描述），复杂能力在下方展开细则
4. `能力细则` — 逐能力细节（跳跃/冲刺/攻击/位移等，各用三级标题 + 机制表）
5. `后天获取能力` — 能力/获取时机/描述
6. `资源系统` — 各独立资源（来源/用途/机制）
7. `形态与技能` — 每形态一节，技能表（能力/输入/触发条件/描述）
8. `修订记录`

### 4.3 小怪 / 精英 / 小 Boss

1. `概述` — 编号/类别/行动方式/核心机制/形象设定表
2. `状态机` — ASCII 状态机图 + **状态列表表**（AI 状态标识符 / 动画 Clip 名 / 类型 / 说明）
3. `AI 行为` — 感知与决策逻辑（代码块伪流程）
4. `技能规格` — 每技能：触发条件/伤害类型/攻击范围/备注（或逐技能三级标题详表）
5. `动画需求` — 动作清单表（动作类别 / 命名 / 动画类型 / 描述 / 帧数 / 图片参考）
6. `数值参数表` — 参数名 / 说明 / 参考值（策划待填）
7. `技术备注` — 实现注意事项
8. `修订记录`

> 状态列表必须分列「AI 状态标识符」与「动画 Clip 名」两列——二者可能不同名（如 AI 状态 `Idle_Disguise` 对应 Clip `Idle`），以本表为实现依据。

### 4.4 Boss

1. `概述` — 名号/排行/大地图/Boss 区域/外貌/掌管能力（对应主角能力）/一句话定位
2. `战斗设计` — 阶段数、阶段切换条件、整体节奏、机制亮点、玩家应对思路（面向策划的体验描述）
3. `阶段系统` — 每阶段可用技能与行为、进入/结束条件
4. `状态机与 AI` — ASCII 状态机总览 + 状态列表表（分战斗前/各阶段/击败流程）+ 各阶段 AI 决策逻辑
5. `技能规格` — 逐技能三级标题详表（类型/弹道/范围/伤害判定/关键参数）
6. `特殊机制` — 阶段切换、击落、分身识别等专属机制（代码块伪流程）
7. `动画需求` — 动作清单表（同小怪）
8. `数值参数表` — 参数名 / 说明 / 默认值（待确认）
9. `技术备注` — 位移分离、弹道生成、事件驱动等实现约定
10. `修订记录`

### 4.5 NPC

1. `概述` — 身份/所在地点/出现或交互前置条件/一句话定位
2. `功能` — 对话 / 商店 / 升级 / 收集兑换等，逐功能说明与关联系统
3. `交互流程` — 交互条件、状态变化（如"获得某被动后才可对话"）
4. `对话要点` — 关键剧情/引导台词纲要（非逐字脚本）
5. `关联系统与奖励` — 指向系统文档的交叉引用、奖励表
6. `动画/表现需求` — 如有立绘/动作需求（可留待补充）
7. `修订记录`

### 4.6 系统

1. `概述` — 系统定位、一句话说明
2. `机制细则` — 逐子机制的规则与数据（表格为主）
3. `数据表` — 物品/条目清单（编号/名称/效果）
4. `关联系统` — 与其他系统的关系（可用 ASCII 关系图）
5. `设计要点` — 设计意图、平衡考量
6. `修订记录`

---

## 五、命名与编号

| 对象 | 文档文件名 | 内部编号字段 | 说明 |
|------|-----------|-------------|------|
| 小怪/精英/小Boss | `E0NN_中文名.md` | `E0NN_拼音`（如 `E001_CaoZhi`） | 编号沿用需求表；与 `ENM_` 资产前缀对应 |
| Boss | `中文名.md`（双 Boss 用 `名与名.md`） | 概述表「排行」字段 | Boss 顺序在 `Boss总览.md` 统一给出 |
| NPC | `中文名.md` | — | — |
| 系统 | `系统名.md` | 条目自带编号 | — |

- 文档内引用**主角能力、资产**时，与 `AssetFolderSpec.md` 的前缀体系保持一致（`ABL_` 能力、`ENM_` 敌人、`WPN_`/`SKL_` 等），必要时给出资产前缀以便程序对应。
- 编号一经分配不复用、不回填空缺（删除的编号作废，不给新对象顶替）。

---

## 六、交叉引用

- 文档之间一律用 **Markdown 相对路径链接**，不裸写文档名。
  - ✅ `详见 [主角能力设定](../主角/主角能力设定.md#资源系统)`
  - ❌ `详见《主角能力设定》`
- 引用文档内某节时链接到锚点（`#分节标题`）。
- 单一事实源：数值、名词定义、能力效果只在其**主属文档**定义，其余文档引用。例如仙酿数值只在 `系统/收集系统.md` 定义，NPC/总览文档引用它。

---

## 七、文案禁忌（禁止参考游戏字样）

设计文档正文、表格、图注中**均不得出现**：

- 其他游戏的专有名称（含中英文缩写）
- 其他游戏的专属机制/道具名称
- "对齐 / 仿 / 参考 / 类比 XX 游戏""XX 风格""XX 同款"等指名措辞

**正确做法：只描述该机制的功能特点。** 对照示例：

| ❌ 禁止 | ✅ 替换为 |
|------|------|
| 机制完全对齐《某游戏》 | 提前松开截断上升速度，实现可变跳跃高度 |
| 类似《某游戏》的酒葫芦 | 探索与战斗中积累、消耗一次使用回复生命的续命资源 |
| 类似《某游戏》高尼兹召唤旋风 | 单手举高挥动，于玩家当前位置召唤一道细长龙卷 |

允许保留的业界通用术语：`Pogo`、`Charm`、`platformer` / 横版平台游戏、`Metroidvania`、`手感`、`风格`。

> 完整规则见 [.github/skills/no-game-references/SKILL.md](../../.github/skills/no-game-references/SKILL.md)，与 [CLAUDE.md](../../CLAUDE.md) 第 4 条一致。

---

## 修订记录

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| 1.0 | 2026-07-21 | 初始版本：目录结构、通用文档结构、六类分节模板、命名编号、交叉引用、文案禁忌 | — |