# 运行时编译层总表

本文档用于定义当前项目推荐的“运行时编译层”结构，也就是把系统默认值、玩法默认值、活动配置、玩家设置编译成统一运行时 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](D:/dev/cmr-mini/miniprogram/game/core/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. 当前结论

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

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

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