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
brushes.md	Brush authoring schema, hydration behavior, and MVP limits

Subsystems (code → doc)

Code module	Responsibility	Doc
lib.rs / EditorPluginGroup	Ordered plugin bundle, lib/bin split	ADR 0008, architecture.md
shared::components::BrushDesc / shared::hydration::brushes	Persisted brush authoring data and generated runtime mesh hydration	brushes.md, ADR 0021
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
operators.rs	Operator lifecycle/status bridge for commands and future modal tools	BS-JD-004
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.
• Jackdaw-inspired roadmap work follows ADR 0020: use Jackdaw as design/API inspiration only unless a ticket explicitly marks code-derived work with source, license, and upstream commit notes. Clean-room implementation is preferred for geometry, terrain, operator, and extension systems.
• 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/model/material thumbnails, a details pane, and context-aware row/menu actions; narrow docks prioritize content, keep the root panel fixed, 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, asset content, and details panels scroll. Built-ins holds spawnable primitives and lights. Materials folder scans assets/materials/*.ron, renders material thumbnails on a sphere using MaterialDesc, and exposes shader-schema-driven parameters/textures in the details editor; Shaders holds shader schema RON files. glTF/GLB/FBX rows can expand into a shelf of normalized embedded mesh, material, and texture subassets with independent generated thumbnails. Mesh subassets can be selected, dragged into the viewport, or placed from details/context menus; material subassets render source-material spheres; texture subassets can be applied to the selected actor. Model import settings are staged with Apply / Revert, asset context menus can regenerate thumbnails, material asset details edit shared MaterialAsset fields, and file asset deletion moves sources/generated artifacts into assets/.trash/.
• 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.
• Brush authoring — ActorKind::Brush + BrushDesc stores persisted convex blockout faces and hydrates active brushes into generated mesh children. See brushes.md.
• Draw Brush — B, toolbar pencil, or command brush.draw enters a floor-polygon draw mode. LMB places snapped points, Backspace removes the last point, Enter creates an additive prism brush through history, and Esc/right-click cancels.
• Brush edit modes — with a brush selected, 1/2/3/4 enter vertex, edge, face, and clip element modes. Element modes show brush handles in the viewport, own LMB picking, support Shift multi-select, show a mode badge, and Esc returns to object mode. Vertex/edge/face selections can be dragged on the viewport floor plane and commit undoable SetBrush edits; clip mode is a preview/selection mode until CSG split support lands.
• 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 live on the actor MaterialDesc; static mesh slot material refs are source/default selectors, and 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 an Add Component footer (actor_inspector) that expands an inline search shelf above the button; 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. The Add Component shelf is registry-driven with persistent search, category groups, descriptions, hydration hints, duplicate/conflict disabled states, and recommendation hints. StaticMeshRenderer uses concept-style slot cards with model thumbnails, imported mesh/source-material selectors, visibility, and shadow flags. Actor material authoring lives in the Authoring Material component, whose texture refs use Asset Browser picker/drop controls. Empty source 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): focuses the filter on open, selects the first filtered command, supports arrow-key selection and Enter to run. Commands include scene.reset_lighting, brush.draw, rendering.create_volume, rendering.select_volumes_at_camera, rendering.focus_active_volumes, selection.group, selection.focus, selection.reset_transform, and play commands.
• Editor input routing gives egui text fields first claim on keyboard input. Viewport shortcut keys require viewport pointer focus and are suspended while RMB/MMB camera navigation is active.
• 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. Viewport options include actor icon size and transform gizmo size sliders.
• 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, generated mesh child resolved to its authored actor, actor root icon, or visualizer hit, with actor icons preferred when clicked over meshes; 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.