Build production-ready editor authoring workflows
CI / Format, lint, test, build (push) Waiting to run

This commit is contained in:
Rbanh committed 2026-07-11 12:41:04 -04:00
1 parent cc1fa6ea3b
commit 0553a85220
163 files changed
+34547 -1565

No files matched your search

+29 -12
View File
@@ -12,6 +12,14 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| [debt-audit.md](debt-audit.md) | Zero-debt phase gates and remaining items |
| [rendering.md](rendering.md) | GI modes, post-process volumes, presets, post FX assets |
| [brushes.md](brushes.md) | Brush authoring schema, hydration behavior, and MVP limits |
| [operator-regression-testing.md](operator-regression-testing.md) | Shared modal-tool commit/cancel/dirty/helper/undo invariants |
| [session-recovery.md](session-recovery.md) | Versioned restart state, clean/crash behavior, and privacy boundary |
| [project-launcher.md](project-launcher.md) | Pre-engine project selection, manifest identity, recents, and sandbox contract |
| [build-and-package.md](build-and-package.md) | Non-blocking editor builds, headless profiles, runtime output, and metadata |
| [multi-scene-composition.md](multi-scene-composition.md) | Scene tabs, stable subscene references, ownership, validation, and recovery |
| [prefab-authoring.md](prefab-authoring.md) | Stable nested overrides, source Apply/conflicts, variants, unpacking, and local conversion |
| [audio-authoring.md](audio-authoring.md) | Audio clip placement, source/listener controls, audition, buses, runtime parity, and validation |
| [animation-authoring.md](animation-authoring.md) | glTF rig/clip import, stable controller states, preview, runtime API, and validation |
## Subsystems (code → doc)
@@ -19,19 +27,26 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|-------------|----------------|-----|
| `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 |
| `scene/` | Level I/O, tabs, composition materialization, schema, viewport render-target setup | architecture.md, multi-scene-composition.md, ADR 0026 |
| `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 |
| `play/audio_preview.rs` / `game::audio` | Non-dirty editor audition and authored runtime playback/bus adapter | audio-authoring.md, ADR 0030 |
| `assets/animation.rs` / `ui/animation_inspector.rs` / `game::animation` | Generated animation manifests, controller authoring/preview, and runtime state adapter | animation-authoring.md, ADR 0031 |
| `assets/` | Catalog, asset DB, static mesh artifacts, `thumbnails/`, `materials.rs`, prefab overrides v2 | this file (below), prefab-authoring.md, ADR 0017, ADR 0027 |
| `shared::prefab_overrides` | Versioned stable override schema and editor-independent runtime application | prefab-authoring.md, ADR 0027 |
| `project/` | Workspace, settings UI, user prefs, support diagnostics | roadmap Phase 1 |
| `project/session.rs` | Versioned XDG session document, clean marker, and safe resume | session-recovery.md, ADR 0024 |
| `project/diagnostics_bundle.rs` | Privacy-bounded transactional support report export | session-recovery.md, ADR 0024 |
| `project/launcher.rs` | Strict project inspection, CLI activation, recent filtering, and sandbox scaffolding | project-launcher.md, ADR 0025 |
| `ext/` | Command palette, BRP, game panel adapters | ADR 0007 |
| `ui/mod.rs` | Dock layout, unified viewport, menus | README controls |
| `ui/scene_tabs.rs` | Main-toolbar scene tabs and composition controls | multi-scene-composition.md, ADR 0026 |
| `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 |
| `operators.rs` / `operators/test_harness.rs` | Operator lifecycle/status bridge and reusable regression invariants | operator-regression-testing.md, BS-JD-502 |
| `ext/game_inspector.rs` | Game-registered inspector sections | Phase 6 |
## Design intentions (stable)
@@ -41,16 +56,17 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
- **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/`. Before thumbnail loading, glTF sources preflight local external buffers/images and show a stable non-retryable failure state when a dependency is missing instead of repeatedly invoking the asset loader.
- **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. **Audio** accepts Bevy-supported Ogg/Vorbis and Speex (`.ogg`, `.oga`, `.spx`), WAV, MP3, and FLAC clips under `assets/audio/`, with a dedicated filter, waveform icon, format/file details, and stable registry-backed references that retain a runtime source path. 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/`. Before thumbnail loading, glTF sources preflight local external buffers/images and show a stable non-retryable failure state when a dependency is missing instead of repeatedly invoking the asset loader.
- **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.
- **Animation authoring** — glTF/GLB imports generate UUID-keyed rig/clip manifests and expandable skeleton/clip shelves. Clip drag creates an animated actor or adds one exact-signature-compatible state to a selected imported model through typed history. `AnimationControllerDesc` exposes named states, ranges, loop/speed, default/crossfade, and non-dirty runtime-backed preview; project validation resolves the same stable refs and blocks animated/skinned FBX with conversion guidance. Production acceptance remains open in Gitea #46. See [animation-authoring.md](animation-authoring.md) and [ADR 0031](../adr/0031-animation-authoring-runtime-contract.md).
- **Brush authoring** — `ActorKind::Brush + BrushDesc` stores persisted convex blockout faces, validates authored geometry in the inspector and Window → Brush Diagnostics, and hydrates active valid brushes into generated mesh children. See [brushes.md](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 locks the outline for height editing, mouse up/down adjusts height, and Enter/LMB creates additive prism brushes through history. Esc/right-click cancels. Simple concave outlines decompose into convex brush parts; self-intersections remain blocked.
- **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 use the standard `W`/`E`/`R` gizmo at the element pivot and commit undoable `SetBrush` edits. Clip previews a bounds-based half-brush and commits with Enter; command-palette intersect, convex merge, and subtract operations use the same preview/commit lifecycle for conservative cuboid/prism blockout.
- **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.
- **Prefab authoring** — shared `PrefabOverrides` targets generated actors by nested anchor chain plus stable `ActorId`, and applies reflected property/component plus same-layer structural operations in editor and game hydration. The editor supports scoped Revert and transactional **Apply to source** with three-way conflict checks, exact-file undo guards, and recoverable changed/broken/conflict states. `HydratedPrefabMember` keeps generated content out of owner serialization; linked-root saves retain local structure as variants. **Unpack Layer** preserves nested links, while **Convert to Local** recursively removes them. See [prefab-authoring.md](prefab-authoring.md) and [ADR 0027](../adr/0027-stable-prefab-ownership-and-variants.md).
- **Visual language** uses a near-black industrial shell, a compact Blacksite identity mark, restrained amber actions/primary selection, cyan secondary selection, semantic status colors, stable grouped controls, and shared elevated viewport chips. Primary/secondary selection roles remain consistent across hierarchy rows, viewport x-ray shells/corner brackets, the selection HUD, and transform interactions. See [visual-language.md](visual-language.md).
- **Hierarchy** shows authored objects plus useful runtime context (`Player`, `PlayerCamera`, Project Sun). Ordinary runtime rows remain read-only; generated prefab rows expose override-aware inspection and same-layer remove/reparent actions while rejecting cross-instance/layer and composition-boundary drops. Locks prevent selection, gizmos, drag participation, structural targets, and mutating context actions. Authored reparenting preserves world placement and records parent/local-transform/manual-order changes as one undoable command.
- **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](rendering.md). **Window → Rendering** shows requested/effective active-camera stack, fallback reason, Solari eligibility, viewport GI badge, and volume HUD.
@@ -58,11 +74,12 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
- **Command palette** (`Ctrl+P`): opens centered, clears and focuses the filter, selects the first result, searches both human-facing labels and stable command IDs, and supports arrow-key selection and Enter to run. Commands include `scene.reset_lighting`, `brush.draw`, `brush.subtract`, `brush.intersect`, `brush.merge_convex`, `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.
- **Scene persistence and recovery** use transactional same-directory writes for authored scenes and bounded user-local recovery snapshots for dirty saved scenes. Recovery runs every 120 seconds by default, keeps five generations, never marks the scene clean, and appears as a status/File-menu restore or discard action when newer than the authored file. Restore leaves the original scene dirty until manually saved. See [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
- **Scene visualizers** expose actor root icons, colliders, lights, player spawns, gameplay markers, volumes, prefab/model anchors, Project Sun, and runtime player/camera markers without changing saved scene data. Spot lights show inner/outer cones and cameras show near/far frusta. Viewport options independently gate visualizer categories and include actor icon 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).
- **Viewport shading** (toolbar): **Lit** (default WYSIWYG), **Unlit** (base-color debug), **Colliders** (hide meshes, emphasize collider gizmos). The viewport combines active shading/render path in one bottom-right chip, draws a camera-relative X/Y/Z orientation widget, identifies the primary selection in a responsive top-right HUD, and previews asset placement with a pointer card, placement reticle, corner brackets, and highlighted drop boundary.
- **Hierarchy** sort modes (**Manual**, **Name**, **Type**) use stable tie-breakers so duplicate names (e.g. several `Pillar` rows) do not reorder on every click. Actor drags use the full remaining row width as an attach target, show a pointer-following action card, preserve world transforms, reject cycles, keep selected subtrees intact, auto-expand the new parent, and commit one undoable hierarchy command. **Manual** mode additionally exposes between-row reorder targets and the drag-only **Scene Root** unparent target.
- **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. The selection HUD reports the current overlapping-pick position, and additive selections use an amber primary plus cyan secondary treatment. All unlocked selected actors participate in the grouped transform gizmo and one undoable transform command.
- **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.
+91
View File
@@ -0,0 +1,91 @@
# Animation Authoring
Blacksite's first production animation path supports skinned glTF 2.0 models (`.gltf` and `.glb`).
It normalizes imported rig and clip metadata into generated manifests, keeps authored scene data
independent of Bevy's runtime graph/player components, and uses the same controller contract in
editor preview, PIE, and standalone builds.
## Import And Placement
Place animated sources under `assets/` and refresh or reimport them from the Asset Browser. The
registry writes `assets/animations/generated/<asset-id>.animation.ron` beside the existing static
mesh artifact. Expanding a model row shows:
- skeleton entries with joint count and signature summary;
- animation clips with duration and event count;
- mesh, material, and texture entries from the static import contract.
Skeleton rows are inspect-only. Dragging an animation clip into the viewport creates one
`ImportedModel` actor with a stable `ModelRef` and `AnimationControllerDesc` and selects it for
immediate inspection. When an imported-model actor is selected, the same drag assigns the clip as a
new controller state instead. Assignment is one undoable command and requires an exact
skeleton-signature match.
Skinned primitive rows are inspect-only because their vertex data requires the source skin
hierarchy. Their thumbnails render the complete source scene, and drag/place actions direct authors
to place the model or an animation clip instead of creating an invalid detached mesh.
## Controller Inspector
The Animation Controller component exposes the selected skeleton, default crossfade, named states,
default state, clip, loop, speed, and optional playback range. State IDs are gameplay keys and must
be non-empty and unique; labels are presentation only. Component add, remove, reset, copy, paste,
and property changes use typed editor history and participate in scene dirty tracking.
The Preview section selects a state, plays or pauses it, stops playback, and scrubs within the
authored range. Preview requests use the game runtime adapter and do not change the controller,
history, or scene dirty state. Entering PIE clears any paused edit-mode scrub so the authored
default state can run; leaving PIE clears transient playback while retaining authored data.
## Runtime API
Gameplay changes state by sending a validated request through `game::animation`:
```rust
game::animation::request_animation_state(
world,
game::animation::AnimationStateRequest::new(actor, "run").with_crossfade(0.15),
)?;
```
An omitted crossfade uses the controller default. Invalid actor or state requests return an error
and preserve current playback. If edited controller data cannot rebuild its runtime graph, the old
graph is stopped and cleared instead of continuing stale playback. `AnimationGraph`,
`AnimationPlayer`, transitions, preview state, and hydrated model roots are runtime-only and never
serialize into authored scenes.
## Stable Identity And Moves
`ModelRef`, skeleton references, and clip references carry the model registry UUID. Generated
artifacts are keyed by that UUID; source paths are cached resolution and repair hints. When one
model is moved or renamed on disk, catalog refresh reconciles it by its animation-manifest content
hash, preserves the UUID, and regenerates both manifests with the new source path. An identical copy
is not treated as a move while the original still exists. Ambiguous content matches intentionally
receive a new identity rather than silently binding the wrong asset.
Legacy path-only `ModelRef` values remain readable and use their cached path. Reassign or replace a
legacy model actor to opt it into stable move resolution.
Skeleton compatibility hashes the exact Bevy 0.19 glTF node-name segments and bind poses, including
whitespace and slash characters. The readable joint paths shown by the editor are deliberately not
used as identity. Animation-manifest schema v1 artifacts must be reimported to generate schema v2
signatures.
## Validation And Format Boundary
Interactive diagnostics and `cargo validate-levels` resolve registry UUIDs, generated manifests,
stable subasset IDs, source dependencies, default/state IDs, playback ranges, speeds, crossfades,
runtime format support, exact source-content fingerprints, and exact rig compatibility. Findings
identify the owning actor and controller property and include a repair action. Packaging includes
the same source files and generated artifacts checked by validation.
FBX remains supported for static model import only. An FBX containing skin deformers or animation
stacks emits a blocking diagnostic directing the author to convert it to glTF. Animation v1 does
not support one glTF asset containing animation channels under multiple top-level roots, because
Bevy creates a separate `AnimationPlayer` for each root. Split those rigs into separate assets or
export them beneath one common root. Animation v1 also does not provide implicit retargeting, blend
trees, a visual state graph, root motion, IK, or motion matching.
See [ADR 0031](../adr/0031-animation-authoring-runtime-contract.md) for the persistent/runtime
boundary and [the working implementation plan](../../.cursor/plans/animation_authoring_2026-07-11.plan.md)
for acceptance gates.
+47 -11
View File
@@ -20,7 +20,7 @@ Native-only dependencies (`rfd`, BRP HTTP) stay in `editor`. `settings`, `shared
| Plugin | Role |
|--------|------|
| `GamePlugin` | Shared runtime: rendering, player, sim schedule |
| `GamePlugin` | Shared runtime: rendering, player, sim schedule; standalone default-level bootstrap |
| `ProjectSettingsPlugin` | Load `assets/project.ron`, emit changes, sync `SimTuning` |
| `ProjectIoPlugin` | User prefs, workspace metadata, window title inputs |
| `EditorStatePlugin` | `EditorMode` (Edit/Play), `PlayPossession`, camera/input gating |
@@ -59,11 +59,41 @@ Workflow: run `cargo watch … build -p game_hot` in one terminal, `cargo run -p
Do not add egui or editor-only state to the `settings` crate.
## Scene Persistence And Recovery
`scene/scene_io.rs` owns authored scene extraction and user-facing save/load requests;
`scene/recovery.rs` owns transactional byte persistence and machine-local recovery generations.
The editor sets `GameSceneBootstrap::defer_default_level`, so `SceneIoPlugin` alone materializes
the startup document. A standalone `GamePlugin` instead attaches a schema-aware `DynamicWorldRoot`
for `ProjectSettings.default_level`; it never runs this automatic load inside the editor.
Serialization always rebuilds stripped hydration state before returning, including error paths.
Manual writes use same-directory temporary files plus sync/rename, while recovery snapshots live
under the user state directory and never clear scene dirty state. Newer recovery is discovered on
load and exposed through File menu restore/keep-copy/discard actions; it is never restored
automatically. Keeping a copy writes a separate transactional scene without changing the active
scene or retiring recovery.
The bounded in-session scene I/O event log feeds the Diagnostics window so a later status update
does not erase a save or recovery failure.
See [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
`project/session.rs` owns the independent versioned restart document under the user state
directory. It snapshots allowlisted paths, panel visibility, dock/hierarchy metadata, and camera
bookmarks, writes a running marker at startup, and records clean `AppExit`. Abnormal sessions do
not auto-open the prior scene; the explicit safe-resume prompt is the only path back. See
[ADR 0024](../adr/0024-versioned-editor-session-state.md).
`project/diagnostics_bundle.rs` exports a separate, transactional support report from an explicit
metadata allowlist. It summarizes build/renderer identity, project paths, dirty state, aggregate
validation, the prior crash boundary, and the bounded Scene I/O log without serializing ECS data,
asset contents, environment values, host identity, credentials, or operator state.
The active project root is a startup boundary because `AssetPlugin.file_path`, project settings,
the asset catalog, and the initial level must agree before editor systems initialize. The editor
currently starts in the repository project root. Cross-project selection and scaffolding belong in
the planned BS-JD-001 launcher before the main app is built; do not reintroduce in-process project
switching that only changes settings metadata while leaving the AssetServer on the old root.
the asset catalog, and the initial level must agree before editor systems initialize.
`project/launcher.rs` validates and activates explicit roots before the app exists, filters
user-local recents, and scaffolds only missing/empty sandbox destinations. The graphical BS-JD-001
chooser builds on this contract. Do not reintroduce in-process project switching that changes only
settings metadata while leaving `AssetServer` on the old root; see
[ADR 0025](../adr/0025-project-root-is-a-startup-boundary.md).
## Camera and viewport model
@@ -121,9 +151,9 @@ The egui layer lives under `crates/editor/src/ui/`:
| `diagnostics.rs` | Detailed stats (Window → Diagnostics, Asset Browser footer) |
| `layout.rs` | Dock layout RON persistence in `editor_prefs.ron` |
The Viewport fills the tab (no inline help text). Gizmo/grid/play controls sit on a semi-transparent overlay, and `G` hides editor-only overlays for a clean game view. A blue status bar prioritizes `SceneIo.status` feedback and also shows scene path/dirty state, mode, selection count, history, and the active operator. Long feedback is truncated responsively and available in a hover tooltip. Dock layout restores from `~/.config/bevy-fps/editor_prefs.ron` on startup; **View → Reset Layout** restores defaults.
The Viewport fills the tab (no inline help text). Gizmo/grid/play controls sit on a near-black semi-transparent overlay, and `G` hides editor-only overlays for a clean game view. The fixed dark status strip prioritizes `SceneIo.status` feedback and also shows scene path/dirty state, mode, selection count, history, and the active operator. Long feedback is truncated responsively and available in a hover tooltip. Dock layout restores from `~/.config/bevy-fps/editor_prefs.ron` on startup; **View → Reset Layout** restores defaults.
**Follow-up (Phase 4b):** hierarchy expand/collapse persistence, inspector search, and richer per-asset previews.
**Follow-up (Phase 4b):** inspector search and richer per-asset previews.
## PIE state machine
@@ -151,7 +181,7 @@ On play enter/exit the editor snapshots **player sim state only** (transform, ve
1. User edits entities with `LevelObject` + reflectable components from `shared`.
2. `EditorOnly` entities (cameras, helpers) are filtered from hierarchy and save; visualizer proxies can be picked but resolve back to source entities.
3. Player placement is stored as `PlayerSpawn`; the runtime `Player` is never serialized.
4. `SceneIo` writes native Bevy dynamic scenes under `assets/levels/`, routed through the Bevy-free `scene::document::SceneDocument` seam. The document layer preserves the current RON storage while exposing stable actor/component document concepts and patch vocabulary for tools.
4. `SceneIo` writes native Bevy dynamic scenes under `assets/levels/`, routed through `scene::document::SceneDocument`. The active tab is materialized in the ECS world; inactive tabs retain normalized authored snapshots and independent dirty/recovery state. `SceneComposition` resources reference validated project-relative subscenes by stable IDs, and runtime-only `ComposedSceneMember` ownership prevents child actors from being flattened into the owner save. See [multi-scene-composition.md](multi-scene-composition.md) and ADR 0026.
5. Hydration systems in `game` spawn meshes, colliders, lights, and static mesh renderer parts at runtime. Level-object roots are initialized with Bevy visibility hierarchy components before generated children are attached, so authoring `EditorVisibility` participates in normal visibility propagation. `ActorId` and `ComponentInstanceId` are the persisted identities; raw Bevy `Entity` IDs are runtime-only and must not become tool-facing document IDs.
6. Brush actors store authored convex geometry as `BrushDesc`; hydration rebuilds generated mesh children from those faces and strips the children before save.
@@ -172,8 +202,11 @@ User-facing actions route through the operator lifecycle in `operators.rs`: begi
commit, cancel, disabled reason, and status text. The first bridge wraps command-palette and queued
editor commands as immediate operators, while existing `EditorHistory` commands remain the undo
payload. Asset placement, mesh-subasset placement, texture apply, and material apply actions now
use immediate operators from `assets::operators`; modal tools should use the same status path as
they migrate.
use immediate operators from `assets::operators`; texture/material changes across a selection use
one `SetMaterialGroup` command. Draw Brush, brush CSG, clip, and element gizmo paths publish the
same preview/commit/cancel phases. `operators/test_harness.rs` verifies authored deltas, dirty
state, helper cleanup, undo grouping, and undo/redo restoration; see
[operator-regression-testing.md](operator-regression-testing.md).
PIE stop restores player simulation state only; authored `LevelObject` edits made during PIE remain in the scene.
@@ -192,7 +225,10 @@ PIE stop restores player simulation state only; authored `LevelObject` edits mad
| `history/` | Undo commands + plugin |
| `ui/` | egui dock shell |
Shared scene schema lives in `crates/scene` (stamp/migrate/validate on save, load, and CI).
Shared scene schema lives in the Bevy-free `crates/scene` crate (stamp/migrate/validate on save,
load, and CI). `game::schema_world_loader` is the runtime adapter that validates and unwraps the
schema envelope before Bevy deserializes versioned prefab assets; both game and editor install it
through `GamePlugin`.
## HDR / swapchain invariant
+62
View File
@@ -0,0 +1,62 @@
# Audio Authoring
Blacksite provides a complete scene-to-runtime audio loop for Bevy-supported Ogg/Vorbis and Speex,
WAV, MP3, and FLAC clips. Audio assets live under `assets/audio/`; the Asset Browser assigns a
stable registry ID plus the runtime project path used by standalone games and packages.
## Authoring Workflow
- Drag an audio clip into empty viewport space to create an `AudioSource` actor at the snapped drop
position. With an audio source selected, dropping another clip assigns it through one undoable
command.
- The Audio Source Inspector controls clip, gain, pitch, loop, autoplay, 2D/spatial blend,
attenuation distances/curve, and stable bus routing. **Audition** uses the editor camera as the
spatial listener; **Stop** ends it immediately.
- Add an Audio Listener component from the Audio category when a scene needs an explicit listener.
The highest-priority enabled listener wins; stable actor ID order is the deterministic fallback.
- Source/listener root icons and selected-only attenuation/listener gizmos can be hidden with the
Audio option in Viewport options.
Audition entities are `EditorOnly`. They are stopped on PIE entry, scene replacement, source
deletion, natural clip completion, or explicit Stop. Audition does not mutate the source descriptor,
push history, or mark the active scene dirty. The preview owns a transient listener that follows the
editor camera without replacing camera components, and a failed clip load stops with an editor
status message instead of leaving a silent preview active.
## Buses
**Edit -> Project Settings -> Audio Buses** edits the project bus graph. `master`, `music`, and `sfx`
are required stable IDs; labels, gain, and mute state are editable. Custom buses receive stable IDs,
route through a parent, and may be removed while unused. Apply/Save is disabled while the graph has
duplicate IDs, missing parents, cycles, invalid gain, or missing required buses.
Runtime code can change user/session mixer state through `game::audio::AudioBusRuntime` without
rewriting project settings. Effective gain includes the complete parent route. A muted parent mutes
all descendants.
## Runtime And PIE
`game::audio::GameAudioPlugin` derives Bevy `AudioPlayer`, sink, and `SpatialListener` state from the
authored descriptors. A continuous spatial blend uses equal-power 2D and spatial voices between the
endpoints; selected attenuation is applied from the effective listener position. Spatial backend
coordinates are normalized inside the authored audible radius, so left/right panning does not add a
second distance falloff on top of the Inspector curve. F6 pauses/resumes existing PIE voices, while
stopping PIE clears derived voices so the next session starts from the authored autoplay state.
The runtime exposes `play_authored_audio_source`, `stop_authored_audio_source`, and
`reset_authored_audio_runtime` for gameplay/session control. `AudioRuntimeDiagnostics` reports the
active CPAL backend, default output device, and compiled codec set without making headless content
validation depend on an audio device.
## Validation And Sample
Interactive validation, `cargo validate-levels`, and packaging share checks for:
- missing, unsafe, excluded, unreadable, or Git LFS pointer clips;
- unresolved clip identities and unsupported codec extensions;
- invalid gain, pitch, spatial blend, attenuation, listener ear gap, or bus references;
- invalid project bus graphs and tied highest-priority enabled listeners.
`assets/levels/audio_authoring_showcase.scn.ron` and
`assets/audio/editor_audition_tone.ogg` provide a small deterministic source/listener fixture for
save/load, audition, PIE, headless validation, and package smoke tests.
+14 -2
View File
@@ -104,13 +104,25 @@ External automation can enqueue the same names through the editor command queue
## CI / headless validation
Validate committed levels without the editor UI:
Validate committed levels and prefab dependency graphs without the editor UI:
```bash
cargo validate-levels
# JSON for CI, packaging, or external tools
cargo validate-levels --json
```
This runs `scene::validate_level_file` (schema migrate + **authoring-only** component check).
This runs the shared `scene::validate_project` report used by the editor Diagnostics window. It
validates authored levels and recursive prefab/composition graphs, emits an owner-attributed
dependency manifest, reports blocking content references, and exits nonzero on errors.
`--project <path>` validates another project root. The graph pass validates link paths, stable actor
identity, cycles, anchors, and override payloads without starting the editor. The same report scans
project settings and asset roots, registry/import dependencies, generated mesh manifests, material
and shader documents, post effects, brush geometry, collider dimensions, Git LFS hydration, and
platform requirements. Validation and packaging share one runtime-inclusion policy: hidden/editor
trees, source formats such as PSD/Blend, symlinks, and unreadable traversal are blocking when a
runtime dependency reaches them. `asset.git_lfs_object_missing` is blocking; run `git lfs pull` in
the project checkout and rerun validation before building a package.
```bash
cargo test -p shared
+77
View File
@@ -0,0 +1,77 @@
# Build and package
## Editor workflow
Open **Build > Build Package** or the **Build** panel. Select `development`, `qa`, or `release`, then
choose **Build** or **Build and Run**. Compilation and packaging run in the background and stream into
the panel. **Cancel** terminates the active packager/compiler process tree. **Reveal Output** opens
the last successful package directory. The editor refuses to start a package while any scene tab is
modified; save all tabs first. Closing the editor cancels and joins the build worker.
Every build validates before and after compilation. Blocking findings must be repaired through the
owning scene actor or asset. The final asset snapshot must remain unchanged while staging is
assembled; otherwise the build asks for a retry and leaves the previous package untouched.
## Headless workflow
```bash
cargo package-project --profile development
cargo package-project --profile qa
cargo package-project --profile release
# Validate/package another checkout
cargo package-project --project /path/to/project --profile release
```
`--skip-build --artifact /path/to/game` is reserved for package-pipeline tests or repackaging an
already-built matching Cargo artifact. Normal editor and CI workflows must not use it. Cargo JSON is
the authoritative executable location for ordinary builds, including custom target directories.
## Profiles and output
Profiles live in `assets/build_profiles/*.ron`. The editor's sandbox scaffold creates all three
standard profiles even though the engine Cargo workspace remains separate from that project root.
Output must use a dedicated `dist/<name>/` directory under a real, non-symlinked project `dist/`.
A non-empty destination is replaceable only when its `build-metadata.json` proves that the packager
owns it; profile typos therefore cannot prune source or unrelated user files. Runtime asset symlinks
and unreadable traversal entries are also rejected. The standard outputs are `dist/development`,
`dist/qa`, and `dist/release`; `dist/` is ignored by Git.
`development` uses the optimized non-LTO package profile and forces Forward GI in the packaged
settings for portable iteration. `qa` retains line tables and preserves the authored rendering
policy. `release` preserves authored rendering, uses thin LTO, and strips symbols. `dev` and
`hot-reload` Cargo features are editor iteration modes and are intentionally rejected by packaging.
Windows MSVC QA output also includes `blacksite.pdb`; Linux QA line tables remain embedded in the
binary. Profile-selected defaults must be regular `.scn.ron` scenes under `assets/levels/`, where the
shared validator audits their complete component dependency graph as well as schema/composition. The current native
layout supports desktop Linux and Windows targets; web, Android, iOS, and macOS application bundles
need dedicated platform packaging and are rejected instead of producing an incomplete output.
Each output contains:
- `blacksite` (`blacksite.exe` on Windows);
- `blacksite.pdb` for Windows MSVC QA profiles;
- runtime `assets/` with editor/recovery/source-only content excluded;
- `build-metadata.json` with the toolchain, commit/dirty state, profile inputs, and BLAKE3 content
hashes.
Files are assembled in an authenticated sibling staging directory copied from prior output, then
rehashed and promoted only after metadata and the content manifest are complete. Staging never shares
writable file inodes with the published package; Windows removal also clears read-only attributes only
inside authenticated owned work trees. A per-output OS lock blocks concurrent publishers. The next
run removes an owned interrupted staging tree and restores a verified prior backup; unknown lookalike
files/directories are left untouched and reported. A cancellation, validation error, or I/O failure
never publishes a partial package.
Run a package from its output directory so Bevy resolves the packaged `assets/` root:
```bash
cd dist/release
./blacksite
```
The standalone binary loads `default_level` from its packaged `assets/project.ron` through the same
schema-aware dynamic-scene loader used by runtime prefab assets. The editor leaves that authored
startup to `SceneIo`; its generated arena remains only as the failure fallback when the startup scene
cannot be loaded. Build and Run reports a clear host mismatch instead of trying to execute a
cross-compiled package for a different operating system or CPU architecture.
+49
View File
@@ -0,0 +1,49 @@
# Multi-Scene Tabs And Composition
Blacksite keeps scene-document controls at the right end of the existing main toolbar. Each tab has
its own path and dirty marker; **+** creates an untitled tab and **x** closes a tab with a
save/discard/cancel prompt when needed. **File > Open Scene...** opens another tab instead of
discarding the active document. Save and Save As affect the active tab, while project switching
offers to save every modified tab.
## Composition workflow
The **Composition** menu beside the tabs edits the active scene's persisted `SceneComposition`:
- **Add Subscene...** accepts a validated `.scn.ron` under the active project root.
- **Loaded** loads or unloads that reference from the active world.
- **Locked** routes every loaded actor through the hierarchy's read-only selection, gizmo, drag,
and mutation guards.
- **Focus** selects a loaded actor owned by the reference and frames it in the editor camera.
- Remove deletes only the reference; it never deletes the referenced scene file.
Composition edits mark only the owner tab dirty and participate in undo/redo. Loaded child actors
carry runtime-only ownership metadata and are excluded when the owner saves, so editing the
composition cannot flatten child content into the parent file. To edit a child scene, open it as
its own tab.
## Validation and PIE
References use stable scene/reference IDs and project-relative paths. Editor load and
`cargo validate-levels` recursively reject missing files, path escapes, duplicate IDs, and cycles
before replacing the active world. Hidden references remain validated even though they are not
loaded. Nested loaded scenes inherit a locked ancestor's read-only boundary.
The active world is the authoritative composition for PIE and viewport rendering. Switching tabs
is disabled during Play. The safe materialization boundary clears entity-edit undo history on tab
activation because current history commands contain runtime entity IDs; composition changes
themselves are stable-resource commands and remain undoable until the next tab activation.
## Recovery and migration
Every dirty saved tab receives its own bounded transactional recovery generations, including tabs
that are currently inactive. Untitled tabs must be saved once before automatic recovery can assign
them a durable scene path.
Legacy scenes need no manual migration. They receive a deterministic `legacy:<project path>` scene
identity in memory and write the current `SceneComposition` resource on the next normal save.
Project startup still opens the manifest's `default_level`; clean session recovery resumes only the
last active authored scene, not the full transient tab set.
See [ADR 0026](../adr/0026-stable-scene-composition-and-active-document.md) for the ownership and
materialization decision.
@@ -0,0 +1,54 @@
# Operator Regression Testing
Blacksite editor operators and modal tools must preserve the authored scene across preview,
commit, cancellation, validation failure, and undo/redo. Tests share
`operators::test_harness::OperatorInvariantHarness` so a new tool proves the same contract instead
of inventing local assertions.
## Required invariants
Every production operator test must cover the paths it exposes:
| Path | Required proof |
|------|----------------|
| Commit | Expected authored entity delta, exact undo-group delta, dirty state, committed phase |
| Cancel or commit failure | No authored entity delta, no new history, prior dirty state, canceled phase |
| Blocked start | Commit closure never runs; authored state, history, and dirty state are unchanged |
| Preview helpers | No helper component remains after commit or cancel |
| Undoable commit | `assert_undo_redo_round_trip` restores both initial and committed projections |
| Continuous edit | The entire interaction creates one history command, not one per frame or target |
The harness intentionally fails with the invariant name in the assertion message. Tests may add
domain assertions, but should not replace these shared lifecycle checks.
## Adding a tool test
1. Build a minimal `World` with `ActiveOperator`, `EditorHistory`, and `SceneIo`. Add tool-specific
selection/resources and `SelectedEntity` when history helpers update selection.
2. Capture `OperatorInvariantHarness` immediately before starting the operation.
3. Run the real operator entry point or the same production commit/cancel function used by its
input system.
4. Call `assert_committed`, `assert_canceled`, or `assert_blocked` with the expected authored and
undo deltas.
5. For helpers, call `assert_no_helpers::<ToolHelper>`. For undoable work, project the meaningful
state through `assert_undo_redo_round_trip`.
Do not satisfy a lifecycle test by constructing an `EditorCommand` and checking only its label.
The test must mutate a world and prove restoration.
## Current coverage
| Workflow | Coverage |
|----------|----------|
| Generic `EditorOperator` | Commit cleanup, commit failure rollback, blocked no-op |
| Asset placement | Commit, dirty state, single undo, authored spawn round trip |
| Sub-asset placement | Missing dependency commit failure leaves no side effects |
| Texture/material assignment | Multi-actor grouped undo; missing material failure; empty-selection block |
| Draw Brush | Full modal-state cancel; decomposed multi-brush grouped commit and round trip |
| Brush CSG | Pending-preview cancel; merge commit/deletion grouped round trip |
| Brush clip and element gizmo | Clip grouped geometry round trip; Escape rollback and helper cleanup |
| Transform gizmo finalization | Multi-target continuous edit grouped into one undo command |
Terrain strokes and physics-settle sessions are roadmap tools, not current production operators.
Their implementation tickets must add harness fixtures before those tools can pass their own exit
gates; Gitea issue BS-JD-502 remains the umbrella until that coverage exists.
+156
View File
@@ -0,0 +1,156 @@
# Prefab Authoring
Blacksite prefabs are schema-versioned `.scn.ron` documents under `assets/`. A placed prefab stays
linked through its authored `PrefabInstance`; entities loaded from the source are runtime-owned
members and are never flattened into the scene that contains the instance.
## Create and place a prefab
1. Select one or more authored actor roots.
2. Choose **File > Save Selection As Prefab...** and save under `assets/prefabs/`.
3. Place the resulting prefab from the Asset Browser. The placed root exposes a **Prefab Instance**
component with its stable asset ID and source path.
Saving expands the selected authored hierarchy. Hydrated prefab members and composed-scene members
are excluded from the prefab file. Missing or duplicate authored `ActorId` values are repaired before
a direct prefab save; a failed save restores the original in-memory IDs.
## Stable identity and layering
An override target is not a runtime `Entity` or display name. `PrefabActorPath` stores the target
actor's stable `ActorId` plus the `ActorId` chain of every nested prefab anchor needed to reach it.
Two nested copies may therefore contain the same source actor IDs without sharing override identity.
The hydrated result is resolved from least to most specific:
1. the source prefab document;
2. each nested link's own overrides;
3. the containing variant document and its authored local structure;
4. the overrides on the placed instance.
The override schema and runtime application live in `crates/shared`, so standalone and packaged game
builds apply the same data without loading the editor plugin.
## Instance overrides
Select a generated prefab member to edit its override layer. The current inspector exposes:
- **Property overrides** for Transform position, rotation, and scale, plus Material base color,
metallic, and roughness.
- **Component overrides** for adding, replacing, or removing `MaterialDesc`, plus visibility on
direct or nested generated actors.
- **Structural overrides** for removing a source actor or reparenting generated actors within the
same instance layer. Hierarchy **Unparent override** writes the same stable structural operation.
These edits update `PrefabInstance.overrides_ron`; they do not immediately edit the source asset.
Use **Revert** at field scope, **Revert component overrides**, **Revert actor overrides**, or
**Revert all** at instance scope. Each edit/revert is one undoable prefab-state command.
Legacy root transform/material data and name-keyed visibility data still load. Current operations
use the full stable `PrefabActorPath`, so repeated leaf `ActorId` values in sibling nested instances
remain distinct.
## Apply to source
**Apply to source** is an explicit source-asset write, not another name for storing an instance
override. It is available for a field, component, generated actor, or all operations on the placed
instance.
For a direct target, Blacksite patches the linked source document. For a target reached through a
nested `instance_chain`, it moves the operation into the immediate nested link recorded by that
source layer. This preserves the base/variant boundary instead of unexpectedly mutating the deepest
leaf prefab.
Before writing, Blacksite compares the recorded base with the current source value, serializes the
patched document, validates the complete dependency graph, and performs an atomic same-directory
write. The history entry stores exact before/after source bytes and the old/new instance state.
Undo or redo is blocked if another process changed the source after the command; Blacksite reports
the block instead of overwriting that external work.
## Source status and conflict recovery
The **Prefab Instance** card combines hydration state, transitive graph validation, recorded source
revision, stable target resolution, and base-value checks:
- **Loading source** - wait for hydration before unpacking or editing generated targets.
- **Ready** - the graph is valid, the recorded revision matches, and overrides resolve cleanly.
- **Base not tracked** - a legacy instance has no revision. **Accept current base** records it without
changing override values.
- **Base changed** - the source graph changed but no semantic conflict was found. Inspect the result,
then **Accept current base** or relink.
- **Override conflict** - a target disappeared or a source property/component/parent changed from the
base captured by an override. **Keep overrides** rebases the stored bases, while **Take source**
removes only semantically conflicting operations. **Remove stale overrides** cleans unresolved
legacy visibility keys; **Relink...** selects another valid source.
- **Broken source** - a source is missing or its graph/path/identity validation failed. Hydrated
generated state is removed, the authored anchor remains repairable, and **Retry source** or
**Relink source...** starts one clean hydration attempt.
- **Invalid overrides** - the serialized override payload is malformed. **Discard invalid data**
resets that payload explicitly.
Accept, keep/take, stale cleanup, relink, and source Apply participate in undo/redo according to
their scope. Reload and Retry refresh hydration without creating an authoring history entry.
## Local children and hierarchy overrides
Authored local actors may be created or reparented below a linked instance root or another authored
local actor. Nested linked prefabs may be placed there as well. Those entries remain normal
scene-owned content: they can be selected, transformed, reordered, saved, and undone.
Rows carrying `HydratedPrefabMember` are generated context. Their Transform/Material fields are
edited through overrides rather than direct source mutation. Generated actors may be removed or
reparented only within the same owning instance and nested layer. Cross-instance, cross-layer, and
composition-boundary drops are rejected. Between-row ordering of generated siblings is not modeled,
and authored local children cannot yet attach directly to a generated source member.
## Save a variant
Variants use normal linked-prefab composition rather than a separate asset type:
1. Start with a linked prefab instance and author its instance override layer.
2. Add local children or nested prefab instances below its root/local structure.
3. Select the linked root and choose **Create Variant...** in the Prefab Instance inspector, or use
**File > Save Selection As Prefab...**.
The saved prefab contains the base `PrefabInstance` link, its stable overrides, and local authored
structure. Hydrated base members are excluded. Placing the variant therefore evaluates base, nested
layers, variant, and placed-instance overrides in order without duplicating generated actors.
Applying an override on a nested source actor writes it to the immediate link in the variant/source
document; open the leaf prefab itself when the intended change should affect every use of that leaf.
## Unpack and convert
**Unpack Layer** removes only the selected outer `PrefabInstance`/`PrefabRef` ownership link and
turns its hydrated members into authored local actors. Nested prefab instances remain linked, and
outer overrides targeting them are folded into those retained links transactionally. Undo restores
the outer link and removes the local copy; redo restores the captured authored result.
**Convert to Local** recursively removes the selected outer link and every generated or authored
local nested prefab link below it. Every converted hydrated source actor receives a fresh local
`ActorId`, including actors from different nested documents that originally reused an ID. The
operation is one undo step and redo uses captured snapshots, so it does not depend on the source
files still being present.
## Validation and remaining acceptance
Prefab save, editor load, project inspection, and `cargo validate-levels` recursively inspect linked
`PrefabInstance` components. Validation rejects missing sources, unsafe paths (including symlink
escapes), non-`.scn.ron` sources, cycles (including path aliases), empty asset IDs, incomplete link
anchors, malformed outer or inner override payloads, missing authored `ActorId` values, and
duplicate IDs within a document. The committed `assets/prefabs/example_base.scn.ron` ->
`example_nested.scn.ron` -> `example_variant.scn.ron` chain is the healthy production-format
fixture for this gate.
The shared format can apply registered reflected property/component operations, but the current
authoring UI exposes the Transform and Material fields/components listed above. Generated sibling
ordering and direct local-child attachment to a generated member are not yet override operations.
Variants remain ordinary composed prefab documents rather than a separately named asset type.
Production acceptance closed in Gitea issue
[#43](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/43) after the
complete workspace suite, recursive headless validation, packaged release startup, and live editor
placement/inspection regression passed against the committed fixture chain.
See [ADR 0027](../adr/0027-stable-prefab-ownership-and-variants.md) for the ownership, stable identity,
layering, and source-write contract.
+63
View File
@@ -0,0 +1,63 @@
# Project Launcher And Sandboxes
Blacksite treats the project root as a pre-engine startup choice. The root must contain a valid
`assets/project.ron`; its default level must be project-relative, exist, and pass the shared scene
validator before the editor constructs `AssetPlugin` or loads project content.
Use an explicit root from the command line:
```bash
cargo run -p editor --features dev -- --project /path/to/project
cargo run -p editor --bin project_launcher --features dev
```
Omitting `--project` preserves direct-open behavior for the current working directory. Invalid or
unknown arguments fail before GPU initialization with an actionable terminal error.
## Manifest identity
New manifests include:
- `project_id`: stable UUID or repository-owned identifier;
- `project_kind`: `Game` or `Sandbox`;
- `template_version`: scaffold/template compatibility version;
- `capabilities`: forward-compatible feature tags;
- `default_level`: regular `.scn.ron` initial authored scene under `assets/levels/`.
New manifests include the `audio` capability, `assets/audio` asset root, and the validated Master,
Music, and SFX bus graph. Bus references use the stable IDs `master`, `music`, and `sfx`; labels are
presentation only.
Older manifests remain readable through serde defaults. The launcher uses a non-persisted legacy
path identity when an old manifest has no `project_id`.
## Sandbox contract
Sandbox creation only accepts a missing or empty destination. It creates the standard audio,
levels, materials, meshes, models, rendering, shader, texture, registry, and trash directories; a
schema-current empty `assets/levels/main.scn.ron`; a transactional sandbox manifest; and
development, QA, and release profiles under `assets/build_profiles/` targeting that scene. The
project remains content-only: editor packaging runs from the installed engine workspace while
passing this project root explicitly. Scaffolding never merges into a non-empty directory.
Recent projects remain user-local. Missing, invalid, and duplicate roots are removed from launcher
presentation, and the last scene is shown only when it still exists under that project root.
## Switching and desktop launch
**File > Switch Project...** writes a clean editor session, starts the Project Browser as an
independent process, and exits. Opening a recent or browsed project performs the reverse handoff:
the browser exits only after a new editor process has been accepted by the user's service manager.
This keeps renderer, asset server, import registry, and project settings rooted consistently.
On the supported Linux workstation, the **Blacksite Editor** desktop entry provides an **Open
Project Browser** action. Its wrapper builds both editor binaries into the shared target directory,
shows the normal startup splash, avoids duplicate browser processes, and preserves the Wayland,
session-bus, graphics, and XDG environment required by the detached process.
The browser's **New Sandbox** workflow requires a missing or empty folder and a non-empty name.
Creation failures remain in the browser as status text; a successful scaffold is validated and
opened through the same process handoff as an existing project.
See [ADR 0025](../adr/0025-project-root-is-a-startup-boundary.md) for why project switching must
cross a process boundary.
+24 -7
View File
@@ -2,7 +2,7 @@
Phased work for the in-process editor (`crates/editor`). Status reflects the current codebase; update this file when closing a phase.
## Production editor program (complete — P5 partial)
## Production editor program (P5 cleanup remaining)
**Goal:** Zero-debt authoring loop — hydration modules, mandatory `ActorKind`, actor inspector only, schema v2 migrations. See [ADR 0009–0012](../adr/0009-authoring-vs-hydrated.md) and `.cursor/plans/editor_rendering_and_ux_*.plan.md`.
@@ -11,9 +11,9 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
| P0 Hydration + lighting | **Done** | `shared/hydration/*`, strip-on-save, schema v2 migrate, live ambient/sun, Rendering Diagnostics |
| P1 Actor model | **Done** | `ActorKind`, `validate_actor`, history snapshots, ADRs 0009–0012 |
| P2 Actor inspector | **Done** | `ui/actor_inspector/`; removed `DefaultInspectorConfigPlugin` + ECS dump on Inspector tab |
| P3 Hierarchy tree + sibling order | **Done** | `HierarchySiblingIndex`, tree outliner, DnD reorder, visibility/lock |
| P3 Hierarchy tree + sibling order | **Done** | `HierarchySiblingIndex`, tree outliner, full-row DnD attach/reorder/root, world-transform preservation, cycle guards, visibility/lock |
| P4 Viewport modes | **Done** | Lit / Unlit / Collider toolbar, light gizmo overlays, Tab pick cycle |
| P5 Assets + prefabs | **Partial** | `MaterialAsset`, `assets/thumbnails/sources/`; prefab overrides v1; delete legacy `fbx_preview` when cache fully unified |
| P5 Assets + prefabs | **Partial** | Prefab v2 is production-accepted with stable nested identity, scoped/runtime overrides, committed base/nested/variant fixtures, source Apply/conflict recovery, and local conversion; legacy `fbx_preview` cleanup remains |
| P6 Extensibility + CI | **Done** | `ActorInspectorSection`, palette commands, BRP policy, hydration/scene CI |
| P7 Docs + debt audit | **Done** | ADRs 0009–0012, [debt-audit.md](debt-audit.md), CI matrix |
@@ -39,7 +39,7 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
| `ProjectWorkspace` resource | Done | Root, settings path, dirty flags |
| User prefs (`~/.config/bevy-fps/editor_prefs.ron`) | Done | Recent levels, load on startup |
| Window title from project + scene | Done | `project_io::window_title` |
| Project launcher and scaffolding | Planned | BS-JD-001; project selection must happen before AssetServer startup, so the former in-process New/Open menu was removed |
| Project launcher and scaffolding | Done | Project Browser validates/scaffolds before AssetServer startup; `--project`, recent projects, and clean process handoff preserve the startup boundary |
| Dock layout persistence | Done | RON in `editor_prefs.ron`; View → Reset Layout |
## Phase 2 — Viewport excellence
@@ -100,13 +100,13 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
| Item | Status | Notes |
|------|--------|-------|
| Dark pro theme + Phosphor icons | Done | `ui/theme.rs`, `ui/fonts.rs`, high-contrast selection states, overlay toolbars |
| Blacksite dark visual system + Phosphor icons | Done | Near-black shell, Blacksite toolbar mark, semantic amber/cyan states, `ui/theme.rs`, `ui/fonts.rs`, overlay toolbars |
| Fixed status bar | Done | Replaces Status dock tab; exposes scene I/O and operator feedback alongside scene/mode/selection/history |
| Viewport overlay toolbar | Done | Gizmo/grid/focus/options/game-view toggle (play moved to main toolbar) |
| Main toolbar transport | Done | Centered Play/Pause/Stop/Eject; taller bar (~52px) |
| Pause in PIE | Done | `PlayPaused` freezes sim while staying in Play (`F6`) |
| Dock layout persistence | Done | `ui/layout.rs` + `UserPreferences.dock_layout` |
| Hierarchy tree + type icons | Partial | Authored + generated/runtime rows with icons; expand/collapse state still future |
| Hierarchy tree + type icons | Done | Authored + generated/runtime rows, persistent expansion, full-row attach targets, subtree-safe multi-drag, transform-preserving undo |
| Actor inspector (authoring-only) | Done | Transform + `LightDesc`/`MaterialDesc`/…; no bevy_inspector dump |
| Inspector component headers | Done | Header + Transform + component cards + Add Component footer |
| Asset browser project/file views | Done | Folder tree, breadcrumb, search/filter/sort, grid/list, details pane, texture + model thumbnails |
@@ -121,7 +121,7 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
| Model import formats | Done | glTF/GLB + FBX (binary); `.fbm` sidecar copy on import |
| Thumbnails | Done | Textures via asset load; glTF albedo fast-path; FBX/untextured models via offscreen studio |
| Import settings per asset | Done | Scale/collider/LOD in registry + details pane |
| Prefab workflow | Partial | `PrefabInstance`, save-as-prefab, unpack; **Revert Transform** v1 in inspector; full override apply/revert future |
| Prefab workflow | Done | Shared stable nested property/component/structural overrides, recursive validation, committed variant fixtures, transactional source Apply, conflict recovery, and undoable outer unpack/recursive local conversion passed headless, packaged-runtime, and live editor acceptance in Gitea #43 |
## Phase 6 — Extensibility
@@ -137,6 +137,23 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
| BRP authoring-only policy | Done | [brp.md](brp.md) |
| CI: `shared` hydration, `scene` migration + allowlist | Done | See `.github/workflows/ci.yml` |
## Production Readiness Program
The live program is tracked by Gitea
[`#1`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/1),
with implementation sequencing in
`.cursor/plans/blacksite_production_readiness_2026-07-10.plan.md`.
| Milestone | Exit condition | Status |
|-----------|----------------|--------|
| M6 Reliability, recovery, and project workflow | Transactional save/recovery, stable sessions, project launcher, hardened hierarchy/prefabs, multi-scene composition | Implementation complete; all six scoped issues are closed after prefab #43 passed workspace, headless, packaged-runtime, and live editor acceptance |
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44, #45, and #47 are complete. Audio passed automated, headless, live editor/PIE, and packaged-runtime acceptance. Remaining scoped work is animation #46, navigation #48, source-control safety #49, and final readiness gate #50 |
Production readiness is not inferred from feature count. Gitea
[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50)
requires representative-project workflows, soak and performance evidence, headless validation,
packaging, recovery QA, first-hour signoff, and no open P0 blocker.
## Documentation maintenance
When you ship editor behavior changes:
+38
View File
@@ -0,0 +1,38 @@
# Editor Session Recovery
Blacksite stores restart metadata in the user state directory, separate from project assets and
source-controlled settings:
- `$XDG_STATE_HOME/blacksite-editor/session.ron`, or
- `~/.local/state/blacksite-editor/session.ron` when `XDG_STATE_HOME` is unset.
The file uses schema v1 and is written transactionally. It contains project and scene paths, dock
and hierarchy metadata, non-destructive panel visibility, finite viewport camera bookmarks, and a
clean-shutdown marker. It never contains scene contents, unsaved tool previews, environment values,
or credentials.
## Restart behavior
- **Clean shutdown:** the last authored scene and non-destructive UI state are restored.
- **Abnormal shutdown:** the editor opens its normal safe scene and displays **Recover Editor
Session**. **Resume Last Scene** opens only the previous authored scene. **Continue Safe** keeps
the startup scene. Modal tools and dirty preview state are never restored.
- Dirty scene data remains governed by the independent scene recovery workflow in
[ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
An unknown newer session schema is ignored safely. Legacy unversioned session documents migrate to
v1 after finite camera bookmark validation.
## Diagnostic bundles
**Window → Diagnostics → Export Diagnostic Bundle** writes a timestamped RON report under
`$XDG_STATE_HOME/blacksite-editor/diagnostics` or
`~/.local/state/blacksite-editor/diagnostics`. The write uses the same transactional replace
primitive as session and scene recovery data.
The v1 report allowlists editor and Bevy versions, target OS/architecture and build profile,
renderer adapter/backend/driver identity, project and active-scene paths, dirty flags, aggregate
level/brush validation counts, the prior-abnormal-shutdown flag, and up to 32 bounded Scene I/O
events. It excludes ECS and scene payloads, asset contents, environment values, host/user identity,
credentials, access tokens, camera transforms, and modal operator state. Review the plain-text RON
file before sharing it when project paths are sensitive.
+79
View File
@@ -0,0 +1,79 @@
# Editor Visual Language
Blacksite's editor UI is a dense production tool. Its visual system prioritizes scan speed,
stable controls, viewport legibility, and unambiguous editing state over decorative surfaces.
## Palette Roles
- Near-black neutral surfaces separate canvas, panels, controls, and elevated popovers without a
light-gray cast or single-hue tint.
- Amber is the Blacksite action accent: active tools, the primary selection, warnings, and
rendering paths that need attention.
- Cyan identifies secondary selections, links, and neutral viewport information.
- Red, green, and blue are reserved for the X, Y, and Z axes across transform gizmos, the world
grid, and the viewport orientation widget.
- Green and red communicate success/running and error/blocked states. They are not decorative.
## Editor Chrome
- A compact Blacksite mark and amber signal line identify the tool without turning the workspace
into a branded landing surface; squared controls and tight radii reinforce the industrial tone.
- Menus, the grouped creation/file toolbar, centered transport controls, dock tabs, and the status
strip keep stable dimensions so mode changes do not shift the workspace.
- Controls use familiar symbols with hover labels. Persistent text is reserved for state, values,
selection identity, and task-specific feedback.
- Dock tabs use an amber active edge, while splitters and panel borders stay neutral until hovered
or dragged.
- Popovers and viewport chips share one elevated surface, border, corner radius, and shadow.
## Viewport Language
- The top-left toolbar groups transform, coordinate space, shading, grid/snap, visualizer, focus,
and display controls.
- The top-right selection chip identifies the active object, selection count, and overlapping-pick
position. It moves below the toolbar when the viewport is narrow.
- The bottom-right orientation widget and combined shading/render-path chip provide camera and
render context without covering scene content.
- Dragging an asset over the viewport produces an amber placement boundary and compact placement
card, pointer reticle, and corner brackets before the drop is committed.
- Grid lines use minor/major weights. The world X and Z axes retain their gizmo colors.
## Selection And Gizmos
- The first selected object is primary: amber x-ray rim and corner brackets, hierarchy edge, and
selection HUD identity.
- Additional selected objects are secondary: cyan rim, brackets, and hierarchy edge.
- All unlocked authored objects in a multi-selection receive grouped transform-gizmo targets; a
single interaction is captured as one undoable group transform.
- Transform gizmos use restrained X/Y/Z colors, an amber interaction highlight, larger stable
screen size, and translation snapping synchronized with the viewport snap toggle and increment.
- Brush vertex, edge, and face modes reuse the same palette and enlarge active element handles.
Face mode outlines the selected face instead of showing only a center point.
## Drag And Drop
- Drag previews follow the pointer and name both the payload and pending action; they never rely on
cursor shape alone.
- Hierarchy rows expose their full remaining width as attach targets. Amber means attach, cyan
means root/reorder, and red means the requested hierarchy would be invalid.
- Reparenting preserves world placement, keeps selected subtrees intact, expands the new parent,
and records parent, sibling order, and local transform in one undoable command.
- Manual hierarchy sort exposes between-row insertion targets; semantic Name and Type sorts expose
parenting without pretending a manual reorder will remain visible.
## Visualizers
- Visualizers preserve semantic category colors while selected objects receive stronger emphasis.
- Camera visualizers include near and far frustum planes plus a forward vector.
- Spot lights show inner and outer cones; point lights, directional lights, colliders, spawns,
gameplay markers, volumes, prefab/model anchors, and runtime helpers remain independently
toggleable.
- Editor-only visualizers and selection helpers never enter saved scene data.
## Maintenance Rules
- Add shared colors and surface frames in `ui/theme.rs`; do not introduce local panel palettes
unless the color has domain meaning.
- Keep selection semantics consistent across the viewport, hierarchy, inspector, and status bar.
- New viewport overlays must adapt before they overlap existing controls at narrow widths.
- Visual polish must preserve picking, undo/redo, clean game view, and scene serialization behavior.