zhangyan/cmr-mini

Fork 0

Files

zhangyan 6964e26ec9 同步前后端联调与文档更新

2026-04-02 09:25:05 +08:00

10 KiB

Raw Permalink Blame History

玩法设计文档模板

文档版本：v1.0 最后更新：2026-04-02 08:28:05

本文档用于定义后续所有玩法设计文档的统一写法，保证玩法规则、全局规则块、配置落点和最小样例能够一起沉淀，为后续 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 Permalink Blame History Unescape Escape