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

+20
View File
@@ -37,6 +37,15 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [0020](adr/0020-jackdaw-inspired-editor-roadmap.md) | Jackdaw-inspired roadmap source policy and attribution requirements |
| [0021](adr/0021-brush-authoring-schema.md) | Brush authoring schema and hydration contract |
| [0022](adr/0022-bevy-0-19-upgrade.md) | Bevy 0.19 / Avian 0.7 upgrade and compatibility patches |
| [0023](adr/0023-transactional-scene-persistence-and-recovery.md) | Atomic scene writes, user-local recovery snapshots, and restore/discard policy |
| [0024](adr/0024-versioned-editor-session-state.md) | Versioned machine-local session state and safe abnormal-shutdown resume |
| [0025](adr/0025-project-root-is-a-startup-boundary.md) | Pre-engine project validation, activation, and sandbox contract |
| [0026](adr/0026-stable-scene-composition-and-active-document.md) | Stable scene IDs, subscene ownership, tabs, and active-world materialization |
| [0027](adr/0027-stable-prefab-ownership-and-variants.md) | Stable prefab ownership, nested override identity/layering, transactional source writes, variants, and local conversion |
| [0028](adr/0028-authoritative-project-content-validation.md) | Shared editor/headless dependency manifest and project content findings |
| [0029](adr/0029-validation-gated-build-profiles-and-packaging.md) | Shared validation-gated build profiles, runtime packaging, and metadata |
| [0030](adr/0030-audio-authoring-and-bus-schema.md) | Serializable audio sources/listeners, stable clip references, and project bus graph |
| [0031](adr/0031-animation-authoring-runtime-contract.md) | glTF animation artifacts, stable controller states, runtime hydration, and exact-signature retargeting |
## Editor framework
@@ -45,10 +54,19 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [editor/release-notes.md](editor/release-notes.md) | Editor framework 1.0 baseline |
| [editor/evaluations/](editor/evaluations/) | Horizon gate sign-offs (R1–R6) |
| [editor/architecture.md](editor/architecture.md) | Viewport / PIE / settings data flow |
| [editor/visual-language.md](editor/visual-language.md) | Editor chrome, viewport, selection, gizmo, and visualizer language |
| [editor/roadmap.md](editor/roadmap.md) | Phased editor roadmap and status |
| [editor/brp.md](editor/brp.md) | BRP automation and authoring-only policy |
| [editor/debt-audit.md](editor/debt-audit.md) | Zero-debt phase gates |
| [editor/brushes.md](editor/brushes.md) | Brush authoring schema, hydration behavior, and MVP limits |
| [editor/operator-regression-testing.md](editor/operator-regression-testing.md) | Reusable modal-tool and operator invariant harness |
| [editor/session-recovery.md](editor/session-recovery.md) | Clean restart, abnormal shutdown, session schema, and privacy boundary |
| [editor/project-launcher.md](editor/project-launcher.md) | Project manifests, explicit startup roots, recents, and sandbox scaffolding |
| [editor/build-and-package.md](editor/build-and-package.md) | Editor/headless package profiles, output, exclusions, and metadata |
| [editor/multi-scene-composition.md](editor/multi-scene-composition.md) | Independent scene tabs, composition ownership, validation, and recovery |
| [editor/prefab-authoring.md](editor/prefab-authoring.md) | Linked instances, scoped overrides/source Apply, conflicts, variants, unpacking, and local conversion |
| [editor/audio-authoring.md](editor/audio-authoring.md) | Audio clips, source/listener authoring, audition, buses, runtime parity, and validation |
| [editor/animation-authoring.md](editor/animation-authoring.md) | glTF rigs/clips, controller states, preview, runtime requests, stable moves, and validation |
## Working plans (not canonical long-term)
@@ -63,6 +81,8 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans
| `static_mesh_asset_refactor_*.plan.md` | Static mesh renderer, normalized model artifacts, inspector redesign |
| `component_system_refactor_*.plan.md` | Component registry, imported asset refs, collider split, material overrides |
| `jackdaw_feature_roadmap_*.plan.md` | Jackdaw-inspired production roadmap; tracked in Gitea as `BS-JD-*` issues |
| `blacksite_production_readiness_*.plan.md` | M6-M7 reliability, content production, shipping, and acceptance gates |
| `animation_authoring_*.plan.md` | M7 glTF skeletal animation import, preview, controller, and runtime acceptance |
## Crate responsibilities (quick reference)
@@ -2,7 +2,8 @@
## Status
Accepted
Accepted for asset identity; structural ownership superseded by
[ADR 0027](0027-stable-prefab-ownership-and-variants.md)
## Context
@@ -11,11 +12,23 @@ Editor prefab placement and content pipeline work (H1/H2) require stable asset i
## Decision
- Persist stable `AssetId` (UUID) per `assets/` path in `assets/.index/registry.ron`.
- Scene-instance `ModelRef` stores the registry UUID plus a cached source path. Hydration resolves
the UUID-keyed generated manifest first, allowing uniquely identified model moves to retain scene
and animation references.
- Catalog refresh reconciles a missing model record to one new path only when its generated content
hash has exactly one match. Copies and ambiguous matches receive new IDs.
- Introduce `PrefabInstance { asset_id, source_path, overrides_ron }` on placed prefab roots alongside hydration via `PrefabRef`.
- Scene save includes `PrefabInstance` and gameplay marker components from `shared`.
- The initial structural boundary treated instance contents as read-only and required Unpack before
authored structural edits. ADR 0027 replaces that boundary with explicit generated-member
ownership while retaining this ADR's asset and instance identity.
## Consequences
- Prefab paths can be resolved through the registry for dependency tracking.
- Override apply/revert (H2) builds on `overrides_ron` without changing the instance component shape.
- Stable child identity, authored local children, nested instances, variants, and recursive graph
validation are defined by ADR 0027.
- Registry must be version-controlled with the project.
- Legacy path-only `ModelRef` values remain readable but require reassignment before they gain stable
move resolution.
+8 -2
View File
@@ -13,10 +13,16 @@ Levels under `assets/levels/` need forward-compatible migrations as authoring co
- Track `schema_version` in scene files (wrapper or sidecar during transition).
- Provide `scene_schema` module with `migrate_scene_text` and `validate_level_file`.
- Route editor save/load through `scene::document::SceneDocument`, an internal Bevy-free seam that preserves DynamicScene RON while exposing stable actor/component document identities and patch operations for tools.
- CI / `xtask validate-levels` loads all committed levels and fails on unknown versions.
- CI / `xtask validate-levels` loads all committed levels and recursively validates every committed
prefab graph, failing on unknown versions or invalid links/override payloads.
- Keep `scene` Bevy-free. A narrow loader adapter in `game` validates and migrates `.scn.ron`
assets through `scene`, strips the schema envelope in memory, and then invokes Bevy's
`WorldDeserializer`. The packaged game and editor therefore hydrate the same versioned prefab
files that authoring and CI validate.
## Consequences
- Breaking component changes require a migration step and version bump.
- Editor save may wrap scenes with schema header in a follow-up change.
- Editor saves wrap levels and prefabs with the schema header; the runtime adapter removes only the
envelope before Bevy deserialization.
- The current storage format remains DynamicScene RON; `SceneDocument` is not a BSN/JSN migration.
@@ -0,0 +1,48 @@
# ADR 0023: Transactional Scene Persistence And Recovery
## Status
Accepted
## Context
Blacksite previously wrote scene RON directly to the authored path. An interruption during that
write could corrupt the last good scene. The save serializer also strips hydrated runtime state
before extraction and only rebuilt it after a successful write, so serialization or filesystem
failure could leave the live editor world partially stripped.
Daily production additionally needs a recovery path for dirty scenes that does not modify project
assets, mark a scene clean, enter source control, or silently replace authored work.
## Decision
- Manual scene, prefab, and selection writes use a temporary file in the destination directory,
flush and sync its bytes, atomically rename it over the destination, and sync the parent
directory where the platform permits.
- Authored document serialization is separate from persistence. Hydrated state is always rebuilt
after serialization attempts, including validation and serialization failures.
- Dirty saved scenes produce recovery snapshots every 120 seconds by default. The interval has a
15-second safety floor and the newest five generations are retained by default.
- Recovery data lives under `$XDG_STATE_HOME/blacksite-editor/recovery` or
`~/.local/state/blacksite-editor/recovery`. Stable hashes of project root and scene path keep
recovery files outside the project without leaking path names into directory names.
- A recovery snapshot never clears the dirty flag and uses the same authoring-only serialization
contract as manual save.
- On scene load, a newer recovery snapshot is surfaced in the status strip and File menu. The
editor never restores it automatically. Restore loads the snapshot into the original scene
context and leaves the scene dirty; the snapshot remains available until manual Save commits it
or Discard removes that scene's recovery generations. Save Recovery Copy As writes the snapshot
to a separate transactional scene file without changing the active scene or recovery lifecycle.
- A successful manual save retires recovery generations for that scene.
## Consequences
- Interrupted manual writes retain the previous complete destination on filesystems with atomic
same-directory rename semantics.
- Recovery is machine-local and does not pollute builds or source control.
- Autosave still performs authored serialization and hydration rebuild work. Performance
instrumentation and background snapshotting remain follow-up work under the production roadmap.
- Unsaved new scenes do not yet have a stable recovery identity; they require a later session-ID
recovery extension.
- The initial controls use user preference fields and documented defaults; a dedicated Preferences
panel can expose them later without changing the storage contract.
@@ -0,0 +1,40 @@
# ADR 0024: Versioned Editor Session State
## Status
Accepted
## Context
User preferences already preserve dock layout and hierarchy options, while scene recovery preserves
dirty authored data. Neither establishes whether the editor exited cleanly, and several productive
session details such as the active scene, panel visibility, and viewport bookmarks were memory-only.
Restoring those details from an abnormal session must not revive a modal tool, dirty preview, or
untrusted serialized ECS state.
## Decision
- Store a separate, versioned `session.ron` under `$XDG_STATE_HOME/blacksite-editor` or
`~/.local/state/blacksite-editor`. User preferences remain in the user config directory and scene
recovery remains a separate generation store.
- Session schema v1 allowlists metadata only: project root, active scene path, saved dock-layout
text, hierarchy expansion paths, non-destructive panel visibility, and finite camera bookmark
transforms.
- Write the session transactionally. Startup immediately writes `clean_shutdown: false`; normal
`AppExit` writes the final document with `clean_shutdown: true`.
- A clean prior session may restore its active scene and non-destructive UI state automatically.
An abnormal prior session starts from the normal safe scene and requires explicit confirmation
before opening the prior scene.
- Never serialize scene contents, modal operator state, unsaved preview geometry, environment
variables, credentials, or access tokens into session state.
- Missing schema version migrates to v1. Newer unknown schemas are rejected rather than guessed.
## Consequences
- Session restore is independent of project source control and cannot modify project files merely
by starting the editor.
- A process killed before `AppExit` leaves an actionable abnormal marker on the next launch.
- Dock/hierarchy preference persistence remains backward-compatible, while session state can evolve
through explicit schema migrations.
- Diagnostics bundles may report allowlisted session metadata, but must maintain the same privacy
boundary.
@@ -0,0 +1,51 @@
# ADR 0025: Project Root Is a Startup Boundary
## Status
Accepted
## Context
Bevy configures `AssetPlugin.file_path` before editor plugins and project settings initialize. The
asset catalog, scene loader, import pipeline, session state, and runtime game systems must all agree
on one project root. Changing only editor metadata in a running process leaves `AssetServer` and
already-created handles attached to the old project, which can silently read or write the wrong
content.
Projects also need stable identity and enough template metadata for a launcher to distinguish a
game workspace from a disposable sandbox without inspecting arbitrary project contents.
## Decision
- Select and validate the project root before constructing the Bevy `App`. `--project <root>`, the
graphical launcher, and recent-project resume all feed the same pre-engine activation function.
- Do not implement in-process project switching. **Switch Project** exits or relaunches through the
launcher so the next process creates `AssetPlugin`, settings, catalog, and session state from one
root.
- Extend `assets/project.ron` with backward-compatible `project_id`, `project_kind`,
`template_version`, and capability tags. Legacy manifests receive safe defaults; new projects
receive a UUID.
- A valid project has a parseable manifest, a project-relative default level that cannot escape the
root, and a default level that passes the shared scene validator.
- The standalone `GamePlugin` materializes that `default_level` through the schema-aware Bevy
`DynamicWorld` loader. Embedded editor startup explicitly defers this step so `SceneIo` remains
the sole owner of the active authored document, tabs, composition, and recovery state.
- Sandbox scaffolding writes only to a missing or empty destination. It creates the standard asset
directories, a schema-current empty level, and a manifest using transactional writes.
- Recent-project presentation filters missing, invalid, and duplicate roots before showing them.
- On Linux, launcher-to-editor and editor-to-launcher handoffs use independent transient user
services with an explicit working directory and a bounded display/session environment allowlist.
Closing either source process therefore cannot tear down the process it launched.
## Consequences
- Project activation cannot leave the editor half-connected to two asset roots.
- Packaged and workspace game binaries start in the validated authored default level instead of the
procedural editor fallback arena; the editor cannot race a second runtime-owned scene load.
- Switching projects requires a process boundary, but startup remains deterministic and testable.
- Project scaffolding is intentionally conservative and cannot merge into a directory containing
user data.
- Template migrations and capability negotiation can evolve independently of the project-settings
file format version.
- The service-manager handoff is Linux-specific; other platforms use the local process-spawn
fallback until native packaging provides a stronger lifecycle boundary.
@@ -0,0 +1,47 @@
# ADR 0026: Stable Scene Composition And Active Document
## Status
Accepted
## Context
One monolithic dynamic scene does not scale to daily content production. Multiple authors and
disciplines need geometry, lighting, gameplay, and set dressing to remain separable, but Bevy
`Entity` identifiers are allocated at runtime and cannot identify actors or ownership across files.
The editor also materializes one authored document into the live ECS world, where hydration,
selection, history, PIE, and rendering operate.
## Decision
- Persist one reflected `SceneComposition` resource in each dynamic scene. It owns a stable
`scene_id` and project-relative `SubsceneReference` entries with stable reference IDs plus loaded
and locked flags.
- Reject absolute/escaping paths, empty or duplicate reference IDs, missing targets, duplicate
scene IDs, and cyclic graphs through the same `scene` crate validator used by editor load,
project inspection, and `cargo validate-levels`.
- Keep one scene tab materialized in the ECS world. Inactive tabs retain normalized authored RON,
path, dirty state, and recovery location in memory. Switching serializes the outgoing authored
roots and hydrates the incoming snapshot.
- Tag hydrated subscene actors with runtime-only `ComposedSceneMember` ownership. They participate
in the active composition and PIE but are excluded from the owner scene's save and recovery
payload.
- Treat an unloaded reference as absent from the world. Loaded references inherit their authored
visibility; locked references enter the hierarchy's existing read-only lock path. Nested locks
propagate downward.
- Composition add/remove/load/lock changes are ordinary undoable history commands. Because existing
entity-edit history stores runtime entity IDs, activating another tab clears that tab's history
instead of retaining commands that could target rematerialized entities incorrectly.
## Consequences
- Cross-scene identity is stable and reviewable without leaking runtime entity IDs into files.
- PIE, viewport rendering, and build validation see the same active materialized composition.
- Saved dirty tabs, including inactive ones, receive independent bounded recovery generations.
- Legacy scenes load without a composition resource using a deterministic path-derived identity;
their next save promotes that identity into the scene resource.
- The open tab set is session-local; safe restart resumes the last active authored scene. Unsaved
untitled tabs remain outside automatic recovery until a future session schema can restore them
without guessing a destination.
- Preserving entity-edit undo stacks across tab materialization requires stable-ID history commands
and is future work; clearing them is explicit and safe.
@@ -0,0 +1,89 @@
# ADR 0027: Stable Prefab Ownership, Overrides, And Variants
## Status
Accepted
## Context
ADR 0005 established stable asset-registry identity and linked `PrefabInstance` roots, but the
first structural boundary treated every descendant of an instance as generated source content.
That prevented an authored scene or prefab from adding local children, nesting another linked
instance, or expressing a variant without flattening the source prefab.
Bevy allocates `Entity` identifiers at runtime, and display names can change. Neither is a durable
key for an override, especially when multiple nested prefab layers contain the same source
`ActorId`. Overrides must also produce the same result in a packaged game that does not include the
editor. Finally, publishing an override to a source file crosses the in-memory undo boundary and
must not overwrite unrelated external edits.
## Decision
- Keep `PrefabInstance { asset_id, source_path, overrides_ron }` as the authored, serialized link.
Its source path remains project-relative and under `assets/`.
- Tag entities spawned from that link with runtime-only `HydratedPrefabMember { instance_root }`.
Tagged source members are excluded from scene, recovery, and prefab serialization. The linked
root, authored local descendants, and nested `PrefabInstance` actors remain editable and
serializable.
- Parse `PrefabInstance` components through `SceneDocument` and validate the dependency graph
recursively. Reject empty asset IDs, unsafe or non-`.scn.ron` paths, missing sources, dependency
cycles, authored actors without `ActorId`, and duplicate `ActorId` values within one document.
Editor load, prefab save, project inspection, and level validation use this structured path.
- Store overrides in the versioned, shared `PrefabOverrides` contract. A `PrefabActorPath` combines
an `instance_chain` of nested link-anchor `ActorId` values with the target actor's `ActorId`, so
repeated IDs in different nested documents remain unambiguous. Runtime override application
lives in `shared` hydration rather than the editor.
- Property overrides carry a reflected component type, property path, base component value, and
replacement component value.
- Component overrides add, replace, or remove a reflected component and retain its base value.
- Structural overrides remove or reparent a source actor. The schema reserves local-child
attachment, but the editor does not expose attachment directly to a generated member until its
reload and ownership lifecycle is safe.
- Retain the v1 root transform, material, and child-visibility fields for wire compatibility. New
authoring uses stable property/component/structural operations; legacy child visibility remains
keyed by `ActorId`, with name keys read only as a compatibility fallback.
- Resolve a composed result in increasing specificity: source document, each nested link's override
layer, the containing variant document and its authored local structure, then the placed
instance's overrides. A containing layer may target a nested source actor through its stable
`instance_chain` without flattening that source.
- Distinguish **instance override** from **Apply to source**. Editing a linked member records an
undoable operation in the containing `PrefabInstance`. Applying a direct target to source patches
that source document. Applying a nested target transfers the operation into the immediate nested
link stored by the containing source; it does not skip the composition layer and mutate a leaf
prefab unexpectedly.
- Validate the complete graph and write source changes atomically. The source-apply history command
stores the exact source bytes before and after the write plus the instance state. Undo and redo
proceed only when the current file exactly matches the expected side of that command; an external
change blocks the history operation instead of being overwritten.
- Record a transitive deterministic source-graph revision and the base values needed for three-way
conflict checks. Health distinguishes loading, ready, untracked, changed-base, semantic/stale
conflict, broken-source, and malformed-override states. Conflict recovery can rebase while keeping
overrides, take the current source for conflicting operations, remove legacy stale targets,
retry a repaired source, or relink to another validated prefab.
- Make **Unpack Layer** an undoable outer-layer conversion: remove the selected instance link and
retain its hydrated members as authored local actors, while preserving nested `PrefabInstance`
links. Make **Convert to Local** the explicit recursive conversion: remove all nested links in the
selected instance result, assign fresh local `ActorId` values, and store snapshots so redo does not
depend on the source files.
- Define a variant as an ordinary prefab document whose selected root is itself a linked
`PrefabInstance`. Saving the selection serializes that link, its override layer, and authored local
descendants/nested instances while excluding hydrated source members. No separate variant asset
type is introduced.
## Consequences
- Nested prefab graphs and variants preserve their source links instead of duplicating generated
content into every owner file. The same shared override data is applied by editor and game
hydration.
- Renaming a source actor does not break current overrides while its `ActorId` and nested anchor
chain remain stable. Moving an actor between documents or replacing an anchor is an identity
change and can surface a recoverable conflict.
- Instance-local edits and Revert operations remain ordinary editor history. **Apply to source** is an
explicit asset mutation with stricter exact-file undo/redo preconditions.
- Generated members may be removed or reparented inside the same prefab layer through structural
overrides. Cross-layer parenting, generated sibling-order overrides, and direct authored-local
attachment to generated members remain intentionally blocked until their persistence semantics
are defined.
- **Unpack Layer** preserves reusable nested links; **Convert to Local** intentionally severs all
links and creates a source-independent authored snapshot. The destructive scope is visible in the
command name rather than inferred.
@@ -0,0 +1,44 @@
# ADR 0028: Authoritative project content validation
## Status
Accepted
## Context
Scene, prefab, and imported-asset checks were distributed across editor loading, hydration, and the
`validate-levels` task. A project could therefore pass headless scene validation while still
containing a missing model, texture, material, shader, generated mesh manifest, post effect, or
rendering profile reference. Editor-only validation would also risk disagreeing with CI and release
tooling.
## Decision
The Bevy-free `scene` crate owns `validate_project` and the structured
`ProjectValidationReport`. The report contains a deterministic dependency manifest and findings
with severity, stable code, source document, owning `ActorId` where available, referenced path,
message, and repair action.
Both the editor Diagnostics window and the `cargo validate-levels` headless command call this same
entry point. The command supports `--project <path>` and `--json`; the editor can select the live
owning actor for an attributed finding. Blocking errors produce a nonzero headless exit status.
Project validation covers the project manifest and asset roots, registry IDs/sources/dependencies,
generated static mesh manifests, material and shader documents, post effects, scene and prefab
graphs, authored model/material/texture/brush/collider references, rendering profiles, and
unhydrated Git LFS pointer files. The validator owns the runtime-packageability predicate consumed by
the packager: editor/hidden trees, source-authoring formats, symlinks, and unreadable traversal are
blocking rather than being accepted and later omitted. The project default must be a regular
`.scn.ron` file under `assets/levels/`, which guarantees the full document dependency pass audits the
startup entrypoint. Unknown newer scene schemas are rejected rather than down-stamped. Platform
requirements are explicit findings; for example, Solari projects record the required forward-path
fallback QA when ray tracing is unavailable.
## Consequences
- Headless and editor validation share result semantics and finding ownership.
- Missing references are visible before Bevy hydration attempts to load them.
- Release packaging invokes this report before and after compilation and refuses blocking errors;
Gitea #44 acceptance verifies the shared gate against real development output.
- Asset formats added later must register their dependencies with this validator and extend the
valid, missing, cyclic, and incompatible project-fixture matrix.
@@ -0,0 +1,66 @@
# ADR 0029: Validation-gated build profiles and packaging
## Status
Accepted
## Context
Blacksite builds previously required users to know Cargo commands and manually assemble assets. That
made it easy to ship broken references, editor caches, recovery data, or an executable without the
settings and content that produced it. Ordinary debug binaries are also too large for practical
distribution, while release LTO is too expensive for every development package.
## Decision
Projects define versioned RON profiles under `assets/build_profiles/`. A profile selects the Cargo
package profile, optional target triple and feature set, rendering tier, default scene, and a safe
project-relative output directory. Development and QA exports use dedicated optimized non-LTO Cargo
profiles; QA retains line tables, while release exports retain thin LTO and strip symbols. The
development rendering tier forces the portable Forward GI path in the packaged project settings;
representative and shipping tiers preserve the authored rendering policy. Windows MSVC QA packages
include Cargo's PDB sidecar and record it in the content manifest.
`cargo package-project` is the authoritative build/package entry point for editor and CI. It runs
`scene::validate_project` before compiling, builds `game`, reads the executable path from Cargo's
JSON artifact stream, then validates again against a BLAKE3 snapshot of the runtime inputs. A profile
default scene must be a regular `.scn.ron` file under the fully audited `assets/levels/` tree and pass
schema plus composition validation. The selected default scene and rendering tier are applied to the
packaged `project.ron`. Metadata records profile, target, features, rendering tier, default scene,
exact engine/project commit and
dirty state, Rust/Cargo versions, and a sorted BLAKE3 content manifest. Features that require the
development or hot-reload dynamic libraries are rejected because those libraries are not shipping
artifacts.
Runtime packaging excludes the editor asset registry, trash, thumbnails, build profiles, recovery
and autosave data, temporary/backup files, and source-authoring formats. Traversal errors and runtime
asset symlinks are blocking instead of silently omitting content. Output is restricted to a dedicated
non-symlinked `dist/<name>/` tree. A non-empty existing directory must carry recognized package
metadata before it can be seeded or pruned, preventing a profile typo from replacing project source
or an unrelated user directory.
Assembly happens in a unique sibling staging directory copied from the previous package. Staging has
no shared file inodes with the published output, and its complete content is rehashed before
promotion, so a failed build or external output edit cannot mutate the candidate package. An
OS-backed per-output lock prevents concurrent publication on Unix and Windows. Versioned
ownership records authenticate lock/staging cleanup; an interrupted run removes only owned partial
staging and restores a strictly validated prior backup before retrying. Only a complete,
unchanged-input package is promoted; stale files and obsolete directory shapes are pruned in staging.
The editor Build panel invokes the same engine-workspace Cargo alias for the active external project,
streams stdout/stderr, owns and cancels its worker/process tree, and exposes Build, Build and Run,
and Reveal Output. Dirty scene tabs block a build. Cross-target packages are produced but Build and
Run refuses to execute a binary for a different host operating system or CPU architecture.
## Consequences
- Editor and headless builds have identical validation, profile, inclusion, and metadata semantics.
- Blocking content errors fail before compiler or output work and are checked again after a long
compile. Concurrent asset mutation aborts staging without replacing the previous package.
- The first build of a package profile compiles optimized intermediates; later unchanged builds reuse
Cargo intermediates and avoid rewriting byte-identical files after seeding the staged copy.
- Cross-compilation still requires the selected Rust target and platform linker/toolchain to be
installed; missing tools are reported by Cargo in the Build panel. The native layout currently
accepts desktop Linux and Windows targets only; web, mobile, and platform-bundle formats require
dedicated future packagers rather than being mislabeled as ready native packages.
- `--skip-build` requires an explicit matching `game` artifact, avoiding guesses about Cargo target
directories or configured default targets.
@@ -0,0 +1,42 @@
# ADR 0030: Audio Authoring And Bus Schema
## Status
Accepted
## Context
Audio sources and listeners must round-trip through authored scenes without serializing Bevy's
runtime playback handles or sink state. Source routing must also survive bus display-name changes,
project reloads, PIE, and packaging. Bevy provides playback and spatial-listener primitives, but it
does not define Blacksite's persistent authoring schema or project bus graph.
## Decision
`shared` owns reflected, serializable `AudioSourceDesc`, `AudioListenerDesc`,
`AudioAttenuationDesc`, and `AudioRolloff` types. Dedicated authored audio actors use the
`AudioSource` and `AudioListener` actor kinds. Runtime playback, sink, and listener components are
derived state and are never scene source of truth.
An authored clip uses `EditorAssetRef`. Its registry identity remains authoritative, its imported
sub-asset ID is `audio:source`, and its cached source path supports runtime hydration and package
validation. Source bus references store stable bus IDs rather than display labels.
`settings` owns `AudioSettings` and its bus graph. Every project contains stable `master`, `music`,
and `sfx` IDs; Music and SFX route to Master by default. Additional buses are allowed when their
lowercase stable IDs are unique and their parent chain terminates at Master. Validation rejects
missing required buses, invalid gain values, missing parents, unknown references, and cycles.
The `ProjectSettings.audio` field uses a serde default so older manifests load with the standard
bus graph. New project and sandbox manifests include the audio capability and `assets/audio` root.
## Consequences
- Renaming a bus label is safe; changing a bus ID is a routing migration.
- Editor audition and game playback share one authored contract while retaining independent
transient runtime state.
- Continuous spatial blend and attenuation behavior belong to the runtime adapter; the schema does
not claim those controls map one-to-one to native Bevy components.
- DSP graphs, sends, reverb zones, streaming banks, and middleware integration remain future work.
- Gitea issue #47 passed automated, headless, live editor/PIE, and packaged-runtime acceptance; this
contract is the M7 audio baseline.
@@ -0,0 +1,87 @@
# ADR 0031: Animation Authoring And Runtime Contract
## Status
Accepted
## Context
Blacksite currently records animation and skin counts while importing glTF and FBX models, but the
authored scene contract contains only a path-based `ModelRef`. Scene-instance hydration loads a
model world without selecting or driving its clips, and the editor has no stable clip references,
controller inspector, preview, or compatibility validation.
Bevy 0.19 already exposes complete glTF scene, skin, `AnimationClip`, `AnimationGraph`, and
`AnimationPlayer` primitives. The patched FBX loader does not: it parses some skin metadata but does
not build the source node hierarchy, attach Bevy skinned-mesh bindings, or convert animation curves
into clips. Treating its metadata counts as playback support would create scenes that appear valid
but remain static at runtime.
Animation authoring also needs a boundary between persistent intent and transient Bevy player state.
Clip references must survive project asset moves, preview must agree with PIE, and a game extension
must be able to request authored states without depending on editor types.
## Decision
Animation authoring v1 supports glTF 2.0 sources (`.gltf` and `.glb`) through Bevy's native loader.
FBX remains a supported static-model source only. Import or validation of an FBX containing
animation stacks or skin deformers must produce an actionable blocking diagnostic until the loader
can construct hierarchy, Bevy skinned meshes, and animation clips.
Each animated model has a versioned generated manifest under `assets/animations/generated/`, keyed
by the model's stable asset-registry UUID. The manifest records the source path and fingerprint,
skeletons and their exact signatures, stable clip sub-asset IDs, clip label/index/duration, target
skeleton signature, normalized event markers, and import diagnostics. Registry UUID plus sub-asset
ID is authoritative; cached `ModelRef` and `EditorAssetRef` source paths are only runtime-resolution
and repair hints. UUID-keyed generated manifests provide the current source path after a uniquely
reconciled move.
`shared` owns reflected, serializable `AnimationControllerDesc` and its named state/event value
types. A controller sits beside the model scene reference and uses `EditorAssetRef` for skeleton and
clip references. It contains one layer of named states, one default state, a default crossfade
duration, and per-state playback range, loop, and speed. State IDs are stable authored identifiers;
display labels are not runtime keys.
Retargeting v1 requires an exact skeleton-signature match. The signature is a deterministic hash of
ordered joint target paths and bind-pose structure. For glTF, each path is hashed as a
length-prefixed vector of the exact UTF-8 node-name bytes Bevy 0.19 uses, including whitespace and
path separators; unnamed nodes use Bevy's `GltfNode{index}` fallback. The readable normalized paths
stored in the manifest are display metadata and never compatibility keys. Blacksite does not infer
humanoid roles, rename joints, or perform proportional remapping in this version. This exact node
identity contract is animation-manifest schema v2; v1 artifacts must be reimported.
The runtime adapter waits for the model `WorldAssetRoot` instance to report readiness, finds its
animation player, and derives Bevy graph/player state from the controller. Generated instance,
graph, player, transition, and playback bookkeeping is transient and excluded from authored scene
serialization. Rehydration owns a dedicated generated instance root and must not despawn authored
children attached to the actor.
`game` exposes a small request API that changes an animated actor to a named state and applies the
authored/default crossfade. Invalid state requests are rejected without disturbing the active
state. The editor's preview and scrub controls use the same runtime adapter; starting, stopping, or
scrubbing a preview never changes the authored descriptor, history, or scene dirty state.
Interactive diagnostics, headless validation, and packaging resolve the same manifest and enforce
source availability, stable reference resolution, supported formats, valid playback ranges/events,
and exact skeleton compatibility.
Animation v1 supports one top-level animated hierarchy per glTF asset. Import scans every animation
channel using the same top-level roots Bevy uses for `AnimationPlayer` placement. A source requiring
multiple players is marked runtime-unsupported with a blocking repair diagnostic; artists must split
the rigs into separate assets or export all clips beneath one common root.
## Consequences
- glTF/GLB is the only animation interchange format promised by v1; artists must convert animated
FBX sources before import.
- Stable registry and sub-asset identities allow source moves without rewriting every controller,
while ambiguous or removed clips become explicit validation failures.
- One-layer named states provide a deterministic gameplay integration point without committing the
editor to a visual graph format prematurely.
- Exact-signature retargeting is intentionally restrictive but cannot silently deform the wrong rig.
- Rejecting multiple animation roots prevents the runtime adapter from selecting an arbitrary first
player and driving only part of a source.
- A future visual graph, blend trees, root motion, IK, advanced retargeting, or animated FBX support
must extend or supersede this contract explicitly rather than leaking runtime Bevy components into
authored scenes.
- Implementation and production acceptance are tracked in Gitea issue #46.
+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.