142 lines
5.9 KiB
Markdown
142 lines
5.9 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
|
|
- 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. `EditorRuntimeCoordinator`
|
|
owns scene document state: current path/name, dirty flag, new/open/save
|
|
routing, and runtime-mode transitions.
|
|
- `ProjectPanel` may identify an openable scene asset, but scene document loading
|
|
must go through `EditorFrameServices::RequestOpenSceneAsset` 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
|
|
|
|
## 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
|
|
- 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 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`
|