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

2026-04-01 13:04:26 +08:00
parent 1635a11780
commit 3ef841ecc7
73 changed files with 8820 additions and 2122 deletions
--- a/doc/games/积分赛/最小配置模板.md
+++ b/doc/games/积分赛/最小配置模板.md
@@ -0,0 +1,246 @@
+# 积分赛最小配置模板
+
+本文档提供一份 **积分赛（`score-o`）最小可跑配置模板**。
+
+目标：
+
+- 只保留积分赛跑通所需的最少字段
+- 让测试尽量回到程序默认规则本身
+- 避免历史内容卡、H5 页面、样式覆盖继续干扰联调
+
+如果你关心“最小模板下系统到底默认怎么跑”，请优先配合阅读：
+
+- [积分赛规则说明文档](D:/dev/cmr-mini/doc/games/积分赛/规则说明文档.md)
+- [程序默认规则基线](D:/dev/cmr-mini/doc/gameplay/程序默认规则基线.md)
+
+---
+
+## 1. 最小模板
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.31",
+  "app": {
+    "id": "sample-score-o-001",
+    "title": "积分赛示例",
+    "locale": "zh-CN"
+  },
+  "map": {
+    "tiles": "../map/lxcb-001/tiles/",
+    "mapmeta": "../map/lxcb-001/tiles/meta.json",
+    "declination": 6.91,
+    "initialView": {
+      "zoom": 17
+    }
+  },
+  "playfield": {
+    "kind": "control-set",
+    "source": {
+      "type": "kml",
+      "url": "../kml/lxcb-001/10/c01.kml"
+    }
+  },
+  "game": {
+    "mode": "score-o"
+  }
+}
+```
+
+---
+
+## 2. 字段说明
+
+### `schemaVersion`
+
+- 类型：`string`
+- 必填：是
+- 说明：配置结构版本
+- 当前建议值：`"1"`
+
+### `version`
+
+- 类型：`string`
+- 必填：是
+- 说明：配置版本号
+
+### `app.id`
+
+- 类型：`string`
+- 必填：是
+- 说明：活动配置实例 ID
+
+### `app.title`
+
+- 类型：`string`
+- 必填：是
+- 说明：活动标题 / 比赛名称
+
+### `app.locale`
+
+- 类型：`string`
+- 必填：否
+- 说明：语言区域
+
+### `map.tiles`
+
+- 类型：`string`
+- 必填：是
+- 说明：地图瓦片根路径
+
+### `map.mapmeta`
+
+- 类型：`string`
+- 必填：是
+- 说明：地图 meta 文件路径
+
+### `map.declination`
+
+- 类型：`number`
+- 必填：否
+- 说明：磁偏角，未填写时按程序默认值处理
+
+### `map.initialView.zoom`
+
+- 类型：`number`
+- 必填：否
+- 说明：初始缩放级别，未填写时按程序默认视口逻辑处理
+
+### `playfield.kind`
+
+- 类型：`string`
+- 必填：是
+- 说明：空间对象类型
+- 积分赛固定使用：`control-set`
+
+### `playfield.source.type`
+
+- 类型：`string`
+- 必填：是
+- 说明：空间底稿来源类型
+- 当前推荐值：`kml`
+
+### `playfield.source.url`
+
+- 类型：`string`
+- 必填：是
+- 说明：KML 文件路径
+
+### `playfield.CPRadius`
+
+- 类型：`number`
+- 必填：否
+- 说明：点位触发半径，未填写时按程序默认值处理
+
+### `playfield.controlDefaults.score`
+
+- 类型：`number`
+- 必填：否
+- 说明：普通积分点统一默认分值
+- 备注：适合整场大多数积分点共用一个分值
+
+### `playfield.controlOverrides.*.score`
+
+- 类型：`number`
+- 必填：否
+- 说明：积分点分值
+- 备注：如果写了 `playfield.controlDefaults.score`，单点这里会覆盖默认值
+
+### `playfield.metadata.title`
+
+- 类型：`string`
+- 必填：否
+- 说明：路线名称
+
+### `playfield.metadata.code`
+
+- 类型：`string`
+- 必填：否
+- 说明：路线编码
+
+### `game.mode`
+
+- 类型：`string`
+- 必填：是
+- 说明：玩法模式
+- 积分赛固定值：`score-o`
+
+### `game.*`
+
+- 类型：`object`
+- 必填：否
+- 说明：最小样例默认不依赖额外玩法覆盖字段
+- 备注：如需覆盖程序默认值，再补 `punch`、`scoring`、`guidance`、`finish` 等子块
+
+---
+
+## 3. 当前默认逻辑
+
+如果你只写本页最小模板，积分赛会按程序默认规则运行。
+
+### 3.1 默认局流程
+
+- 进入游戏后默认只显示开始点
+- 系统默认提示玩家：需要先打开始点才正式开始比赛
+- 未打开始点前，积分点和结束点不生效
+- 首次成功打开始点后：
+  - 正式开始比赛
+  - 初始化本局数据
+  - 开始计时
+  - 显示全部积分点和结束点
+  - 默认只给出“比赛开始”短反馈，并同步更新引导提示和 HUD
+  - 最小模板下默认不弹开始白色内容卡
+- 比赛进行中默认允许自由点击任意未收集积分点，将其设为当前目标点
+- 当前目标点选定后，底部 HUD 信息面板默认显示该点距离等信息
+- 最小模板下，点击积分点默认不弹详情卡
+- 默认不要求先选中目标点
+- 任意未收集积分点进入打点半径后都可成功打点
+- 成功打点后默认：
+  - 先得该点标注分值的基础分
+  - 默认不弹题
+  - 如需答题卡，需显式配置对应点位的 `quiz` CTA
+- 开始点和结束点默认不弹题，只弹提示信息
+- 默认至少完成 `1` 个普通积分点后，结束点才解锁
+- 结束点解锁后不需要先选为目标点
+- 成功打结束点后：
+  - 停止计时
+  - 给出完成短反馈
+  - 直接进入默认成绩结算页
+  - 默认不再额外叠加终点白色内容卡
+- 白色内容卡默认改为显式配置启用；只有某个点位明确配置 `autoPopup = true` 时，完成该点后才会先弹白卡
+
+### 3.2 默认规则参数
+
+- `map.declination`
+  - 没配时默认按 `0`
+- `map.initialView.zoom`
+  - 没配时由客户端初始视口逻辑接管
+- `playfield.CPRadius`
+  - 没配时按客户端内置值处理
+- `playfield.controlDefaults.*`
+  - 没配时按程序默认值处理
+- `playfield.controlOverrides.*.score`
+  - 没配时按程序默认统一分值处理
+- `game.session.*`
+  - 默认非手动开始
+  - 默认要求起点打卡
+  - 默认不要求终点打卡才能算“完赛资格”
+  - 默认不在最后一个积分点自动结束
+- `game.punch.requiresFocusSelection`
+  - 默认按 `true` 处理
+- `game.guidance.allowFocusSelection`
+  - 默认按积分赛逻辑允许选点
+- `game.finish.finishControlAlwaysSelectable`
+  - 默认按积分赛逻辑处理终点可选
+- `game.visibility.revealFullPlayfieldAfterStartPunch`
+  - 默认按 `true` 处理
+
+---
+
+## 4. 当前样例说明
+
+当前仓库中的 [score-o.json](D:/dev/cmr-mini/event/score-o.json) 已按这套最小测试口径收敛，除积分点分值外，不再附带历史测试内容卡、H5 页面和样式覆盖。
+
+如果要查看公共完整字段，请继续参考：
+
+- [当前最全配置模板](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)