XCEngine/editor/AGENTS.md

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:

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_editor_runtime_coordinator.cpp
• test_game_viewport_runtime.cpp
• test_project_panel.cpp
• test_scene_viewport_render_plan.cpp
• test_scene_viewport_runtime.cpp