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

@@ -0,0 +1,105 @@
# Skeletal Animation Import, Preview, And Authoring
Working implementation plan for Gitea issue
[`#46`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/46).
This is the minimum production animation loop required by the M7 content-production milestone.
## Status
Implementation and production acceptance are complete. The persistent/runtime contract, generated
manifest, stable model/clip identity, runtime adapter, browser drag workflow, typed inspector, and
headless validation are implemented. Live acceptance covers import, placement, preview, scrub,
save/reload hydration, PIE playback, source relocation, development packaging, and standalone
runtime playback with the committed RobotExpressive fixture.
## Outcome
An author can import a supported skinned model, inspect its skeleton and clips, place an animated
actor, preview and scrub a clip without dirtying the scene, save a small named state set, and drive
the same state changes in PIE and a packaged game. Missing content and skeleton mismatches fail with
owner-attributed repair guidance before packaging.
## Format Policy
- Animation authoring v1 supports glTF 2.0 (`.gltf` and `.glb`) through Bevy's native scene,
skinning, and animation assets.
- FBX remains supported for the existing static mesh import path. An FBX containing animation stacks
or skin deformers is not a supported animated source and must produce a blocking, actionable
diagnostic.
- Animated FBX support cannot be enabled until the loader constructs the source hierarchy, Bevy
skinned-mesh bindings, and `AnimationClip` assets. Metadata counts alone do not qualify as support.
## Architecture
- The asset registry UUID remains the parent model identity. A generated animation manifest under
`assets/animations/generated/` records the source fingerprint, skeleton signatures, stable clip
sub-asset IDs, clip metadata, and animation events.
- `shared::AnimationControllerDesc` is reflected and serializable. It references imported skeletons
and clips through stable `EditorAssetRef` values and owns one layer of named states, a default
state, playback range/loop/speed, and default crossfade duration.
- `game` owns the runtime adapter. It waits for the model `WorldAssetRoot` instance to become ready,
attaches transient animation graph/player state, and exposes a request API for changing an actor's
named state.
- `editor` owns import presentation, clip/skeleton shelves, drag assignment/placement, inspector
controls, and non-dirty preview/scrubbing. Preview uses the runtime adapter rather than a separate
interpretation of the authored contract.
- `scene` and package validation resolve the same manifests and stable references used by editor and
runtime hydration.
## Authoritative Data
The generated manifest is keyed by the model's stable registry UUID and includes:
- schema version and source path/fingerprint;
- scenes and exact skeleton signatures;
- stable skeleton and clip sub-asset IDs;
- clip label, source index, duration, target skeleton signature, and event markers;
- import diagnostics, including unsupported animated FBX content.
An exact skeleton signature is a deterministic hash of normalized ordered joint target paths and
bind-pose structure. Retargeting v1 accepts only an exact signature match. No implicit joint-name,
humanoid, or proportional remapping is allowed.
## Implementation Sequence
1. Add the versioned animation manifest schema, stable sub-asset identity rules, glTF extraction,
FBX blocking diagnostics, and focused importer tests.
2. Add `AnimationControllerDesc`, named state/event types, registration, migration defaults,
actor validation, history snapshots, scene round-trip coverage, and runtime-only strip policy.
3. Replace broad imported-model child cleanup with a dedicated generated instance root, then hydrate
the ready scene instance into a transient graph/player and implement the game state-request API.
4. Extend Asset Browser model shelves with skeleton and clip rows, compatibility status, preview,
scrub/range/loop controls, and clip drag placement or assignment.
5. Add the typed Animation Controller inspector, undoable state edits, PIE pause/stop reconciliation,
owner-attributed project validation, and package dependency collection.
6. Commit a small redistributable animated GLB and sample scene, then run import, round-trip,
headless, live editor/PIE, and packaged-runtime acceptance.
## Acceptance Gates
- A committed skinned GLB and its clips import, preview, save, hydrate, and play in PIE and a
packaged runtime.
- Moving or renaming the source inside the project preserves controller clip references through the
registry UUID and stable sub-asset IDs.
- Missing manifests/clips and mismatched skeleton signatures produce actor/property-attributed
diagnostics with a concrete repair action.
- Gameplay can request a valid named state through the public game API; invalid requests leave the
current state intact and report a diagnostic.
- Preview follows the authored loop/range/speed settings, stops cleanly, and never mutates the scene
descriptor, history, or dirty state.
- Generated graph/player/instance components never serialize into authored scenes, and model
rehydration never deletes authored hierarchy children.
- Animated or skinned FBX content blocks animation import with a diagnostic that explains the glTF
v1 requirement.
- Focused importer, validation, hydration, request-API, and editor operator tests pass alongside
workspace tests, `cargo validate-levels`, package validation, and live smoke testing.
## Deliberate Boundaries
- V1 provides one animation layer with named states, one default state, and a default crossfade. It
does not include a visual state graph, blend trees, transition-condition authoring, inverse
kinematics, motion matching, or root-motion extraction.
- Event markers are normalized data and runtime notifications; V1 has no timeline scripting system.
- Retargeting is exact signature match only.
- FBX static mesh import remains available, but animated FBX conversion is separate loader work and
cannot silently fall back to bind-pose or metadata-only playback.
@@ -0,0 +1,72 @@
# Audio Authoring And Runtime Parity
Working implementation plan for Gitea issue
[`#47`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/47).
This is the minimum complete audio loop required by the M7 content-production milestone.
## Status
Completed and production-accepted in Gitea #47. Permanent behavior is documented in
[ADR 0030](../../docs/adr/0030-audio-authoring-and-bus-schema.md) and
[Audio Authoring](../../docs/editor/audio-authoring.md).
## Outcome
An author can import a supported audio clip, place or assign it as an authored source, tune playback
and spatial behavior, audition it without dirtying the scene, save/reload it, and hear equivalent
behavior in PIE and a packaged game. Projects expose stable Master, Music, and SFX buses with runtime
gain/mute hooks and validation that also runs headlessly.
## Architecture
- `shared` owns reflected, serializable source/listener/attenuation descriptors and stable actor kinds.
- `settings` owns versioned project bus definitions and validation; bus references use stable IDs.
- `game` hydrates authoring descriptors into Bevy audio playback/listener components and applies bus
controls. Hydrated components remain derived and are never scene source of truth.
- `editor` owns asset discovery/import UX, inspector controls, drag/drop placement, visualizers, and
transient audition state. Audition never mutates an authored descriptor or marks a scene dirty.
- Scene and project validation share the same clip-reference, bus-reference, range, and listener rules
used by packaging. Missing, excluded, unsupported, or Git LFS pointer clips block release validation.
## Supported Content
- Ogg Vorbis is the baseline runtime format.
- WAV, MP3, and FLAC support is enabled explicitly in the workspace Bevy feature set.
- Audio sources support gain, pitch, looping, autoplay, spatial blend, attenuation, and bus routing.
- Listener authoring supports enabled state, priority, and ear gap; at runtime exactly one enabled
listener is selected deterministically.
- Default project buses are `master`, `music`, and `sfx`; Music and SFX route to Master.
## Implementation Sequence
1. Add shared descriptors, settings schema/defaults/validation, launcher scaffolding, and migrations.
2. Add audio clip catalog classification, import target, search/filter/details, and drag payloads.
3. Add runtime source/listener hydration, deterministic listener selection, and bus controls.
4. Add inspector cards with undoable edits and scene save/validation allowlists.
5. Add viewport icons/range visualizers and transient audition/stop using the editor camera listener.
6. Add a small sample clip/scene, focused round-trip and PIE tests, live QA, permanent docs, and Gitea
acceptance evidence.
## Acceptance Gates
- Dragging a clip into the viewport creates an audio source; dropping onto a compatible selected
source assigns the clip through one undoable command.
- Inspector edits survive save/reload and PIE hydration without generated playback state leaking into
the authored scene.
- Spatial preview follows the editor camera, stops on explicit Stop, mode/project changes, or source
deletion, and never changes scene dirty state.
- Bus definitions persist with stable IDs, invalid parent cycles/references are rejected, and runtime
gain/mute hooks affect routed sources.
- Headless validation reports missing/unpackageable clips, unsupported values, invalid buses, and
ambiguous enabled listeners with actor/property context.
- Focused unit/integration tests, `cargo validate-levels`, package validation, and live editor/game
smoke tests passed for issue `#47` closure.
## Deliberate Boundaries
- This slice does not include DSP graphs, reverb zones, waveform editing, audio streaming banks,
middleware integration, or platform-specific compression pipelines.
- Continuous spatial blend is represented authoritatively and implemented without claiming Bevy
supports a native blend control; the runtime adapter owns the mapping/mix behavior.
- A future mixer UI may expose additional buses and sends, but it must preserve the stable bus IDs and
parent graph established here.
@@ -0,0 +1,101 @@
# Blacksite Editor Production Readiness Program
Working milestone plan for the production expansion tracked by Gitea epic
[`#1`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/1).
The existing Jackdaw-inspired M0-M5 roadmap remains the authoring/tool foundation. This plan adds
the reliability and shipping gates required for daily indie game production.
## Definition Of Production Ready
Blacksite is production ready only when the evidence matrix in Gitea
[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50)
is signed off. Feature presence alone is insufficient. Recovery, validation, packaging,
performance, soak, regression, and first-hour workflows must pass against a representative project.
## Immediate Sequence
1. Completed: hierarchy/prefab boundary hardening `#40`, transactional recovery `#39`, stable
sessions/diagnostics `#41`, and Project Browser/startup boundaries `#3`.
2. Completed: stable scene tabs and composed subscene ownership/validation in `#42`.
3. Completed: nested prefabs, variants, and structural overrides passed production acceptance in
`#43`; M6 implementation is complete.
4. Completed: authoritative content validation `#45` and the validation-gated packaging/Build
workflow `#44`.
5. Completed: audio source/listener/bus authoring and spatial preview passed production acceptance
in `#47`. Next: animation `#46`, navigation `#48`, source-control safety `#49`, then readiness
gate `#50`.
## M6 - Reliability, Recovery, And Project Workflow
**Exit:** A normal or interrupted editor session cannot silently lose or corrupt authored work, and
projects/scenes/prefabs have stable daily workflows.
| Issue | Capability | Priority |
|-------|------------|----------|
| #3 | Project launcher, templates, recent projects, resume | P0 |
| #39 | Transactional saves, autosave, crash recovery | P0 |
| #40 | Hierarchy, parenting, prefab structure hardening | P0 |
| #41 | Session persistence and crash diagnostics | P0 |
| #42 | Multi-scene tabs, subscenes, level composition | P1 |
| #43 | Nested prefabs, variants, structural overrides | P1 |
## M7 - Content Production And Shipping
**Exit:** A clean checkout can validate, build, package, and run a representative project with the
minimum animation, audio, and navigation authoring loops required by the game.
| Issue | Capability | Priority |
|-------|------------|----------|
| #44 | Build/package profiles and Build panel | P0 |
| #45 | Dependency manifest and content release gate | P0 |
| #46 | Skeletal animation import/preview/authoring | P1 |
| #47 | Audio sources/listeners/buses/spatial preview | P1 |
| #48 | Navigation authoring/bake/path preview | P1 |
| #49 | Source-control status and collaborative file safety | P2 |
| #50 | Production-readiness acceptance matrix | P0 |
## Cross-Cutting Gates
- Authored IDs, scene schema, hydration stripping, and extension boundaries remain authoritative.
- Every mutation supports meaningful undo/redo; modal tools also support cancel without dirty state.
- Editor-only helpers, recovery files, and caches never enter scenes or game packages.
- Interactive and headless validation use the same rules and produce equivalent blocking results.
- Large asset, terrain, navigation, and geometry work is debounced or dirty-region based.
- Visible behavior updates root controls and `docs/editor/`; hard-to-reverse decisions get ADRs.
- Production signoff requires a second-person first-hour QA pass and no open P0 blocker.
## Completed Slice - UI Identity And Structural Dragging
- Near-black Blacksite shell with compact tool identity rather than a Unity clone.
- Pointer-following asset drag preview, viewport reticle, boundary, and corner brackets.
- Full-width hierarchy attach targets plus explicit root/reorder/invalid feedback.
- World-transform-preserving reparent/unparent with grouped history.
- Cycle rejection, subtree-safe multi-drag, parent expansion, and focused regression coverage.
## Completed Slice - Multi-Scene Production Workflow
- Independent scene tabs integrated into the right end of the existing main toolbar.
- Stable `SceneComposition` resources with project-relative references and no runtime entity IDs.
- Recursive missing/cycle/duplicate/path-escape validation shared by editor and CI.
- Runtime-only composed ownership, load/lock/focus controls, and owner-save exclusion.
- Per-saved-tab recovery, composition undo/redo, PIE-active composition consistency, and fixtures.
## Completed Slice - Validation-Gated Build And Packaging
- Shared owner-attributed project validation and runtime-packageability policy in editor, CI, and
packaging; unknown schemas, missing LFS objects, excluded references, and unsafe traversal block.
- Versioned development/QA/release profiles with Cargo-reported artifacts, rendering/default-scene
application, Windows QA symbols, supported-target enforcement, and deterministic metadata.
- OS-locked authenticated staging, interrupted-build recovery, complete pre-publish hashing, safe
replacement, and unchanged-output reuse.
- Non-blocking editor Build/Run/Cancel/Reveal workflow with dirty-tab guard and process-tree cleanup.
- Gitea #44 and #45 closed after headless, focused regression, repeated-build, and live packaged
development-runtime acceptance.
## Completed Slice - Audio Authoring And Spatial Preview
The stable authoring/runtime contract is recorded in
[ADR 0030](../../docs/adr/0030-audio-authoring-and-bus-schema.md), with controls, runtime behavior,
validation, and the committed sample fixture documented in
[Audio Authoring](../../docs/editor/audio-authoring.md). Gitea #47 closed after automated,
headless, live editor/PIE, and packaged-runtime acceptance.