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:

bind real owners for run.*
bind real owners for scripts.*
bind real owners for scene document commands such as file.new_scene, file.open_scene, file.save_scene, and file.save_scene_as
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. The game viewport path is real, but that does not mean play-mode ownership is complete.
EditorHostCommandBridge still exposes honest failure messages for commands without a bound owner. Do not replace these with fake success.
EditorSceneRuntime already owns real scene editing behavior. Missing work is usually at the app/document/runtime owner layer, not in the raw scene backend.
ProjectPanel should keep using explicit runtime ownership and honest blocked behavior for unsupported asset commands.

Working Rules

prefer explicit owner/coordinator/runtime-service seams over direct panel to engine hookups
when changing runtime or document flow, inspect EditorSession, 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

Good Entry Points

editor/app/Bootstrap/Application.cpp
editor/app/Composition/EditorContext.cpp
editor/app/Composition/EditorShellRuntime.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:

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:

cmake --build build --config Debug --target XCEditor

Relevant focused tests include:

test_editor_host_command_bridge.cpp
test_game_viewport_runtime.cpp
test_project_panel.cpp
test_scene_viewport_render_plan.cpp
test_scene_viewport_runtime.cpp

4.1 KiB Raw Blame History