Build production-ready editor authoring workflows
CI / Format, lint, test, build (push) Waiting to run
CI / Format, lint, test, build (push) Waiting to run
This commit is contained in:
1 parent
cc1fa6ea3b
commit
0553a85220
163 files changed
+34547
-1565
No files matched your search
+29
-12
@@ -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.
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user