diff --git a/docs/plan/Unity式SceneView_Gizmo系统完整审查与正式化重构方案.md b/docs/plan/Unity式SceneView_Gizmo系统完整审查与正式化重构方案.md index 87b4d123..725f9689 100644 --- a/docs/plan/Unity式SceneView_Gizmo系统完整审查与正式化重构方案.md +++ b/docs/plan/Unity式SceneView_Gizmo系统完整审查与正式化重构方案.md @@ -808,3 +808,199 @@ ISceneViewportGizmoProvider - Phase 1:已完成 - Phase 2:已完成并收口 - Phase 3 及后续阶段:仍待继续推进 + +--- + +## 12. 下一阶段执行计划 2026-04-03 + +基于当前真实代码状态,下一阶段不应继续直接堆叠新 gizmo 功能,而应优先完成 `Phase 3: Gizmo Provider Registry`。当前最主要的结构性问题有三处: + +1. `SceneViewportOverlayBuilder` 仍是大单体 + - camera gizmo + - light gizmo + - scene icon / frustum / helper 生成逻辑仍堆在同一处 + +2. `SceneViewPanel` 仍参与 transform gizmo 的 transient overlay 注入 + - 仍通过 `SetSceneViewTransientTransformGizmoOverlayData(...)` 把临时 frame data 注入宿主 + - 这说明 transform gizmo 还没有真正并入正式 provider 体系 + +3. `OrientationGizmo` 仍属于 HUD/ImGui 历史链路 + - 现在功能上可用 + - 但尚未在架构层被正式命名为 HUD overlay + +因此,下一阶段推荐拆成如下 4 个可执行小阶段。 + +### 12.1 Phase 3A:Overlay Provider Registry 落地 + +目标: +- 把“谁负责生成 SceneView world overlay”从 `SceneViewportOverlayBuilder` 中拆出 +- 让 `builder` 退化成聚合器,而不是所有 gizmo 规则的实现者 + +本阶段应新增: +- `ISceneViewportOverlayProvider` +- `SceneViewportOverlayProviderRegistry` +- `SceneViewportOverlayBuildContext` + +本阶段应先拆出的 provider: +- `SceneViewportCameraOverlayProvider` +- `SceneViewportLightOverlayProvider` + +本阶段不应做: +- 不修改 gizmo 样式 +- 不动 transform gizmo 交互算法 +- 不改 orientation gizmo + +完成标志: +- `SceneViewportOverlayBuilder` 不再直接内嵌 camera/light 具体生成逻辑 +- provider 可以按顺序注册并聚合输出 `SceneViewportOverlayFrameData` +- SceneView 现有 camera/light 图标、frustum、directional light helper 视觉结果保持不变 + +建议测试: +- provider registry 装配顺序测试 +- camera provider contract 测试 +- light provider contract 测试 +- 现有 overlay render flow 测试继续通过 + +### 12.2 Phase 3B:Transform Gizmo 并入正式 Provider 体系 + +目标: +- 去掉当前的 transient gizmo overlay 桥接层 +- 让 move / rotate / scale gizmo 和其他 SceneView overlay 一样,成为正式 provider 输出 + +本阶段应处理: +- `SceneViewPanel` 中 gizmo frame 组织逻辑 +- `ViewportHostService` 中的 transient overlay 存储字段 +- `SceneViewportTransformGizmoFrameBuilder` + +建议方向: +- 引入 `SceneViewportTransformGizmoOverlayProvider` +- provider 输入来自统一的 gizmo state / selection state / camera state +- 输出仍然是统一的 `worldLines / screenTriangles / handleRecords` + +本阶段完成后,应删除或废弃: +- `SetSceneViewTransientTransformGizmoOverlayData(...)` +- `m_sceneViewTransientTransformGizmoOverlay` +- `m_sceneViewTransientTransformGizmoInputs` + +完成标志: +- `SceneViewPanel` 不再向宿主注入临时 gizmo overlay 数据 +- `ViewportHostService` 只消费正式 overlay provider 输出 +- move / rotate / scale gizmo 交互行为不回退 + +建议测试: +- move/rotate/scale gizmo provider 输出测试 +- overlay handle hit test 回归测试 +- SceneView render plan 下 gizmo 仍能正常显示与拾取 + +### 12.3 Phase 4:HUD Overlay 与 World Overlay 正式分层 + +目标: +- 把当前“能工作但还没正式命名”的 HUD 链路正规化 +- 明确区分 `world overlay` 与 `HUD overlay` + +本阶段应做: +- 保留 `SceneViewportEditorOverlayPass` 作为 world overlay GPU pass +- 将 `SceneViewportOverlayRenderer` 明确归类为 HUD overlay renderer +- 将 `OrientationGizmo` 明确纳入 HUD overlay 体系 + +本阶段之后的职责边界应为: +- `world overlay` + - scene icon + - camera frustum + - light helper + - transform gizmo +- `HUD overlay` + - orientation gizmo + - Scene toolbar + - 后续 label / hint / debug text + +完成标志: +- world/HUD 两条链路命名清楚 +- orientation gizmo 不再被视为历史遗留杂项 +- 后续 HUD 元素可持续接入,而不再向 world overlay 污染 + +建议测试: +- HUD overlay 独立渲染入口测试 +- SceneView panel 中 HUD/world 顺序与命中关系测试 + +### 12.4 Phase 5:Editor Gizmo 资源体系继续收口 + +目标: +- 继 shader 之后,把 gizmo 相关 editor 资源定位逻辑继续集中 + +本阶段建议新增: +- `SceneViewportResourcePaths` 或等价 editor resource locator + +本阶段应纳入统一入口的内容: +- gizmo shader 路径 +- camera/light icon 路径 +- 后续如果引入 mesh/wire helper 资源,也走同一入口 + +本阶段不要求: +- 不必立刻做 atlas +- 不必引入复杂资源注册中心 + +完成标志: +- panel/pass 内不再到处手写 `exeDir/../../resources/...` +- editor 资源定位逻辑集中,便于后续 packaging 与迁移 + +建议测试: +- 资源路径解析测试 +- working directory 改变后的 editor 资源加载测试 + +### 12.5 Phase 6:测试与打包边界收口 + +目标: +- 把当前已经成型的边界真正测住 + +需要补齐的关键测试类别: + +1. provider contract + - provider 输入什么 + - 必须输出什么 + - 禁止输出什么 + +2. render assembly contract + - SceneView render plan 如何装配 post-scene / overlay / HUD + +3. resource boundary + - editor-only shader / icon 不污染 runtime builtin + - player/runtime 构建不依赖 SceneView 专属资源 + +4. interaction regression + - gizmo handle hit test + - scene icon picking + - HUD 与 world overlay 的点击优先级 + +完成标志: +- 当前 plan 第 9 节中的 7 条完成态判定标准全部可被验证 + +### 12.6 推荐执行顺序 + +严格建议按下面顺序推进,不要跳阶段: + +1. Phase 3A +2. Phase 3B +3. Phase 4 +4. Phase 5 +5. Phase 6 + +原因: +- 先做 provider 化,才能消除 `builder` 与 `SceneViewPanel` 的持续膨胀 +- 先做 transform gizmo provider 化,后面 HUD/world 分层才不会再被临时桥接逻辑牵制 +- 资源与测试应在结构稳定后统一收口,而不是提前做成半成品 + +### 12.7 下一次会话的直接开工点 + +下一次正式实施时,优先执行 `Phase 3A`,并以如下拆分作为第一批提交目标: + +1. 新建 `ISceneViewportOverlayProvider` +2. 新建 `SceneViewportOverlayProviderRegistry` +3. 抽离 `SceneViewportCameraOverlayProvider` +4. 抽离 `SceneViewportLightOverlayProvider` +5. 让 `SceneViewportOverlayBuilder` 改为只负责: + - 构建上下文 + - 调用 provider registry + - 合并 `SceneViewportOverlayFrameData` + +这一步完成后,当前 SceneView gizmo 系统才算真正进入“可持续扩展”的第二阶段。