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