16 KiB
16 KiB
游戏配置全量模板（当前开发实现版）
本文档提供一份 截至当前开发状态，客户端已实现或已正式消费的较完整配置模板。
目标：
- 给后端、后台、联调一份“当前最全可用模板”
- 帮助梳理哪些字段已经生效
- 后续新增字段时，以这份模板持续补充
说明：
- 本模板优先以当前客户端代码真实实现为准
- 不是未来终态，只代表“当前这一版已经能消费的字段”
- 以顺序赛为主模板，同时说明积分赛差异点
1. 当前最全模板
{
"schemaVersion": "1",
"version": "2026.03.30",
"app": {
"id": "sample-full-001",
"title": "完整配置示例",
"locale": "zh-CN"
},
"settings": {
"autoRotateEnabled": {
"value": true,
"isLocked": false
},
"trackDisplayMode": {
"value": "tail",
"isLocked": false
},
"gpsMarkerStyle": {
"value": "beacon",
"isLocked": true
},
"showCenterScaleRuler": {
"value": false,
"isLocked": false
}
},
"map": {
"tiles": "../map/lxcb-001/tiles/",
"mapmeta": "../map/lxcb-001/tiles/meta.json",
"declination": 6.91,
"initialView": {
"zoom": 17
}
},
"playfield": {
"kind": "course",
"source": {
"type": "kml",
"url": "../kml/lxcb-001/10/c01.kml"
},
"CPRadius": 6,
"controlDefaults": {
"score": 10,
"template": "story",
"autoPopup": false,
"pointStyle": "classic-ring",
"pointColorHex": "#cc006b"
},
"metadata": {
"title": "完整路线示例",
"code": "full-001"
},
"controlOverrides": {
"start-1": {
"template": "focus",
"title": "比赛开始",
"body": "从这里触发，先熟悉地图方向。",
"clickTitle": "起点说明",
"clickBody": "点击起点可再次查看起跑说明。",
"autoPopup": true,
"once": true,
"priority": 1,
"contentExperience": {
"type": "h5",
"url": "https://example.com/content/start-1",
"bridge": "content-v1",
"presentation": "fullscreen"
},
"clickExperience": {
"type": "h5",
"url": "https://example.com/content/start-1-click",
"bridge": "content-v1",
"presentation": "fullscreen"
}
},
"control-1": {
"template": "story",
"score": 10,
"title": "第一检查点",
"body": "完成该点后继续推进。",
"clickTitle": "第一检查点",
"clickBody": "点击查看该点的补充说明。",
"autoPopup": true,
"once": false,
"priority": 1,
"contentExperience": {
"type": "h5",
"url": "https://example.com/content/control-1",
"bridge": "content-v1",
"presentation": "fullscreen"
},
"clickExperience": {
"type": "h5",
"url": "https://example.com/content/control-1-click",
"bridge": "content-v1",
"presentation": "fullscreen"
}
},
"control-2": {
"template": "minimal",
"title": "第二检查点",
"body": "这个点配置成手动查看内容。",
"clickTitle": "第二检查点",
"clickBody": "点击查看手动内容。",
"autoPopup": false,
"once": true,
"priority": 1
},
"finish-1": {
"template": "focus",
"title": "比赛结束",
"body": "恭喜完成本次路线。",
"clickTitle": "终点说明",
"clickBody": "点击终点可再次查看结束说明。",
"autoPopup": false,
"once": true,
"priority": 2,
"clickExperience": {
"type": "h5",
"url": "https://example.com/content/finish-1-click",
"bridge": "content-v1",
"presentation": "fullscreen"
}
}
},
"legDefaults": {
"style": "classic-leg",
"colorHex": "#cc006b",
"widthScale": 1
}
},
"game": {
"mode": "classic-sequential",
"rulesVersion": "1",
"session": {
"startManually": false,
"requiresStartPunch": true,
"requiresFinishPunch": true,
"autoFinishOnLastControl": false,
"minCompletedControlsBeforeFinish": 1,
"maxDurationSec": 5400
},
"punch": {
"policy": "enter-confirm",
"radiusMeters": 5,
"requiresFocusSelection": false
},
"sequence": {
"skip": {
"enabled": true,
"radiusMeters": 10,
"requiresConfirm": false
}
},
"guidance": {
"showLegs": true,
"legAnimation": true,
"allowFocusSelection": false
},
"visibility": {
"revealFullPlayfieldAfterStartPunch": true
},
"finish": {
"finishControlAlwaysSelectable": false
},
"telemetry": {
"heartRate": {
"age": 30,
"restingHeartRateBpm": 62,
"userWeightKg": 65
}
},
"audio": {
"distantDistanceMeters": 80,
"approachDistanceMeters": 20,
"readyDistanceMeters": 5,
"cues": {
"guidance:distant": {
"loopGapMs": 4800,
"volume": 0.34
},
"guidance:approaching": {
"loopGapMs": 950,
"volume": 0.58
},
"guidance:ready": {
"loopGapMs": 650,
"volume": 0.68
}
}
},
"feedback": {
"audioProfile": "default",
"hapticsProfile": "default",
"uiEffectsProfile": "default"
}
},
"resources": {
"audioProfile": "default",
"contentProfile": "default",
"themeProfile": "default-race"
},
"debug": {
"allowModeSwitch": false,
"allowMockInput": false,
"allowSimulator": false
}
}
2. 顶层字段说明
schemaVersion
- 类型：
string - 必填：是
- 说明：配置结构版本
- 当前建议值：
"1"
version
- 类型：
string - 必填：是
- 说明：配置内容版本号
app
- 类型：
object - 必填：是
- 说明：活动级基础信息
map
- 类型：
object - 必填：是
- 说明：地图底座信息
playfield
- 类型：
object - 必填：是
- 说明：点位空间、内容覆盖、点位元信息
game
- 类型：
object - 必填：是
- 说明：玩法规则与对局流程
resources
- 类型：
object - 必填：否
- 说明：资源 profile 引用
debug
- 类型：
object - 必填：否
- 说明：调试开关
3. app 字段说明
app.id
- 类型：
string - 说明：活动配置 ID
app.title
- 类型：
string - 说明：活动标题 / 比赛名称
app.locale
- 类型：
string - 说明：语言环境
- 当前常用值：
zh-CN
4. map 字段说明
map.tiles
- 类型：
string - 必填：是
- 说明：瓦片根路径
map.mapmeta
- 类型：
string - 必填：是
- 说明：地图 meta 文件路径
map.declination
- 类型：
number - 必填：否
- 说明：磁偏角
- 影响：真北 / 磁北换算
map.initialView.zoom
- 类型：
number - 必填：否
- 说明：初始缩放级别
- 建议默认值：
17
5. playfield 字段说明
playfield.kind
- 类型：
string - 说明：空间对象类型
- 当前常用值：
coursecontrol-set
playfield.source.type
- 类型：
string - 说明：空间来源类型
- 当前推荐值：
kml
playfield.source.url
- 类型：
string - 说明：KML 路径
playfield.CPRadius
- 类型：
number - 说明：检查点绘制半径
- 建议默认值：
6
playfield.metadata.title
- 类型：
string - 说明：路线标题
playfield.metadata.code
- 类型：
string - 说明：路线编码
6. playfield.controlDefaults / playfield.controlOverrides 字段说明
推荐优先级：
系统默认值 -> 玩法默认值 -> playfield.controlDefaults -> playfield.controlOverrides
playfield.controlDefaults
- 类型：
object - 说明：普通检查点的活动级默认配置
- 作用：减少重复书写，未单独覆盖的普通检查点默认继承这里
playfield.controlOverrides
- 类型：
object - 说明：起点、普通点、终点的单点覆盖
- 作用：只写与活动默认不同的点
key 命名规则
- 起点：
start-1 - 普通点：
control-1、control-2、control-3 - 终点：
finish-1
当前支持字段
template
- 类型：
string - 说明：原生内容卡模板
- 当前支持：
minimalstoryfocus
score
- 类型：
number - 说明：积分赛点位分值
title
- 类型：
string - 说明：打点完成后自动弹出的标题
body
- 类型：
string - 说明：打点完成后自动弹出的正文
clickTitle
- 类型：
string - 说明：点击点位时弹出的标题
- 默认逻辑：最小模板下默认不启用；仅在显式配置点击内容能力时生效
clickBody
- 类型：
string - 说明：点击点位时弹出的正文
- 默认逻辑：最小模板下默认不启用；仅在显式配置点击内容能力时生效
autoPopup
- 类型：
boolean - 说明：打点完成后是否自动弹出
- 默认逻辑：最小模板下默认
false - 特殊逻辑：
game.punch.policy = "enter"时不自动弹原生内容 - 补充说明：白色内容卡已改为显式配置启用；普通点只有显式设置
autoPopup = true才会在打点后先弹白卡 - 补充说明：终点完成后默认直接进入结果页，不走白色内容卡链路
once
- 类型：
boolean - 说明：本局只展示一次
- 默认逻辑：
false
priority
- 类型：
number - 说明：内容优先级，越大越高
- 默认逻辑：
- 普通点：
1 - 终点：
2
- 普通点：
contentExperience
- 类型：
object - 说明：打点完成后的 H5 详情/互动扩展配置
- 注意：当前不是直接顶替原生弹窗，而是通过原生卡片 CTA 进入
contentExperience.type
- 类型：
string - 说明：内容扩展承载类型
- 当前支持：
nativeh5
contentExperience.url
- 类型：
string - 说明：H5 详情页地址
contentExperience.bridge
- 类型：
string - 说明：Bridge 协议版本
- 当前推荐值：
content-v1
contentExperience.presentation
- 类型：
string - 说明：H5 内容页展示形态
- 当前运行建议：
fullscreen
- 兼容历史值：
dialogsheet
- 备注：经过真机验证，
web-view不再承担局部弹窗职责；当前应按“原生内容卡 + H5 全屏详情页/任务页”理解。
clickExperience
- 类型：
object - 说明：点击点位时的 H5 详情/互动扩展配置
- 规则同
contentExperience
7. game 字段说明
game.mode
- 类型：
string - 说明：玩法模式
- 当前常用值：
classic-sequentialscore-o
game.rulesVersion
- 类型：
string - 说明：规则版本号
game.session.startManually
- 类型：
boolean - 说明：是否手动开始
- 顺序赛建议默认值：
false
game.session.requiresStartPunch
- 类型：
boolean - 说明：是否必须打起点
game.session.requiresFinishPunch
- 类型：
boolean - 说明：是否必须打终点
game.session.autoFinishOnLastControl
- 类型：
boolean - 说明：最后一个目标完成后是否自动结束
game.session.minCompletedControlsBeforeFinish
- 类型：
number - 说明：终点生效前至少需要完成的普通检查点数量
- 建议默认值：
- 顺序赛：
0 - 积分赛：
1
- 顺序赛：
game.session.maxDurationSec
- 类型：
number - 说明：最大对局时长，单位秒
game.punch.policy
- 类型：
string - 说明：打点策略
- 当前常用值：
enter-confirmenter
game.punch.radiusMeters
- 类型：
number - 说明：打点半径，单位米
game.punch.requiresFocusSelection
- 类型：
boolean - 说明：是否需要先聚焦/选中目标再打点
- 建议默认值：
- 顺序赛：
false - 积分赛：
false
- 顺序赛：
game.sequence.skip.enabled
- 类型：
boolean - 说明：顺序赛是否允许跳点
game.sequence.skip.radiusMeters
- 类型：
number - 说明：跳点可用半径
- 顺序赛建议默认值：打点半径的
2倍
game.sequence.skip.requiresConfirm
- 类型：
boolean - 说明：跳点是否需要二次确认
- 顺序赛建议默认值：
false
game.guidance.showLegs
- 类型：
boolean - 说明：是否显示路线腿段
game.guidance.legAnimation
- 类型：
boolean - 说明：是否开启路线腿段动画
game.guidance.allowFocusSelection
- 类型：
boolean - 说明：是否允许点击点位选中目标
game.visibility.revealFullPlayfieldAfterStartPunch
- 类型：
boolean - 说明：打完起点后是否显示完整场地
game.finish.finishControlAlwaysSelectable
- 类型：
boolean - 说明：终点是否始终可选
game.telemetry.heartRate.age
- 类型：
number - 说明：用户年龄
game.telemetry.heartRate.restingHeartRateBpm
- 类型：
number - 说明：静息心率
game.telemetry.heartRate.userWeightKg
- 类型：
number - 说明：体重，单位公斤
game.feedback.audioProfile
- 类型：
string - 说明：音效 profile
game.feedback.hapticsProfile
- 类型：
string - 说明：震动 profile
game.feedback.uiEffectsProfile
- 类型：
string - 说明：UI 动效 profile
game.audio
- 类型：
object - 说明：高级音频运行时配置，用于控制三档距离提示音的距离阈值和 cue 参数
game.audio.distantDistanceMeters
- 类型：
number - 说明：远距离提示音阈值
- 建议默认值：
80
game.audio.approachDistanceMeters
- 类型：
number - 说明：接近提示音阈值
- 建议默认值：
20
game.audio.readyDistanceMeters
- 类型：
number - 说明：可打点提示音阈值
- 建议默认值：
5 - 备注：
- 运行时不会低于
game.punch.radiusMeters
- 运行时不会低于
game.audio.cues["guidance:distant" | "guidance:approaching" | "guidance:ready"]
- 类型：
object - 说明：三档距离提示音的 cue 级配置
- 当前支持字段：
srcvolumelooploopGapMs
8. resources 字段说明
resources.audioProfile
- 类型：
string - 说明：资源音效配置档
resources.contentProfile
- 类型：
string - 说明：内容资源配置档
resources.themeProfile
- 类型：
string - 说明：主题配置档
9. debug 字段说明
debug.allowModeSwitch
- 类型：
boolean - 说明：是否允许玩法切换调试
debug.allowMockInput
- 类型：
boolean - 说明：是否允许模拟输入
debug.allowSimulator
- 类型：
boolean - 说明：是否允许模拟器调试
10. 积分赛差异点
如果使用积分赛，通常要修改这几项：
{
"playfield": {
"kind": "control-set"
},
"game": {
"mode": "score-o",
"session": {
"startManually": false
},
"punch": {
"requiresFocusSelection": true
},
"guidance": {
"showLegs": false,
"legAnimation": false,
"allowFocusSelection": true
},
"finish": {
"finishControlAlwaysSelectable": true
}
}
}
并在 playfield.controlDefaults 中先写普通点统一默认，必要时再在 playfield.controlOverrides 中为少量特殊点补：
score