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
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user