231 lines
8.5 KiB
Markdown
231 lines
8.5 KiB
Markdown
# 配置分级总表
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-02
|
||
|
||
|
||
本文档用于把当前配置体系按“核心必需项 / 常用活动项 / 高级实验项”三层整理，作为后续后台配置设计、活动装配和字段治理的统一依据。
|
||
|
||
目标：
|
||
|
||
- 防止把所有内部变量都直接暴露成后台配置
|
||
- 明确哪些字段适合最先做成后台表单
|
||
- 明确哪些字段只应保留在高级配置区或 JSON 扩展区
|
||
- 支撑“默认能跑、少配能跑、多配能扩”的可伸缩配置方案
|
||
|
||
说明：
|
||
|
||
- 本文档关注的是“字段开放策略”，不是字段字典本身
|
||
- 字段定义、类型、默认值仍以 [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md) 为准
|
||
- 玩法专属使用范围仍以各玩法目录下的文档为准
|
||
|
||
---
|
||
|
||
## 1. 分级原则
|
||
|
||
### 1.1 核心必需项
|
||
|
||
满足以下条件的字段应归入核心必需项：
|
||
|
||
- 不填就无法正常进入游戏
|
||
- 不填会导致地图、场地或玩法主流程无法成立
|
||
- 后台创建一个新活动时几乎一定会填写
|
||
|
||
特点：
|
||
|
||
- 数量要少
|
||
- 后台首屏就能录入
|
||
- 应优先做成明确表单项
|
||
|
||
### 1.2 常用活动项
|
||
|
||
满足以下条件的字段应归入常用活动项：
|
||
|
||
- 不填也能跑，但活动运营经常会改
|
||
- 改动后会明显影响玩家体验或活动策略
|
||
- 属于“常见活动差异”，而不是内部实现细节
|
||
|
||
特点：
|
||
|
||
- 可以在后台做成“高级设置”分组
|
||
- 建议有默认值
|
||
- 应控制数量，避免首版后台过重
|
||
|
||
### 1.3 高级实验项
|
||
|
||
满足以下条件的字段应归入高级实验项：
|
||
|
||
- 只在少数玩法或实验活动中才需要
|
||
- 更偏表现调优、体验实验、联调或研发控制
|
||
- 暂时不适合做成常规后台表单
|
||
|
||
特点：
|
||
|
||
- 默认不暴露给普通运营
|
||
- 更适合放在高级 JSON 区或内部配置区
|
||
- 后续可以按实际使用频率再降级到常用活动项
|
||
|
||
---
|
||
|
||
## 2. 推荐后台策略
|
||
|
||
建议后续后台按三层展示：
|
||
|
||
1. 基础信息
|
||
2. 常用活动设置
|
||
3. 高级配置
|
||
|
||
其中：
|
||
|
||
- 基础信息只对应核心必需项
|
||
- 常用活动设置对应常用活动项
|
||
- 高级配置对应高级实验项和 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. 这个字段是不是只是研发或实验阶段才会动？
|
||
|
||
对应落点：
|
||
|
||
- 第 1 类：核心必需项
|
||
- 第 2 类：常用活动项
|
||
- 第 3 类：高级实验项
|
||
|
||
如果无法明确归类，默认先归入高级实验项，不急着开放到后台常规表单。
|
||
|