cmr-mini/config-template-score-o.md

积分赛配置文档（基础版）

本文档用于给服务端和后台配置设计提供一份可直接落地的积分赛基础模板。
目标是先把积分赛入口结构定稳，后续程序功能再逐步细化。

---

1. 适用玩法

适用于最基础的积分赛玩法：

• 手动开始
• 先打开始点
• 多个检查点自由收集
• 控制点有固定分值
• 可选终点
• 支持选中目标点后打卡

---

2. 顶层结构

推荐主配置结构如下：

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

---

3. 完整示例

{
  "schemaVersion": "1",
  "version": "2026.03.25",
  "app": {
    "id": "lxcb-001",
    "title": "雪熊领秀城区积分赛",
    "locale": "zh-CN"
  },
  "map": {
    "tiles": "lxcb-001/tiles/",
    "mapmeta": "lxcb-001/tiles/meta.json",
    "declination": 6.91,
    "initialView": {
      "zoom": 17
    }
  },
  "playfield": {
    "kind": "control-set",
    "source": {
      "type": "kml",
      "url": "lxcb-001/course/c01.kml"
    },
    "CPRadius": 6,
    "controlOverrides": {
      "control-1": {
        "score": 10
      },
      "control-2": {
        "score": 20
      },
      "control-3": {
        "score": 30
      },
      "control-4": {
        "score": 40
      }
    },
    "metadata": {
      "title": "校园积分赛控制点集",
      "code": "score-o-c01"
    }
  },
  "game": {
    "mode": "score-o",
    "rulesVersion": "1",
    "session": {
      "startManually": true,
      "requiresStartPunch": true,
      "requiresFinishPunch": false,
      "autoFinishOnLastControl": false,
      "maxDurationSec": 5400
    },
    "punch": {
      "policy": "enter-confirm",
      "radiusMeters": 10,
      "requiresFocusSelection": true
    },
    "scoring": {
      "type": "score",
      "defaultControlScore": 10
    },
    "guidance": {
      "showLegs": false,
      "legAnimation": false,
      "allowFocusSelection": true
    },
    "visibility": {
      "revealFullPlayfieldAfterStartPunch": true
    },
    "finish": {
      "finishControlAlwaysSelectable": true
    },
    "telemetry": {
      "heartRate": {
        "age": 30,
        "restingHeartRateBpm": 62,
        "userWeightKg": 65
      }
    },
    "feedback": {
      "audioProfile": "default",
      "hapticsProfile": "default",
      "uiEffectsProfile": "default"
    }
  },
  "resources": {
    "audioProfile": "default",
    "contentProfile": "default",
    "themeProfile": "default-race"
  },
  "debug": {
    "allowModeSwitch": false,
    "allowMockInput": false,
    "allowSimulator": false
  }
}

---

4. 字段说明

app

• id 活动或配置实例 id
• title 活动标题
• locale 语言环境

map

• tiles 瓦片根路径
• mapmeta 地图 meta 地址
• declination 磁偏角
• initialView.zoom 初始缩放级别

playfield

• kind 当前推荐 control-set
• source.type 当前推荐 kml
• source.url KML 地址
• CPRadius 检查点绘制半径
• controlOverrides 每个控制点的积分和后续扩展元数据

playfield.controlOverrides

当前阶段最推荐至少放：

• score

示例：

"control-1": {
  "score": 10
}

这样可以保证：

• KML 只提供点位与空间结构
• 分值由配置控制

game.session

• startManually 是否手动开始
• requiresStartPunch 是否必须先打开始点
• requiresFinishPunch 是否必须打终点
• autoFinishOnLastControl 积分赛通常为 false
• maxDurationSec 最大时长

game.punch

• policy 当前推荐 enter-confirm
• radiusMeters 打点半径
• requiresFocusSelection 是否必须先选中目标点后才能打卡

game.scoring

• type 当前推荐 score
• defaultControlScore 如果某个点没单独配置分数时的默认值

game.guidance

• showLegs 积分赛基础版建议 false
• legAnimation 积分赛基础版建议 false
• allowFocusSelection 建议 true

game.visibility

• revealFullPlayfieldAfterStartPunch 开始点打卡后是否显示完整控制点集合

game.finish

• finishControlAlwaysSelectable 积分赛建议支持随时选终点结束时，设为 true

game.telemetry

通用体能参数。

game.feedback

反馈 profile 绑定。

resources

资源 profile 绑定。

debug

调试相关开关。

---

5. 当前阶段推荐必填字段

积分赛当前阶段建议至少保证以下字段存在：

• map.tiles
• map.mapmeta
• map.declination
• playfield.kind
• playfield.source.type
• playfield.source.url
• playfield.CPRadius
• game.mode
• game.punch.policy
• game.punch.radiusMeters
• game.punch.requiresFocusSelection
• game.scoring.type

---

6. 当前阶段建议默认值

如果服务端还没有全部细项，建议先采用以下默认值：

{
  "game": {
    "session": {
      "startManually": true,
      "requiresStartPunch": true,
      "requiresFinishPunch": false,
      "autoFinishOnLastControl": false
    },
    "punch": {
      "policy": "enter-confirm",
      "radiusMeters": 10,
      "requiresFocusSelection": true
    },
    "scoring": {
      "type": "score",
      "defaultControlScore": 10
    },
    "guidance": {
      "showLegs": false,
      "legAnimation": false,
      "allowFocusSelection": true
    },
    "finish": {
      "finishControlAlwaysSelectable": true
    }
  }
}

---

7. 积分赛当前阶段推荐的设计边界

当前阶段建议坚持以下边界：

• KML 提供点位和几何底稿
• 配置提供分值和玩法解释
• 不把积分逻辑写进 KML
• 不把自由收集逻辑写成固定路线逻辑

也就是说：

• playfield.kind = control-set
• controlOverrides.score 负责分值
• game.guidance.allowFocusSelection = true 负责选中目标逻辑

---

8. 适合当前客户端的迁移原则

当前客户端迁移时，建议服务端先完成：

1. 将积分赛点位分值迁入 playfield.controlOverrides
2. 将玩法规则迁入 game.session / game.punch / game.scoring / game.guidance / game.finish
3. 不急着一次性接入动态积分和复杂规则

先把静态积分赛入口结构定稳，再逐步扩展动态积分和高级玩法能力。

---

9. 一句话结论

积分赛配置当前阶段建议：

• 用 playfield.kind = control-set
• 用 KML 承载控制点空间底稿
• 用 playfield.controlOverrides 承载点位分值
• 用 game.scoring / game.punch / game.guidance / game.finish 承载玩法规则
• 先把静态积分赛入口结构定稳，后续再扩动态积分与更复杂玩法