配置分级总表.md 8.5 KB
配置分级总表
文档版本：v1.0 最后更新：2026-04-02 08:28:05
本文档用于把当前配置体系按“核心必需项 / 常用活动项 / 高级实验项”三层整理，作为后续后台配置设计、活动装配和字段治理的统一依据。
目标：
- 防止把所有内部变量都直接暴露成后台配置
- 明确哪些字段适合最先做成后台表单
- 明确哪些字段只应保留在高级配置区或 JSON 扩展区
- 支撑“默认能跑、少配能跑、多配能扩”的可伸缩配置方案
说明：
- 本文档关注的是“字段开放策略”，不是字段字典本身
- 字段定义、类型、默认值仍以 配置选项字典 为准
- 玩法专属使用范围仍以各玩法目录下的文档为准
1. 分级原则
1.1 核心必需项
满足以下条件的字段应归入核心必需项：
- 不填就无法正常进入游戏
- 不填会导致地图、场地或玩法主流程无法成立
- 后台创建一个新活动时几乎一定会填写
特点：
- 数量要少
- 后台首屏就能录入
- 应优先做成明确表单项
1.2 常用活动项
满足以下条件的字段应归入常用活动项：
- 不填也能跑，但活动运营经常会改
- 改动后会明显影响玩家体验或活动策略
- 属于“常见活动差异”，而不是内部实现细节
特点：
- 可以在后台做成“高级设置”分组
- 建议有默认值
- 应控制数量，避免首版后台过重
1.3 高级实验项
满足以下条件的字段应归入高级实验项：
- 只在少数玩法或实验活动中才需要
- 更偏表现调优、体验实验、联调或研发控制
- 暂时不适合做成常规后台表单
特点：
- 默认不暴露给普通运营
- 更适合放在高级 JSON 区或内部配置区
- 后续可以按实际使用频率再降级到常用活动项
2. 推荐后台策略
建议后续后台按三层展示：
- 基础信息
- 常用活动设置
- 高级配置
其中：
- 基础信息只对应核心必需项
- 常用活动设置对应常用活动项
- 高级配置对应高级实验项和 JSON 扩展
不建议：
- 首版后台直接开放全部字段
- 把玩家个人设置和活动规则配置混在一起
- 把纯运行时状态做成配置项
3. 当前分级总表
3.1 核心必需项
| 字段 | 说明 | 备注 |
|---|---|---|
schemaVersion |
配置结构版本 | 建议固定为 "1" |
version |
配置版本号 | 建议按发布日期或发布号维护 |
app.id |
活动实例 ID | 必填 |
app.title |
活动标题 | 必填 |
map.tiles |
瓦片根路径 | 必填 |
map.mapmeta |
地图元数据路径 | 必填 |
playfield.kind |
场地类型 | 顺序赛常用 course，积分赛常用 control-set |
playfield.source.type |
场地来源类型 | 当前推荐 kml |
playfield.source.url |
场地源文件路径 | 必填 |
game.mode |
玩法模式 | 当前核心玩法：classic-sequential / score-o |
建议：
- 核心必需项应控制在
10个左右 - 新活动创建时，后台优先只要求填写这一层
3.2 常用活动项
| 字段 | 说明 | 备注 |
|---|---|---|
app.locale |
语言环境 | 常见默认值 zh-CN |
settings.*.value |
系统设置默认值 | 活动可覆盖玩家默认体验 |
settings.*.isLocked |
系统设置锁态 | 只在本局生命周期内生效 |
map.declination |
磁偏角 | 地图类活动常用 |
map.initialView.zoom |
初始缩放 | 常见活动会调 |
playfield.CPRadius |
控制点绘制半径 | 常用地图表现项 |
playfield.metadata.title |
路线标题 | 常用展示信息 |
playfield.metadata.code |
路线编码 | 常用管理字段 |
playfield.controlOverrides.<key>.score |
点位分值覆盖 | 积分赛常用 |
game.session.requiresStartPunch |
是否要求起点打卡 | 常用局流程控制 |
game.session.requiresFinishPunch |
是否要求终点打卡 | 常用局流程控制 |
game.session.autoFinishOnLastControl |
最后点自动结束 | 常用局流程控制 |
game.session.maxDurationSec |
最大时长 / 关门时间 | 常用赛事规则项 |
game.punch.policy |
打点方式 | 常用玩法差异项 |
game.punch.radiusMeters |
打点半径 | 常用活动调节项 |
game.punch.requiresFocusSelection |
是否先选目标 | 积分赛常用 |
game.sequence.skip.enabled |
是否允许跳点 | 顺序赛常用 |
game.sequence.skip.radiusMeters |
跳点半径 | 顺序赛常用 |
game.sequence.skip.requiresConfirm |
跳点是否确认 | 顺序赛常用 |
game.guidance.showLegs |
是否显示腿线 | 常用表现项 |
game.guidance.legAnimation |
腿线动画 | 常用表现项 |
game.guidance.allowFocusSelection |
是否允许地图选点 | 积分赛常用 |
game.visibility.revealFullPlayfieldAfterStartPunch |
起点后是否揭示全场 | 常用局流程表现项 |
game.finish.finishControlAlwaysSelectable |
终点是否始终可打 | 积分赛常用 |
game.scoring.defaultControlScore |
默认点位分值 | 常用计分项 |
建议：
- 常用活动项是后台第二层的重点
- 这层优先服务“活动策划/运营经常会改的东西”
3.3 高级实验项
| 字段 | 说明 | 备注 |
|---|---|---|
playfield.controlOverrides.<key>.template |
白卡模板 | 内容实验项 |
playfield.controlOverrides.<key>.title |
打点后内容标题 | 内容实验项 |
playfield.controlOverrides.<key>.body |
打点后内容正文 | 内容实验项 |
playfield.controlOverrides.<key>.clickTitle |
点击内容标题 | 显式启用型能力 |
playfield.controlOverrides.<key>.clickBody |
点击内容正文 | 显式启用型能力 |
playfield.controlOverrides.<key>.autoPopup |
是否自动弹白卡 | 内容实验项 |
playfield.controlOverrides.<key>.once |
是否仅一次 | 内容实验项 |
playfield.controlOverrides.<key>.priority |
内容优先级 | 内容实验项 |
playfield.controlOverrides.<key>.contentExperience.* |
打点后 H5 / 原生体验 | 高级体验项 |
playfield.controlOverrides.<key>.clickExperience.* |
点击 H5 / 原生体验 | 高级体验项 |
playfield.controlOverrides.<key>.pointStyle |
单点样式覆盖 | 表现调优项 |
playfield.controlOverrides.<key>.pointColorHex |
单点颜色覆盖 | 表现调优项 |
playfield.controlOverrides.<key>.pointSizeScale |
单点尺寸倍率 | 表现调优项 |
playfield.controlOverrides.<key>.pointAccentRingScale |
单点强调环倍率 | 表现调优项 |
playfield.controlOverrides.<key>.pointGlowStrength |
单点光晕强度 | 表现调优项 |
playfield.controlOverrides.<key>.pointLabelScale |
标签缩放 | 表现调优项 |
playfield.controlOverrides.<key>.pointLabelColorHex |
标签颜色覆盖 | 表现调优项 |
playfield.legOverrides.<key>.* |
腿线局部覆盖 | 表现调优项 |
game.presentation.* |
全局点位/腿线样式 | 当前更适合高级区 |
game.presentation.track.* |
轨迹表现细项 | 高级表现区 |
game.presentation.gpsMarker.* |
GPS 点表现细项 | 高级表现区 |
game.telemetry.* |
遥测计算参数 | 高级区或设备联调区 |
game.audio.* |
音效细项 | 高级表现区 |
game.haptics.* |
震动细项 | 高级表现区 |
game.uiEffects.* |
UI 动效细项 | 高级表现区 |
resources.* |
资源档与主题档 | 高级资源管理项 |
debug.* |
调试与模拟字段 | 默认不进正式后台 |
建议：
- 这一层先不要全做成常规表单
- 后期可以根据真实使用频率，把一部分下放到常用活动项
4. 当前建议的开放策略
4.1 先开放
优先开放这些：
- 核心必需项
- 常用活动项中的对局规则、打点规则、完赛规则、分值规则
4.2 后开放
后续再开放这些：
- 常用活动项中的部分设置默认值
- 少量高频使用的内容卡字段
- 少量高频使用的表现字段
4.3 暂不开放
建议先不开放这些：
- 大量细粒度动画参数
- 大量音效和震动细项
- 纯调试字段
- 仅研发联调使用的实验字段
5. 后续维护规则
后续每次新增配置能力时，建议先回答 3 个问题：
- 这个字段是不是不配就跑不了？
- 这个字段是不是活动经常会改？
- 这个字段是不是只是研发或实验阶段才会动？
对应落点：
- 第 1 类：核心必需项
- 第 2 类：常用活动项
- 第 3 类：高级实验项
如果无法明确归类，默认先归入高级实验项，不急着开放到后台常规表单。