MikuMikuAR 文档

Appearance

ADR-111: 场景/环境菜单按用户直觉重新划分 ​

状态 ​

状态: 已实施 日期: 2026-07-14

开始日期: 2026-07-14

背景与问题 ​

当前菜单结构按「实现归属」划分，而非按「用户心智模型」组织：

场景菜单                    环境菜单
+-- 后处理                  +-- 天空
+-- 舞台（道具/灯光）       +-- 水面
+-- 物理                    +-- 地面
+-- 编队                    +-- 雾/风/粒子/光照
                            `-- 环境预设

问题：

  1. 地面、水面属于「舞台」概念（场景内容），却放在「环境」菜单下，违背用户直觉。
  2. 后处理（Bloom/DOF/色调映射）本质是「渲染氛围」，放在「场景」菜单下语义模糊。
  3. 地面/水面状态（envState.groundLevel/envState.waterLevel）与环境预设深度耦合——切换环境预设会覆盖用户手动调整的地面/水面参数，这是功能缺陷。

目标 ​

按用户直觉重新划分菜单归属：

场景菜单                    环境菜单
+-- 舞台                    +-- 天空
|   +-- 地面                +-- 后处理 < Bloom/DOF/色调映射
|   +-- 水面                +-- 雾/风/粒子
|   +-- 道具                +-- 光照
|   `-- 灯光                `-- 环境预设
+-- 物理
`-- 编队

分步实施计划 ​

Phase 1：解耦状态（核心修复） ​

目标：地面/水面状态与环境预设解耦，切换预设不再覆盖用户手动参数。

改动范围：

  • env-preset-levels.ts — 环境预设应用时不再写入 envState.groundLevel/envState.waterLevel
  • 验证：切换环境预设后，地面/水面参数保持不变

验收标准：

  • [x] 手动调整地面参数 → 切换环境预设 → 地面参数不丢失
  • [x] 手动调整水面参数 → 切换环境预设 → 水面参数不丢失

Phase 2：迁移 UI 归属（纯 UI 重排） ​

目标：菜单结构调整，状态 bind 关系不变。

改动范围：

  • ui-scene-stage-levels.ts（新建）— 承接地面、水面的 UI builder
  • ui-scene-levels.ts — 移除地面、水面 builder
  • ui-env-levels.ts — 移除地面、水面 builder
  • ui-env-preset-levels.ts — 环境预设 UI 不变

验收标准：

  • [x] 场景菜单下有「舞台」folder，含地面、水面、道具、灯光
  • [x] 环境菜单下无地面、水面
  • [x] 切换场景/环境菜单，状态 bind 正常

Phase 3：后处理迁移（pipeline 改造） ​

目标：后处理 UI 从场景菜单迁到环境菜单。

改动范围：

  • scene-render-levels.ts — 移除后处理 builder
  • env-levels.ts（新建或扩展）— 承接后处理 builder
  • renderer.ts — pipeline 初始化逻辑不变（仅 UI 归属变）

验收标准：

  • [x] 环境菜单下有「后处理」folder，含 Bloom/DOF/色调映射
  • [x] 场景菜单下无后处理
  • [x] 后处理效果实时生效

技术约束 ​

  1. 状态所有权不变：envState.groundLevel/envState.waterLevel 保留在 envState 中，Phase 1 仅解耦预设覆盖行为，不迁移状态。
  2. 向后兼容：Phase 2/3 期间，已有功能不受影响，逐步迁移。
  3. 无破坏性重构：每个 Phase 独立可验证，不在单次 PR 中混合多个 Phase。

未解决的问题 ​

  • [ ] Phase 1 解耦后，环境预设的「地面/水面默认值」如何表达？是否需要单独的 preset-ground / preset-water 覆盖逻辑？
  • [ ] Phase 3 后处理 pipeline 初始化是否需要重构（当前在 renderer.ts 中集中初始化）？

相关文档 ​

  • docs/menu-how-to.md — 菜单配置方式
  • docs/design.md — UI 设计规范

提交记录 ​

日期Phase描述
2026-07-15Phase 1+2+3env menu redistribution（commit f1c962e）— 地面/水面开关迁至场景→舞台，后处理迁至环境菜单
2026-07-18Phase 2 修复地面/水面完整参数面板（buildGroundLevel/buildWaterLevel）接入场景→舞台 slideRow 箭头导航；scene-stage 测试修复
2026-07-18Phase 2 修订灯光从「舞台」子 folder 提至场景菜单根级（scene:stageLight）。理由：① 灯光是高频调整项，藏在舞台 folder 下增加导航深度（根级→舞台→灯光 3 层 vs 根级→灯光 2 层）；② 用户心智中「灯光」独立于「舞台布景」（地面/水面/道具）；③ 与 ADR-120 atmosphere 预设组联动时，根级入口更易发现。原目标图的「舞台含灯光」结构废止。

修订记录 ​

2026-07-18：灯光提到根级 ​

原 Phase 2 目标图将灯光归入「舞台」folder：

场景菜单
+-- 舞台
|   +-- 地面
|   +-- 水面
|   +-- 道具
|   `-- 灯光  ← 原计划

实际实施时调整为根级入口：

场景菜单
+-- 灯光      ← 实际（根级）
+-- 舞台
|   +-- 地面
|   +-- 水面
|   `-- 道具

理由：

  1. 导航深度：灯光是高频调整项，根级可达 ≤2 层；藏于舞台 folder 需 3 层
  2. 心智模型：用户视「灯光」为独立于「舞台布景」（地面/水面/道具）的概念
  3. 预设联动：与 ADR-120 atmosphere 预设组（含 lightingPresetName）联动时，根级入口更易发现

不影响：状态 bind 关系不变（envState.lightingPresetName 等），仅 UI 归属调整。