mini-prog/doc/gameplay/运行时编译层总表.md

运行时编译层总表

本文档用于定义当前项目推荐的“运行时编译层”结构，也就是把系统默认值、玩法默认值、活动配置、玩家设置编译成统一运行时 profile 的中间层。

目标：

• 避免页面、引擎、规则层到处直接读取原始配置
• 明确各种默认值和覆盖值的合并顺序
• 为后续继续收口代码提供统一目标

说明：

• 本文档讲的是“运行时编译结构”
• 它不替代字段字典和玩法规则文档
• 当前已先落第一版代码骨架，后续会逐步把更多模块并到这一层

---

1. 为什么需要编译层

当前系统里至少有 4 类来源：

1. 系统默认值
2. 玩法默认值
3. 活动配置
4. 玩家设置

如果页面、引擎、规则层分别自己去判断这些来源，问题会很快出现：

• 默认值散落
• 覆盖顺序不一致
• 同一个字段在不同页面里表现不同
• 后续后台接入后更难维护

所以推荐做法是：

先编译，再运行。

也就是：

默认值 / 配置 / 玩家设置 -> Runtime Profile -> MapEngine / Rule / HUD

---

2. 当前推荐编译顺序

2.1 规则与玩法相关

推荐顺序：

系统默认值 -> 玩法默认值 -> 活动配置

适用：

• 对局流程
• 打点规则
• 跳点规则
• 完赛规则
• 分值默认值

2.2 系统设置相关

推荐顺序：

系统设置默认值 -> 活动 settings 默认值 -> 玩家本地设置值

锁态单独处理：

系统默认锁态 -> 活动 settings 锁态 -> 本局锁态生命周期

说明：

• 设置值可以持久化
• 锁态不持久化
• 锁态只在当前游戏配置运行生命周期内生效

2.3 遥测相关

推荐顺序：

系统遥测默认值 -> 活动 telemetry 默认值 -> 玩家身体数据

适用：

• 年龄
• 静息心率
• 体重

---

3. 当前推荐 profile 结构

当前建议至少编译成以下几块：

3.1 map

负责地图底座级运行参数：

• 标题
• 控制点绘制半径
• 投影
• 磁偏角
• 初始缩放

3.2 game

负责玩法与规则层运行参数：

• 玩法模式
• 关门时间
• 关门预警时间
• 打点方式
• 打点半径
• 是否先选目标点
• 是否允许跳点
• 跳点半径
• 跳点确认
• 是否自动结束
• 默认点位分值

3.3 settings

负责系统设置页相关运行参数：

• 设置值最终结果
• 锁态最终结果
• 锁态生命周期是否激活

3.4 telemetry

负责遥测层运行参数：

• 合并后的遥测配置
• 当前玩家身体数据快照

3.5 presentation

负责表现层 profile：

• 控制点样式
• 轨迹样式
• GPS 点样式

3.6 feedback

负责反馈层 profile：

• 音效配置
• 震动配置
• UI 动效配置

---

4. 当前代码落点

第一版运行时编译骨架已落在：

• runtimeProfileCompiler.ts

当前已经开始编译的内容：

• game
• settings
• telemetry
• presentation
• feedback
• map

当前已接入页面 / 引擎的部分：

• 设置页运行时 profile
• 遥测层运行时 profile
• 反馈层运行时 profile
• 表现层 runtime profile
• 规则层中一部分 game profile 字段

当前接入说明：

• settings / telemetry / feedback 已开始作为日常运行入口使用
• 设置页大部分引擎型设置项已改成“先更新玩家设置，再统一走 settings profile 回灌 MapEngine”
• settings profile 现已通过 MapEngine.applyCompiledSettingsProfile(...) 统一应用，不再由页面逐项调用各类 handleSet...
• presentation 已开始通过编译层回写 MapEngine 表现参数
• game 当前已先接入模式、关门时间、打点和跳点这组核心字段
• map 已开始接入地图底座参数和配置状态文本这组基础字段
• MapEngine.applyRemoteMapConfig(...) 已开始退回为原始场地与资源入口，不再继续双写已编译字段

后续建议继续并入：

• MapEngine.applyRemoteMapConfig(...) 的配置归一入口
• map profile
• 更多 game profile 字段
• courseToGameDefinition

---

5. 当前推荐落地步骤

建议按以下顺序继续收代码：

1. 先让剩余设置层完全只吃 settings profile
2. 再让遥测层只吃 telemetry profile
3. 再让反馈层只吃 feedback profile
4. 最后把玩法规则入口和表现入口都改成吃统一 profile

补充：

• 规则层中的目标角色也应尽量由统一运行态承载，而不是散落在 HUD 和地图展示字段里反推
• 当前已先明确 4 类目标角色：
  • 可打目标
  • 引导目标
  • HUD 目标
  • 展示高亮目标

这样风险最小，也最容易逐步验证。

---

6. 这层的边界

运行时编译层应该只做两件事：

1. 合并来源
2. 产出最终运行态 profile

不应该做的事：

• 不直接承载页面状态
• 不直接承载本局临时分数和目标点
• 不直接写回配置
• 不承担玩法执行逻辑本身

也就是说：

• 编译层负责“准备好”
• 引擎和规则层负责“执行”

---

7. 当前结论

后续推荐统一按这条链走：

系统默认值 -> 玩法默认值 -> 活动配置 -> 玩家设置 -> 运行时编译层 -> 引擎 / 页面 / 规则

这样配置越多，系统越不容易乱；后续后台做复杂了，也还是有一层中间结构兜住。