# 玩法设计文档模板

本文档用于定义后续所有玩法设计文档的**统一写法**，保证玩法规则、全局规则块、配置落点和最小样例能够一起沉淀，为后续 JSON 配置管理和后台装配提供稳定输入。

目标：

- 统一玩法设计文档结构
- 避免只写“玩法创意”，不写“配置落点”
- 让后续玩法都能自然接到配置文件和后台管理方案

说明：

- 本文档是模板，不是具体玩法规则
- 后期 JSON 配置管理以专门后台方案承接
- 本文档负责沉淀“设计输入”
- 后台方案负责沉淀“编辑、版本、发布、装配”

建议配合阅读：

- [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md)
- [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
- [后台配置管理方案V2](D:/dev/cmr-mini/doc/config/后台配置管理方案V2.md)

---

## 1. 使用方式

后续每新增一个玩法，都建议新建一份玩法文档，并按本模板完整填写。

推荐存放方式：

- `doc/games/<游戏名称>/游戏说明文档.md`
- `doc/games/<游戏名称>/规则说明文档.md`
- `doc/games/<游戏名称>/最小配置模板.md`
- `doc/games/<游戏名称>/最大配置模板.md`
- `doc/games/<游戏名称>/全局配置项.md`
- `doc/games/<游戏名称>/游戏配置项.md`

如果玩法还处于发散阶段，可以先写“构想方案”；  
一旦进入可开发阶段，就应该补齐本模板里的正式章节。

---

## 2. 标准章节清单

后续每个玩法设计文档，建议至少包含以下章节：

1. 文档定位
2. 一句话规则
3. 设计目标
4. 适用范围
5. 局流程
6. 核心对象模型
7. 判定与状态机
8. 计分与胜负规则
9. 全局规则块选型
10. 配置落点
11. 最小可跑配置样例
12. 验收清单
13. 后续扩展点

---

## 3. 模板正文

以下为推荐模板正文，可直接复制新建玩法文档后填写。

---

# `玩法名称`

## 1. 文档定位

本文档用于定义 `玩法模式标识` 的正式规则、默认行为、配置落点和最小可跑样例。

当前阶段目标：

- 说明玩法怎么玩
- 说明系统如何判定
- 说明配置文件如何承载
- 说明哪些沿用系统默认，哪些需要玩法覆盖

---

## 2. 一句话规则

请用一句话写清：

- 玩家要做什么
- 怎样推进
- 怎样结束
- 怎样赢 / 怎样结算

示例：

> 玩家需要按顺序完成控制点打卡，允许跳点；普通点打卡后回答限时数学题获取奖励分，打完终点后结算成绩。

---

## 3. 设计目标

建议至少说明：

- 这个玩法的核心乐趣是什么
- 它和已有玩法的主要差异是什么
- 它优先验证哪种系统能力

建议回答：

- 是否偏竞技
- 是否偏探索
- 是否偏轻量复玩
- 是否偏实时压力

---

## 4. 适用范围

建议至少说明：

- 适用于单人还是多人
- 是否依赖真实 GPS
- 是否依赖模拟器
- 是否依赖心率等遥测能力
- 是否依赖路线型场地还是对象集型场地

建议落成明确语句：

- 支持：`单人 / 多人`
- 输入依赖：`GPS / 心率 / 模拟输入`
- 场地类型：`course / control-set / region-set / object-set`

---

## 5. 局流程

建议按时间顺序写完整流程：

### 5.1 进入游戏

- 初始看到什么
- 哪些对象显示，哪些隐藏
- 是否立即开始计时
- 是否先弹提示

### 5.2 正式开始

- 什么事件触发正式开局
- 是否初始化数据
- 是否显示全图 / 全路线
- 是否弹开始提示

### 5.3 进行中推进

- 玩家如何推进
- 当前目标如何变化
- 是否允许跳点 / 切目标 / 自由选点
- 进行中有哪些关键反馈

### 5.4 结束

- 什么条件触发结束
- 是否立即停止计时
- 是否弹结束提示
- 是否进入结算页

---

## 6. 核心对象模型

建议列清玩法运行依赖的对象类型。

示例格式：

| 对象类型 | 作用 | 是否必需 | 备注 |
| --- | --- | --- | --- |
| `start` | 起始触发点 | 是 | 用于正式开赛 |
| `control` | 普通推进目标 | 是 | 可按玩法扩展属性 |
| `finish` | 结束点 | 视玩法而定 | 用于结束比赛 |
| `bonus` | 奖励对象 | 否 | 可选 |
| `danger-zone` | 危险区域 | 否 | 可选 |

还建议说明：

- 对象来源于 `KML` 还是运行时生成
- 对象是静态的还是动态变化的
- 对象是否有状态切换

---

## 7. 判定与状态机

### 7.1 局状态

建议明确列出局状态，例如：

1. `ready`
2. `running`
3. `paused`
4. `finished`
5. `settled`

### 7.2 关键判定

建议逐条写清：

- 打点成功判定
- 跳点判定
- 得分判定
- 失败判定
- 完赛判定

### 7.3 状态切换条件

建议写成表：

| 当前状态 | 触发事件 | 下一状态 | 备注 |
| --- | --- | --- | --- |
| `ready` | 起点打卡成功 | `running` | 正式开始计时 |
| `running` | 结束条件满足且终点打卡 | `finished` | 停止计时 |
| `finished` | 关闭结束提示 | `settled` | 进入结算页 |

---

## 8. 计分与胜负规则

建议明确：

- 基础分怎么来
- 奖励分怎么来
- 扣分怎么来
- 跳过点如何处理
- 最终成绩显示哪些指标

推荐格式：

| 规则项 | 说明 | 默认值 | 备注 |
| --- | --- | --- | --- |
| 基础分 | 成功打点获得 | `1` | 示例 |
| 奖励分 | 答题答对获得 | `1` | 示例 |
| 跳过点得分 | 是否得分 | `0` | 示例 |
| 结算指标 | 总用时 / 总分 / 成功点数 | - | 示例 |

如果玩法没有积分，也要写清：

- 胜负依据是什么
- 排名依据是什么
- 是否只有完赛状态

---

## 9. 全局规则块选型

本节必须回答“这个玩法用了哪些全局能力块，以及默认选型是什么”。

建议按下表填写：

| 规则块 | 是否使用 | 选型 / 配置方向 | 默认值策略 | 备注 |
| --- | --- | --- | --- | --- |
| 地图底座 | 是 | 自定义地图 + KML | 沿用系统默认 |  |
| 点位表现 | 是 | 传统定向紫红系 | 可局部覆盖 |  |
| 腿线表现 | 是 | `classic-leg` + 动效 | 顺序类沿用默认 |  |
| 轨迹表现 | 是 | `full` / `tail` / `none` | 玩法指定 |  |
| 定位点表现 | 是 | `beacon` / `dot` 等 | 沿用系统默认或玩法覆盖 |  |
| 引导显示 | 是 | 是否显示腿线、是否允许选点 | 玩法指定 |  |
| 可见性策略 | 是 | 开局隐藏 / 起点后全显 | 玩法指定 |  |
| 内容体验 | 否 / 是 | 原生 / H5 / 不启用 | 玩法指定 |  |
| 反馈系统 | 是 | 音效 / 震动 / UI 档位 | 玩法指定 |  |
| 遥测参数 | 否 / 是 | 是否用心率 | 沿用默认或玩法覆盖 |  |
| 调试能力 | 是 | 是否开放模拟器 | 开发期指定 |  |

本节的目的不是重复字段字典，而是明确：

- 这个玩法到底用了哪些公共块
- 哪些沿用默认
- 哪些要做玩法覆盖

---

## 10. 配置落点

本节用于把规则翻译成配置结构。

建议写成表：

| 设计项 | 配置落点 | 是否已有字段 | 默认值 | 是否建议后台表单化 |
| --- | --- | --- | --- | --- |
| 起点后显示全路线 | `game.visibility.revealFullPlayfieldAfterStartPunch` | 是 | `true` | 是 |
| 跳点开关 | `game.sequence.skip.enabled` | 是 | `true` | 是 |
| 答题倒计时 | `待补字段` | 否 | `10` | 先走 JSON 区 |
| 目标点样式 | `game.presentation.sequential.controls.current` | 是 | 玩法指定 | 可后续表单化 |

这里建议把字段分成两类：

### 10.1 稳定字段

适合后续做后台正式表单：

- 模式
- 半径
- 是否必须起点 / 终点
- 是否显示腿线
- 是否显示轨迹
- 是否允许跳点
- 是否启用内容体验

### 10.2 易变字段

更适合先放 JSON 编辑区：

- 实验性计分细则
- 特殊答题规则
- 视觉实验参数
- 单点特殊表现
- 复杂状态映射

本节要和后续后台管理方案衔接，避免字段落点混乱。

---

## 11. 最小可跑配置样例

本节建议给出一个最小可跑 JSON 样例。

要求：

- 只保留当前玩法最关键字段
- 能作为联调和测试入口
- 和规则说明保持一致

建议结构：

```json
{
  "schemaVersion": "1",
  "version": "2026.03.31",
  "app": {},
  "map": {},
  "playfield": {},
  "game": {},
  "resources": {},
  "debug": {}
}
```

如果已有运行中的 `event/*.json`，应在本节明确引用对应样例。

---

## 12. 验收清单

建议至少覆盖：

| 验收项 | 是否通过 | 备注 |
| --- | --- | --- |
| 开局流程与文档一致 |  |  |
| 打点判定与文档一致 |  |  |
| 计分规则与文档一致 |  |  |
| 点位表现与文档一致 |  |  |
| 轨迹与定位点表现一致 |  |  |
| 结算页指标与文档一致 |  |  |
| 样例配置可跑通 |  |  |
| 文档与配置字段口径一致 |  |  |

---

## 13. 后续扩展点

本节建议专门写：

- 哪些能力当前先不做
- 哪些字段未来可能配置化
- 哪些地方后续会交给后台表单化管理

示例：

- 第一阶段先固定答题倒计时为 `10` 秒，后续再配置化
- 第一阶段先固定基础分 / 奖励分，后续再补 `game.scoring` 细项
- 第一阶段样式先走 profile，后续再细化到按状态表单配置

---

## 14. 文档产出要求

后续新增一个正式玩法文档时，建议至少同步产出以下内容：

1. 一份玩法规则文档
2. 一份对应最小样例配置
3. 如有新增公共能力，更新 [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md)
4. 如有新增字段，更新 [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)

---

## 15. 和后台方案的关系

后期 JSON 配置文档建议通过专门后台管理，但要注意分工：

- 玩法文档：
  负责定义规则、默认值、配置落点、最小样例
- 配置字典：
  负责定义字段含义、可选项和默认值
- 后台方案：
  负责对象、版本、校验、装配、发布

也就是说：

**玩法文档是“设计源头”，后台系统是“管理和发布工具”。**

不要让后台方案反过来决定玩法规则结构。