zhangyan/cmr-mini

Fork 0

Files

zhangyan 3ef841ecc7 feat: 收敛玩法运行时配置并加入故障恢复

2026-04-01 13:04:26 +08:00

10 KiB

Raw Blame History

玩法设计文档模板

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

目标：

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

说明：

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

建议配合阅读：

1. 使用方式

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

推荐存放方式：

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

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

2. 标准章节清单

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

文档定位
一句话规则
设计目标
适用范围
局流程
核心对象模型
判定与状态机
计分与胜负规则
全局规则块选型
配置落点
最小可跑配置样例
验收清单
后续扩展点

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 局状态

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

ready
running
paused
finished
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 样例。

要求：

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

建议结构：

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

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

12. 验收清单

建议至少覆盖：

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

13. 后续扩展点

本节建议专门写：

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

示例：

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

14. 文档产出要求

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

一份玩法规则文档
一份对应最小样例配置
如有新增公共能力，更新全局规则与配置维度清单
如有新增字段，更新配置选项字典

15. 和后台方案的关系

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

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

也就是说：

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

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

10 KiB Raw Blame History Unescape Escape