416 lines
10 KiB
Markdown
416 lines
10 KiB
Markdown
# 玩法设计文档模板
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-02
|
||
|
||
|
||
本文档用于定义后续所有玩法设计文档的**统一写法**，保证玩法规则、全局规则块、配置落点和最小样例能够一起沉淀，为后续 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 配置文档建议通过专门后台管理，但要注意分工：
|
||
|
||
- 玩法文档：
|
||
负责定义规则、默认值、配置落点、最小样例
|
||
- 配置字典：
|
||
负责定义字段含义、可选项和默认值
|
||
- 后台方案：
|
||
负责对象、版本、校验、装配、发布
|
||
|
||
也就是说：
|
||
|
||
**玩法文档是“设计源头”，后台系统是“管理和发布工具”。**
|
||
|
||
不要让后台方案反过来决定玩法规则结构。
|
||
|
||
|
||
|