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

@@ -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.