5.3 KiB
5.3 KiB
运行时编译层总表
本文档用于定义当前项目推荐的“运行时编译层”结构，也就是把系统默认值、玩法默认值、活动配置、玩家设置编译成统一运行时 profile 的中间层。
目标：
- 避免页面、引擎、规则层到处直接读取原始配置
- 明确各种默认值和覆盖值的合并顺序
- 为后续继续收口代码提供统一目标
说明：
- 本文档讲的是“运行时编译结构”
- 它不替代字段字典和玩法规则文档
- 当前已先落第一版代码骨架，后续会逐步把更多模块并到这一层
1. 为什么需要编译层
当前系统里至少有 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. 当前代码落点
第一版运行时编译骨架已落在：
当前已经开始编译的内容：
gamesettingstelemetrypresentationfeedbackmap
当前已接入页面 / 引擎的部分：
- 设置页运行时 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. 当前推荐落地步骤
建议按以下顺序继续收代码：
- 先让剩余设置层完全只吃
settings profile - 再让遥测层只吃
telemetry profile - 再让反馈层只吃
feedback profile - 最后把玩法规则入口和表现入口都改成吃统一 profile
补充：
- 规则层中的目标角色也应尽量由统一运行态承载，而不是散落在 HUD 和地图展示字段里反推
- 当前已先明确 4 类目标角色：
- 可打目标
- 引导目标
- HUD 目标
- 展示高亮目标
这样风险最小，也最容易逐步验证。
6. 这层的边界
运行时编译层应该只做两件事：
- 合并来源
- 产出最终运行态 profile
不应该做的事：
- 不直接承载页面状态
- 不直接承载本局临时分数和目标点
- 不直接写回配置
- 不承担玩法执行逻辑本身
也就是说：
- 编译层负责“准备好”
- 引擎和规则层负责“执行”
7. 当前结论
后续推荐统一按这条链走：
系统默认值 -> 玩法默认值 -> 活动配置 -> 玩家设置 -> 运行时编译层 -> 引擎 / 页面 / 规则
这样配置越多，系统越不容易乱；后续后台做复杂了，也还是有一层中间结构兜住。