175 lines
8.1 KiB
Markdown
175 lines
8.1 KiB
Markdown
# Editor Agent Guide
|
|
|
|
This file is for agents working in `editor/**` and `tests/UI/Editor/**`.
|
|
Treat the current code and tests as source of truth. If this guide drifts from
|
|
the checkout, update it in the same change.
|
|
|
|
## Current Priority
|
|
|
|
The editor is not in a "split more layers for their own sake" phase.
|
|
|
|
The primary product line is still runtime/product loop closure:
|
|
|
|
- extend the bound `EditorRuntimeCoordinator` instead of adding panel-local
|
|
shortcuts for `run.*`, scene document commands, or project scene opens
|
|
- keep play mode transactional: `EditorRuntimeCoordinator` must enter play
|
|
through `EditorSceneRuntime::BeginPlaySession`, and `RuntimeLoop` must run
|
|
the play-session runtime scene rather than the editable document scene
|
|
- drive `EditorRuntimeCoordinator` from the app frame pump exactly once per
|
|
outer frame; do not tick runtime from per-window shell/content update paths
|
|
- bind a real script assembly builder behind `scripts.*`; until then the
|
|
coordinator must keep the command honestly disabled
|
|
- keep `Game`, `Scene`, `Inspector`, `Selection`, and `Console` coherent across
|
|
runtime transitions
|
|
|
|
Do not burn time on broad architectural churn unless it directly unlocks that
|
|
product loop or removes an active architectural hazard.
|
|
|
|
## Engine Boundary Status
|
|
|
|
The old public `EditorEngineServices` god interface is gone.
|
|
|
|
The current editor-to-engine boundaries are narrow and must stay narrow:
|
|
|
|
- `EditorSceneBackendFactory`
|
|
- `SceneViewportEngineBridge`
|
|
- `GameViewportEngineBridge`
|
|
- `EditorShaderProvider`
|
|
- `EditorEngineLifecycle`
|
|
|
|
`EngineEditorComposition` in `editor/app/Services/Engine/EngineEditorServices.*`
|
|
is an internal composition root that hands out those narrow interfaces. It is
|
|
not a new shared facade for features to depend on.
|
|
|
|
Rules:
|
|
|
|
- do not recreate `EditorEngineServices`
|
|
- do not add a replacement god interface under a different name
|
|
- do not make new panels, passes, or runtimes depend on a catch-all engine
|
|
service locator
|
|
- keep render-pass dependencies low-level: passes may depend on
|
|
`EditorShaderProvider`, not on scene backend creation or lifecycle code
|
|
- composition owns assembly; features and passes must receive explicit
|
|
dependencies
|
|
|
|
## Product Truths
|
|
|
|
- `GameViewportFeature`, `GameViewportRenderService`, and related tests exist.
|
|
`EditorRuntimeCoordinator` is now the app-level owner for play-mode command
|
|
routing and uses `RuntimeLoop` for the active play-session scene.
|
|
- Play mode is a scene transaction. The engine scene backend snapshots the
|
|
editable scene, replaces it with a runtime scene for play/step, and restores
|
|
the editable scene when the play session ends. Do not start runtime playback
|
|
directly from `EditorSceneRuntime::GetActiveScene()`.
|
|
- `EditorHostCommandBridge` delegates `file.*`, `run.*`, and `scripts.*` to a
|
|
bound runtime owner. If no owner is bound, it must continue exposing honest
|
|
disabled messages.
|
|
- `EditorSceneRuntime` owns raw scene editing behavior and scene mutations. It
|
|
may return transient startup/open/new results, but it must not own the live
|
|
scene document state. Scene viewport private state now lives in
|
|
`SceneViewportSession`, owned by the scene viewport feature/panel instance,
|
|
not by `EditorContext`, `EditorFrameServices`, or the shared scene runtime.
|
|
`EditorRuntimeCoordinator` owns scene document state: current path/name,
|
|
dirty flag, new/open/save routing, and runtime-mode transitions.
|
|
- `EditorRuntimeCoordinator` time advancement is app-owned. It must tick once
|
|
per outer application frame before window rendering, not once per workspace
|
|
window or once per shell update.
|
|
- `ProjectPanel` may identify an openable scene asset, but scene document loading
|
|
must go through the bound typed scene-open request callback and the
|
|
coordinator. Do not reintroduce `ProjectRuntime` pending-open queues.
|
|
- `scripts.rebuild` has a bound coordinator owner, but no in-process script
|
|
assembly builder is currently wired. Keep it disabled and explicit until that
|
|
builder exists.
|
|
- the old shared `EditorPanelServices` dependency bag is gone. Workspace and
|
|
utility panels now receive explicit bindings or panel-local contexts; do not
|
|
recreate a catch-all mutable panel service bundle under a new name
|
|
- `EditorFrameServices` remains a window/content orchestration boundary. It must
|
|
stay on the window/content and shell-orchestration seam only. It must not be
|
|
passed through the workspace-panel seam or the utility-window panel seam as a
|
|
generic dependency source; workspace panels and utility panels should receive
|
|
explicit panel-local bindings or typed callbacks instead. Runtime time-step
|
|
ownership does not belong on this interface.
|
|
|
|
## Working Rules
|
|
|
|
- prefer explicit owner/coordinator/runtime-service seams over direct panel to
|
|
engine hookups
|
|
- keep panel dependencies explicit. If a panel needs more data or actions, add a
|
|
narrow panel-local context or binding instead of routing everything through a
|
|
generic shared services struct
|
|
- keep utility-window dependencies explicit. Color picker, add-component, and
|
|
future utility panels must be constructed with the exact runtime/tool state
|
|
they use; do not make utility panel update paths depend on
|
|
`EditorFrameServices`
|
|
- keep viewport-local state local. Camera/tool mode/pivot/space state for Scene
|
|
belongs in `SceneViewportSession` on the feature/controller side; do not push
|
|
it back into shared runtime/context/frame-service layers for convenience
|
|
- do not reintroduce `void*` plus callback-function panel hooks for scene-open
|
|
or utility-window requests; use typed callbacks or explicit requester
|
|
interfaces instead
|
|
- when changing runtime or document flow, inspect `EditorSession`,
|
|
`EditorRuntimeCoordinator`, `EditorHostCommandBridge`, the relevant feature,
|
|
and the matching tests
|
|
- if a change affects ownership, state flow, or command routing, add or update
|
|
tests in `tests/UI/Editor/unit`
|
|
- keep multi-window work behind runtime/document correctness; do not move it
|
|
ahead of core ownership closure
|
|
|
|
## Do Not Regress
|
|
|
|
- no new service-locator style editor-to-engine dependency
|
|
- no new low-level render pass dependency on scene backend creation or lifecycle
|
|
- no silent fallback where a command should fail honestly
|
|
- no panel-local shortcut that bypasses the intended runtime owner
|
|
- no new shared mutable panel-services bag or service-locator style panel
|
|
dependency bundle
|
|
- no `EditorFrameServices` tunneling into workspace-panel update/prepare paths
|
|
- no `EditorFrameServices` tunneling into utility-window panel update paths
|
|
- no per-window or per-shell runtime ticking path; runtime must not advance once
|
|
per workspace window
|
|
- no new live scene document metadata on `EditorSceneRuntime`; coordinator
|
|
remains the single owner for current path/name/dirty state
|
|
- no new path where Scene viewport render requests or camera/tool state are
|
|
recomputed from `EditorContext` instead of the owning `SceneViewportSession`
|
|
- no scene-open side channel in `EditorProjectRuntime`; project UI must call the
|
|
panel service request hook
|
|
- no play-mode path that mutates the editable scene in place or skips
|
|
`EditorScenePlaySession`
|
|
|
|
## Good Entry Points
|
|
|
|
- `editor/app/Bootstrap/Application.cpp`
|
|
- `editor/app/Composition/EditorContext.cpp`
|
|
- `editor/app/Composition/EditorShellRuntime.cpp`
|
|
- `editor/app/Services/Runtime/EditorRuntimeCoordinator.cpp`
|
|
- `editor/app/Rendering/Viewport/ViewportHostService.cpp`
|
|
- `editor/app/Services/Engine/EngineEditorServices.h`
|
|
- `editor/app/Services/Scene/EditorSceneRuntime.cpp`
|
|
- `editor/app/Core/Commands/EditorHostCommandBridge.cpp`
|
|
- `docs/plan/editor-next-stage-runtime-plan.md`
|
|
- `docs/plan/editor-engine-services-refactor-plan.md`
|
|
|
|
## Verification
|
|
|
|
Minimum verification for editor app/core changes:
|
|
|
|
```powershell
|
|
cmake --build build --config Debug --target editor_app_core_tests
|
|
cmake --build build --config Debug --target editor_app_feature_tests
|
|
```
|
|
|
|
When the executable path is affected, also rebuild:
|
|
|
|
```powershell
|
|
cmake --build build --config Debug --target XCEditor
|
|
```
|
|
|
|
Relevant focused tests include:
|
|
|
|
- `test_editor_host_command_bridge.cpp`
|
|
- `test_editor_runtime_coordinator.cpp`
|
|
- `test_game_viewport_runtime.cpp`
|
|
- `test_project_panel.cpp`
|
|
- `test_scene_viewport_render_plan.cpp`
|
|
- `test_scene_viewport_runtime.cpp`
|