Blacksite/docs/editor/README.md

Editor Framework Documentation

Docs for the in-process egui editor (crates/editor/). Update this index when adding editor subsystems.

Documents

Document	Contents
roadmap.md	Phased editor work and status
architecture.md	Plugins, cameras, PIE, settings split
brp.md	Remote protocol, authoring-only policy, commands
debt-audit.md	Zero-debt phase gates and remaining items
rendering.md	GI modes, post-process volumes, presets, post FX assets

Subsystems (code → doc)

Code module	Responsibility	Doc
lib.rs / EditorPluginGroup	Ordered plugin bundle, lib/bin split	ADR 0008, architecture.md
scene/	Level I/O, schema, viewport render-target setup	architecture.md
viewport/	Camera, selection, gizmos, render views	architecture.md
play/	PIE session, editor mode state	architecture.md
assets/	Catalog, asset DB, static mesh artifacts, thumbnails/, materials.rs, prefab overrides v2	this file (below), ADR 0017
project/	Workspace, settings UI, user prefs	roadmap Phase 1
ext/	Command palette, BRP, game panel adapters	ADR 0007
ui/mod.rs	Dock layout, unified viewport, menus	README controls
ui/component_registry.rs	Editor-visible component descriptors and Add Component palette metadata	ADR 0018
ui/asset_browser/	Asset Browser tree, grid/list, details	roadmap Phase 4b
history/	Undo/redo command stack	README controls
crates/scene	Schema stamp/migrate/validate (shared)	ADR 0006, ADR 0008
ext/extensibility.rs	Command registry, ActorInspectorSection, palette	Phase 6
ext/game_inspector.rs	Game-registered inspector sections	Phase 6

Design intentions (stable)

• EditorOnly helper entities never appear in hierarchy or saved scenes. Visualizer proxies are editor-only but selectable; selection resolves to their source entity.
• Dedicated egui Camera2d at full window — never attach PrimaryEguiContext to a viewport-cropped 3D camera (NaN layout panic).
• Unified viewport uses one render-to-texture target for both the editor fly camera and the possessed player camera so HDR/atmosphere is not broken by sub-viewport cropping.
• PIE: F8 possess/eject while sim runs; F6 pauses/resumes simulation in Play; project settings drive shared rendering for the active viewport camera.
• Asset browser mirrors the on-disk assets/ directory with project tree, breadcrumb, search/filter/sort, grid/list views, texture and model thumbnails (AssetThumbnailCache::request_model), and a compact details pane; narrow docks prioritize content, wrap toolbar/footer controls, switch list view to a compact single-column layout, and hide tree/details panes when they would crowd the content area. The footer stays pinned while only the project tree and asset content panels scroll. Built-ins holds spawnable primitives and lights. Materials folder scans assets/materials/*.ron; Shaders holds shader schema RON files. glTF/GLB/FBX details expose static asset vs scene-instance placement, hierarchy mode, material policy, collider generation, and the generated static mesh artifact path.
• Static mesh renderer — model drag/drop defaults to ActorKind::StaticMesh + StaticMeshRenderer using normalized artifacts under assets/meshes/generated/. Renderer slots store imported EditorAssetRef mesh/material references, not source FBX/glTF paths. SceneInstance placement keeps the legacy ImportedModel + ModelRef path for full scene playback.
• Collider split — imported mesh collision lives in a separate ColliderDesc::StaticMesh plus optional RigidBodyDesc; renderer slots own only render visibility, shadows, mesh, and material references.
• Material assets — MaterialAsset RON (label + MaterialDesc) is shader-schema aware. Actor material edits write MaterialOverride entries keyed by renderer slot ID; content-browser asset inspectors are the path for editing shared material assets.
• Prefab overrides — PrefabInstance.overrides_ron stores transform/material/child-visibility overrides; inspector collapsible groups with Apply / Revert (replaces transform-only revert v1).
• Theme selections use explicit high-contrast selected text and muted blue fills so hierarchy, asset browser, and inspector selection rows stay readable.
• Hierarchy shows authored objects plus useful runtime context (Player, PlayerCamera, Project Sun) while keeping runtime rows read-only.
• Player placement is authored through PlayerSpawn; selecting the runtime player in Edit mode redirects to a saved Player Start.
• World lighting has two layers: project default sun/ambient settings, and optional scene-authored directional LightDesc overrides. Scene → Lighting menu and Rendering panel (Window) restore project sun or bake a scene directional from project settings. Apply in Project Settings updates ambient and sun illuminance live.
• Rendering — GiMode + post-process volumes; see rendering.md. Window → Rendering shows requested/effective active-camera stack, fallback reason, Solari eligibility, viewport GI badge, and volume HUD.
• Inspector shows a responsive header, Transform, registered authoring component cards, and a pinned bottom Add Component footer (actor_inspector); only the component body scrolls. Rows wrap or stack inside narrow docks instead of forcing the panel wider, and legacy authoring sections use the same component-card shell. Component card carets collapse/expand for the current editor session, status dots toggle persisted active state, and triple-dot menus provide reset, copy/paste values, move, remove, and documentation slots. Inactive authoring components remain in the scene but are skipped by hydration/runtime queries, stripping their generated meshes, lights, physics, or post-process effects. StaticMeshRenderer uses concept-style slot cards with model thumbnails, imported mesh/material selectors, visibility, shadow flags, and per-actor material overrides. Empty actor material refs display the inherited source material from the generated static mesh artifact as Source default; selector Browse assigns explicit normalized imported sub-assets, Locate focuses the owning asset in the Asset Browser, and Clear returns optional material slots to the inherited source default. ColliderDesc and RigidBodyDesc are separate component cards. Game crates add sections via ActorInspectorSection + game::editor_ext::actor_inspector_section_ids().
• Command palette (Ctrl+P): scene.reset_lighting, rendering.create_volume, rendering.select_volumes_at_camera, rendering.focus_active_volumes, selection.group, selection.focus, and play commands.
• ActorKind is required on saved level objects (schema v2). Save strips hydrated ECS before writing .scn.ron.
• Scene visualizers expose actor root icons, colliders, lights, player spawns, prefab/model anchors, Project Sun, and runtime player/camera markers without changing saved scene data.
• Clean game-view overlay (G) hides editor chrome, grid, selection outlines, transform gizmos, actor root icons, visualizers, and selectable proxies without changing camera ownership; Ctrl+G toggles grid.
• Viewport shading (toolbar): Lit (default WYSIWYG), Unlit (base-color debug), Colliders (hide meshes, emphasize collider gizmos). Light gizmos show range spheres, spot cones, and directional sun arrows. A mode badge (bottom-right of the viewport) shows the active mode; Collider mode displays a warning banner.
• Hierarchy sort modes (Manual, Name, Type) use stable tie-breakers so duplicate names (e.g. several Pillar rows) do not reorder on every click. Drag-and-drop reparenting disables panel scroll-to-drag; drop indicators appear only while dragging.
• Viewport picking: click selects nearest object, actor root icon, or visualizer hit; Tab cycles overlapping targets at the last click (selection pin deferred).
• Settings data lives in crates/settings; settings UI lives in settings_ui.rs.

When implementing or changing any of the above, update this file and the root README in the same change.