12 KiB
游戏规则架构
文档版本：v1.0 最后更新：2026-04-02 18:33:00
本文档用于说明当前项目中“游戏规则”在文档、配置文件、样例 JSON、解析代码和运行时规则引擎之间的实际组织方式。
目标：
- 说明规则设计从哪里开始
- 说明公共配置和玩法配置如何分层
- 说明样例配置、代码解析、运行时规则如何对应
- 作为后续后台配置管理的架构基线
1. 总体原则
当前项目采用的是“文档定义规则，配置承载规则，代码解析配置，规则引擎执行配置”的结构。
可以概括为四句话：
- 玩法规则先在文档里定义
- 规则通过 JSON 配置文件表达
- 客户端解析配置生成运行态定义
- 规则引擎按运行态定义驱动游戏流程
也就是说：
文档是设计源头，配置是规则载体，代码是执行层。
如果换一种更偏运行时的说法：
MapEngine和页面壳子是骨架- 默认值层和规则层决定骨架怎么动
- 配置像神经系统，把活动差异传进运行时
- 遥测和反馈层负责把玩家状态再回流到界面
2. 当前分层结构
当前规则体系分成 6 层。
2.1 公共规则层
位置：
作用：
- 定义系统共用能力有哪些
- 定义公共字段、可选项和默认值
- 作为所有玩法的公共配置全集
这一层回答的是：
- 系统支持哪些规则块
- 系统有哪些字段
- 这些字段默认怎么工作
2.2 玩法设计层
位置：
- 程序默认规则基线
- 运行时编译层总表
- 多赛道 Variant 五层设计草案
- 多赛道 Variant 前后端最小契约
- 玩法设计文档模板
- 玩法构想方案
doc/games/<游戏名称>/规则说明文档.mddoc/games/<游戏名称>/游戏说明文档.md
作用：
- 定义客户端自身应该内建的默认行为
- 定义某个玩法怎么玩
- 定义局流程、状态机、计分、胜负、表现
- 明确该玩法选用了哪些公共规则块
这一层回答的是：
- 这个玩法的目标是什么
- 这个玩法如何开始、推进、结束
- 这个玩法和系统公共能力的关系是什么
2.3 玩法配置层
位置：
doc/games/<游戏名称>/最小配置模板.mddoc/games/<游戏名称>/最大配置模板.mddoc/games/<游戏名称>/全局配置项.mddoc/games/<游戏名称>/游戏配置项.mdevent/*.json
作用：
- 把玩法规则翻译为可执行配置
- 明确这个玩法实际使用的公共字段子集
- 给出最小可跑样例和较完整样例
这一层回答的是：
- 规则具体落到哪些字段
- 哪些字段是系统默认
- 哪些字段由玩法覆盖
- 当前联调跑的是哪份样例配置
2.4 配置解析层
位置：
作用：
- 读取远端或本地 JSON
- 补齐模式默认值
- 归一化为运行时使用的定义对象
这一层回答的是：
- 配置进入程序后如何被解释
- 系统默认值何时注入
- 不同玩法模式如何做差异化默认处理
2.5 运行时默认与设置层
位置：
作用：
- 统一维护玩法默认值
- 统一维护设置页默认值
- 明确哪些值持久化，哪些锁态不持久化
- 为页面层和规则层提供同一套默认基线
补充约束：
- 设置值允许玩家修改并持久化
- 设置锁态只由系统默认值和活动配置决定
- 锁态不持久化，也不允许玩家在页面里切换
- 锁态只在当前游戏配置运行生命周期内生效；本局结束或主动退出后失效
2.6 运行时编译层
位置：
作用：
- 统一合并系统默认值、玩法默认值、活动配置和玩家设置
- 产出页面、引擎和规则层可直接消费的运行时 profile
- 逐步替代页面和引擎中分散的默认值判断
当前进度：
settings / telemetry / feedback已开始走编译层入口- 设置页大部分引擎型设置项已改成统一更新玩家设置，再由编译层回灌引擎
settings当前已通过MapEngine.applyCompiledSettingsProfile(...)统一落地，不再由页面层散着逐项推送presentation和一部分game字段也已开始接入map也已开始接入地图底座和配置状态这组基础字段MapEngine.applyRemoteMapConfig(...)已开始退回为原始场地与资源入口
这一层回答的是：
- 程序默认值放在哪里
- 玩家本地设置如何和系统默认值合并
- 锁态为什么不能从历史缓存恢复
- 为什么页面、引擎、规则不应再直接各自读原始配置
2.7 故障恢复层
位置：
作用：
- 在对局进行中低频持久化轻量恢复快照
- 在异常退出后提供“继续上一局 / 放弃上一局”入口
- 只恢复核心运行态，不恢复瞬时 UI
这一层回答的是：
- 非正常退出后如何继续比赛
- 为什么恢复只保留核心赛局状态
- 为什么不尝试恢复白卡、答题卡和动效中间态
2.8 运行时规则层
位置：
- classicSequentialRule.ts
- scoreORule.ts
- mapEngine.ts
- map.ts
- resultSummary.ts
- telemetryRuntime.ts
- playerTelemetryProfile.ts
作用：
- 根据运行态定义执行状态流转
- 响应 GPS、点击、打点、答题、结束等事件
- 产出 HUD、反馈、结果页等最终体验
- 明确区分可打目标、引导目标、HUD 目标和展示高亮目标
这一层回答的是：
- 玩家在游戏中的每一步如何被判定
- 积分、答题、结束如何结算
- 页面上显示什么、什么时候显示
- 活动遥测默认值和玩家身体数据如何合并
3. 规则从设计到运行的链路
当前实际链路如下：
- 在玩法文档里定义默认规则
- 在公共配置文档里定义字段与默认值
- 在玩法目录里确定该玩法使用哪些字段
- 在
event/*.json中写出样例配置 - 由配置解析层读取 JSON 并注入模式默认值
- 由默认值与设置层补齐系统默认行为和玩家本地值
- 由规则引擎和
MapEngine执行游戏逻辑 - 由结果页和 HUD 层展示最终状态
其中遥测相关链路补充为：
系统默认值 -> 活动 telemetry 配置 -> 玩家线上身体数据 -> TelemetryRuntime -> HUD 第 2 页
设置相关链路补充为：
系统设置默认值 -> 玩家本地持久化值 -> 当前运行时锁态 -> map.ts / MapEngine
也可以简化成：
规则文档 -> 配置文档 -> 样例 JSON -> 配置解析 -> 规则引擎 -> 运行结果
当前已补一层轻量 smoke tests，用于卡住高风险回归：
- 配置继承
- 起点 / 终点规则
- 积分赛自由打点
- 锁态生命周期
- 超时结束
命令：
npm run test:runtime-smoke
4. 当前目录分工
4.1 doc/config
职责：
- 公共配置全集
- 公共字段字典
- 公共模板
- 发布和后台管理方案
这一层不应该存放某个玩法自己的专属规则文档。
4.2 doc/gameplay
职责：
- 通用玩法方法论
- 玩法设计模板
- 玩法构想和规则架构说明
这一层不应该长期存放具体玩法的正式规则文档。
4.3 doc/games/<游戏名称>
职责：
- 某个具体玩法的完整文档集合
- 玩法说明
- 规则说明
- 最小 / 最大模板
- 全局配置项子集
- 游戏配置项子集
这一层是具体玩法的唯一正式维护入口。
4.4 event/*.json
职责：
- 当前可运行样例配置
- 联调、验证、远端发布的直接输入
这一层必须和玩法目录中的文档保持一致。
5. 当前已落地的玩法实例
5.1 顺序打点
正式文档入口：
5.2 积分赛
正式文档入口：
6. 文档与代码同步约定
后续每次规则变化，建议至少检查 4 层是否同步：
- 公共配置文档是否要补字段或默认值
- 对应玩法目录下的规则文档是否要改
- 对应
event/*.json样例是否要改 - 配置解析和规则引擎是否要改
如果只改了其中一层，就容易出现文档、配置、代码不一致。
建议统一按下面顺序维护：
- 先改规则文档
- 再改配置文档和样例 JSON
- 再改解析代码和规则代码
- 最后回头核对结果页、HUD 和提示是否与文档一致
7. 和后续后台管理的关系
当前本地项目里，规则主要由文档和样例 JSON 驱动。
后续接后台后，分工仍然建议保持不变：
- 玩法文档负责定义规则
- 公共配置文档负责定义字段
- 后台负责编辑、版本、校验、装配、发布
- 客户端继续消费静态 JSON
也就是说，后台是管理工具，不是规则源头。
8. 一句话总结
当前这套实际架构可以概括为：
doc/config 管公共规则全集，doc/games/<游戏名称> 管玩法规则与配置子集，event/*.json 管可运行样例，客户端解析配置后交给规则引擎执行，并由轻量恢复层处理异常退出后的续局。