mini-prog/doc/config-template-classic-sequential.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": "course",
    "source": {
      "type": "kml",
      "url": "lxcb-001/course/c01.kml"
    },
    "CPRadius": 6,
    "metadata": {
      "title": "校园经典路线",
      "code": "c01"
    }
  },
  "game": {
    "mode": "classic-sequential",
    "rulesVersion": "1",
    "session": {
      "startManually": true,
      "requiresStartPunch": true,
      "requiresFinishPunch": true,
      "autoFinishOnLastControl": false,
      "maxDurationSec": 5400
    },
    "punch": {
      "policy": "enter-confirm",
      "radiusMeters": 10
    },
    "sequence": {
      "skip": {
        "enabled": false,
        "radiusMeters": 30,
        "requiresConfirm": true
      }
    },
    "guidance": {
      "showLegs": true,
      "legAnimation": true,
      "allowFocusSelection": false
    },
    "visibility": {
      "revealFullPlayfieldAfterStartPunch": true
    },
    "finish": {
      "finishControlAlwaysSelectable": false
    },
    "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 当前为 course
• source.type 当前推荐为 kml
• source.url KML 地址
• CPRadius 检查点绘制半径，单位米
• metadata 路线元数据

game.session

• startManually 是否需要先点击开始按钮
• requiresStartPunch 是否必须先打开始点
• requiresFinishPunch 是否必须打终点
• autoFinishOnLastControl 是否打完最后一个检查点自动结束
• maxDurationSec 最大比赛时长

game.punch

• policy 当前推荐 enter-confirm
• radiusMeters 正常打点半径

game.sequence

• skip 顺序赛跳点规则
• enabled 是否允许跳点
• radiusMeters 跳点半径，必须大于打点半径
• requiresConfirm 是否必须用户确认后跳点

当前基础版建议先关闭：

"enabled": false

game.guidance

• showLegs 是否显示腿线
• legAnimation 是否显示当前腿动画
• allowFocusSelection 顺序赛一般为 false

game.visibility

• revealFullPlayfieldAfterStartPunch 开始点打卡后是否显示完整路线

game.finish

• finishControlAlwaysSelectable 顺序赛一般为 false

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.session.requiresStartPunch
• game.session.requiresFinishPunch

---

6. 当前阶段建议默认值

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

{
  "game": {
    "session": {
      "startManually": true,
      "requiresStartPunch": true,
      "requiresFinishPunch": true,
      "autoFinishOnLastControl": false
    },
    "punch": {
      "policy": "enter-confirm",
      "radiusMeters": 10
    },
    "sequence": {
      "skip": {
        "enabled": false,
        "radiusMeters": 30,
        "requiresConfirm": true
      }
    },
    "guidance": {
      "showLegs": true,
      "legAnimation": true,
      "allowFocusSelection": false
    }
  }
}

---

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

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

1. 将老字段逐步迁入 map / playfield / game / resources / debug
2. 保持基础字段完整
3. 不急着一次性把所有高级规则上线

优先把“入口结构”夯实，再逐步扩玩法参数。

---

8. 一句话结论

顺序赛配置当前阶段建议：

• 用 playfield.kind = course
• 用 KML 承载空间底稿
• 用 game.session / game.punch / game.sequence / game.guidance 承载玩法规则
• 先把基础入口结构定稳，后续再细化跳点、惩罚、特殊引导等高级规则