zeling_v2/Docs/Standards/GameDesignDocSpec.md

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

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

项	值
文档类型	规范（Standard）
版本	v1.0
更新日期	2026-07-21
状态	已定稿
适用范围	Docs/Game/ 下全部设计文档
关联文档	AssetFolderSpec · AddressablesLabelSpec · LayerSpec · 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 文档头

# {文档标题}

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

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

3.2 文末修订记录

## 修订记录

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

3.3 待补充标注

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

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

---

四、各类别文档分节结构

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

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，与 CLAUDE.md 第 4 条一致。

---

修订记录

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