Build renderer and material component foundations

Add dedicated skinned rendering, pose restoration, shared Material and Material Instance slots, registry-driven components, Surface/Solari integration, transactional schema upgrades, navigation authoring, documentation, and evaluation evidence.
This commit is contained in:
Rbanh committed 2026-07-12 00:24:06 -04:00
1 parent 0553a85220
commit 0798aa5d57
169 files changed
+27098 -3469

No files matched your search

+11
View File
@@ -46,6 +46,11 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [0029](adr/0029-validation-gated-build-profiles-and-packaging.md) | Shared validation-gated build profiles, runtime packaging, and metadata |
| [0030](adr/0030-audio-authoring-and-bus-schema.md) | Serializable audio sources/listeners, stable clip references, and project bus graph |
| [0031](adr/0031-animation-authoring-runtime-contract.md) | glTF animation artifacts, stable controller states, runtime hydration, and exact-signature retargeting |
| [0032](adr/0032-versioned-navigation-bake-and-runtime-query.md) | Rerecast bake artifacts, Polyanya runtime queries, and editor/runtime ownership |
| [0033](adr/0033-dedicated-skinned-mesh-renderer.md) | Dedicated skinned renderer, static/skinned import boundary, and scene migration |
| [0034](adr/0034-registry-driven-authoring-components.md) | Stable component IDs, reflected lifecycle/history, composition, and independent active state |
| [0035](adr/0035-shared-material-assets-and-renderer-slots.md) | Shared Material/Material Instance assets, stable renderer slots, and runtime-only property blocks |
| [0036](adr/0036-surface-abi-and-solari-parity.md) | Constrained Surface ABI v1, raster/Solari evaluator parity, and deformed-geometry boundary |
## Editor framework
@@ -67,6 +72,10 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [editor/prefab-authoring.md](editor/prefab-authoring.md) | Linked instances, scoped overrides/source Apply, conflicts, variants, unpacking, and local conversion |
| [editor/audio-authoring.md](editor/audio-authoring.md) | Audio clips, source/listener authoring, audition, buses, runtime parity, and validation |
| [editor/animation-authoring.md](editor/animation-authoring.md) | glTF rigs/clips, controller states, preview, runtime requests, stable moves, and validation |
| [editor/navigation-authoring.md](editor/navigation-authoring.md) | Bounds/obstacles/areas/links, deterministic bake, overlay, path preview, and runtime queries |
| [editor/extensibility.md](editor/extensibility.md) | Static authoring component registration, lifecycle, composition, and history contract |
| [editor/material-system.md](editor/material-system.md) | Shared material assets and instances, renderer-slot assignment, Surface evaluators, migration, and diagnostics |
| [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
## Working plans (not canonical long-term)
@@ -83,6 +92,8 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans
| `jackdaw_feature_roadmap_*.plan.md` | Jackdaw-inspired production roadmap; tracked in Gitea as `BS-JD-*` issues |
| `blacksite_production_readiness_*.plan.md` | M6-M7 reliability, content production, shipping, and acceptance gates |
| `animation_authoring_*.plan.md` | M7 glTF skeletal animation import, preview, controller, and runtime acceptance |
| `navigation_authoring_*.plan.md` | M7 navigation bounds, deterministic bake, diagnostics, preview, and runtime query API |
| `renderer_material_component_foundation_*.plan.md` | Renderer/material slots, skinned pose lifecycle, Surface ABI, and component foundation |
## Crate responsibilities (quick reference)
+3 -1
View File
@@ -10,7 +10,9 @@ Level data must round-trip through save/load without leaking runtime ECS compone
## Decision
- **Authoring components** (`Primitive`, `StaticMeshRenderer`, `MaterialDesc`, `MaterialOverride`, `LightDesc`, `ModelRef`, `RigidBodyDesc`, `ColliderDesc`, legacy `PhysicsBody`, `ActorKind`, etc.) are the only components written to `.scn.ron`.
- **Authoring components** (`Primitive`, `StaticMeshRenderer`, `SkinnedMeshRenderer`,
`MaterialDesc`, `MaterialOverride`, `LightDesc`, `ModelRef`, `RigidBodyDesc`, `ColliderDesc`,
legacy `PhysicsBody`, `ActorKind`, etc.) are the only components written to `.scn.ron`.
- **Hydration** in `crates/shared/src/hydration/` generates runtime components in a fixed `Update` chain.
- **Save path** uses an explicit `DynamicSceneBuilder` allowlist and `strip_hydrated_entity` on each entity before serialize.
+4 -2
View File
@@ -2,7 +2,7 @@
## Status
Accepted
Partially superseded by [ADR 0034](0034-registry-driven-authoring-components.md).
## Context
@@ -12,7 +12,9 @@ Inspector panels were routed by `if world.get::<LightDesc>` and mixed with `bevy
- Every savable `LevelObject` carries a required **`ActorKind`** component (schema v2).
- One-shot **`ActorKind` backfill** runs in `crates/scene` migration v1→v2; load-time backfill is a fallback only for unsaved in-memory entities.
- **`validate_actor`** runs on save and rejects invalid component sets per kind.
- **`validate_actor`** runs on save and rejects invalid component sets per kind. ADR 0034 replaces
this authority model with component-owned validation while retaining `ActorKind` as a derived
compatibility/display hint.
- The default **Inspector** tab uses **`actor_inspector`** only (transform first, then authoring panels). No `ui_for_entity_with_children` in production builds.
## Consequences
@@ -8,7 +8,8 @@ Accepted
glTF/GLB and FBX previously entered the editor as imported scenes through `ModelRef`, with runtime hydration loading a format-specific `WorldAssetRoot`. That path is still useful for full scene playback, but it makes ordinary static mesh placement depend on source format behavior and prevents the inspector from exposing a stable renderer component.
The editor needs model drag/drop to create editable static mesh actors by default, while retaining an explicit scene-instance path for animation, skinning, cameras, and other full-scene data.
The editor needs model drag/drop to create editable static mesh actors for unrigged geometry while
retaining explicit, separate paths for skinned geometry and generic full-scene data.
## Decision
@@ -18,7 +19,11 @@ The saved scene authoring component is `StaticMeshRenderer`. Its slots reference
Asset import settings choose the default placement mode:
- `StaticAsset` creates `ActorKind::StaticMesh + StaticMeshRenderer`; when collider generation is enabled it also creates `RigidBodyDesc + ColliderDesc::StaticMesh`.
- `StaticAsset` creates `ActorKind::StaticMesh + StaticMeshRenderer` for unrigged sources; when
collider generation is enabled it also creates `RigidBodyDesc + ColliderDesc::StaticMesh`.
- Sources containing skin-bound primitives or animation route to
`ActorKind::SkinnedMesh + SkinnedMeshRenderer` and never create static renderer slots or
automatic triangle-mesh colliders (ADR 0033).
- `SceneInstance` creates the legacy `ActorKind::ImportedModel + ModelRef`.
Hierarchy mode is also stored per asset. `SingleActor` places all mesh parts into one renderer. `SourceHierarchy` creates an authored root with child static mesh actors.
@@ -28,5 +33,6 @@ Hierarchy mode is also stored per asset. `SingleActor` places all mesh parts int
- glTF/GLB and FBX placement consume the same renderer contract after processing.
- Scene files store renderer intent, not runtime Bevy mesh/material handles.
- Static mesh actors can expose renderer slots, source labels, shadows, collider policy, and material overrides in the inspector.
- Animated/skinned playback remains on the scene-instance path until a future animation authoring component exists.
- Skinned parts are marked in artifact schema v2 and excluded from static renderer construction and
hydration. Animation playback uses the dedicated contract in ADRs 0031 and 0033.
- Generated artifacts are project files but are hidden from the Asset Browser catalog to avoid treating them as levels/prefabs.
@@ -2,7 +2,9 @@
## Status
Accepted.
Partially superseded by [ADR 0034](0034-registry-driven-authoring-components.md) for component
lifecycle, active-state ownership, history, and composition. Material ownership is superseded by
the renderer-material ADR.
## Context
@@ -23,9 +25,8 @@ Component footer rather than an ad hoc button near Transform.
`ActorName`) and repeatable authoring items use `ComponentInstanceId`.
- Editor-visible actor components are described by an
`EditorComponentRegistry`; the Add Component footer reads from this registry.
- `InspectorOrder` stores editor component order plus per-component active
state. Collapse state is session-only UI state; active state is persisted with
the scene and is undoable.
- `InspectorOrder` stores editor component order. ADR 0034 moves persisted active state to
`AuthoringComponentStates`; collapse state remains session-only UI state.
- `StaticMeshRenderer` stores `MeshRenderSlot` values that reference imported
content-browser assets through `EditorAssetRef { asset_id, sub_asset_id,
label }`. Actor renderer data does not store source FBX/glTF paths.
+3 -1
View File
@@ -12,7 +12,9 @@ Jackdaw roadmap work needs blockout geometry that is editable as authored data,
Add `ActorKind::Brush` and `BrushDesc` as persisted shared authoring data. A brush stores convex polygon faces with stable face IDs, plane data, material/texture references, UV parameters, smoothing group, and shadow flags. The MVP supports additive cube brushes and hydrates active brush components into generated mesh children; generated children are stripped from saved scenes.
Brush actors conflict with `Primitive`, `StaticMeshRenderer`, `LightDesc`, and `ModelRef` in actor validation. Scene v1-to-v2 kind backfill infers `ActorKind::Brush` when an older level object contains `BrushDesc`.
Brush actors conflict with `Primitive`, `StaticMeshRenderer`, `SkinnedMeshRenderer`, `LightDesc`,
and `ModelRef` in actor validation. Scene v1-to-v2 kind backfill infers `ActorKind::Brush` when an
older level object contains `BrushDesc`.
## Consequences
@@ -6,8 +6,8 @@ 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
Blacksite previously recorded animation and skin counts while importing glTF and FBX models, but the
authored scene contract contained only a path-based `ModelRef`. Generic scene-instance hydration loaded a
model world without selecting or driving its clips, and the editor has no stable clip references,
controller inspector, preview, or compatibility validation.
@@ -32,12 +32,12 @@ Each animated model has a versioned generated manifest under `assets/animations/
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
ID is authoritative; cached `SkinnedMeshRenderer` 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
types. A controller sits beside the dedicated `SkinnedMeshRenderer` 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.
@@ -50,7 +50,13 @@ stored in the manifest are display metadata and never compatibility keys. Blacks
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-manifest schema v3 adds an optional stable default clip sub-asset ID sourced from model
import settings. It is an explicit presentation policy: renderable animated-model placement creates
a one-state controller only when this ID resolves. An absent value preserves the imported node pose;
the importer and placement workflow never infer a first clip. Generic scene-instance placement does
not consume this setting.
The runtime adapter waits for the renderer's `HydratedSkinnedMeshRoot` 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
@@ -61,6 +67,14 @@ authored/default crossfade. Invalid state requests are rejected without disturbi
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.
When a hydrated hierarchy becomes ready, the runtime captures its descendant `Transform` and
`MorphWeights` components before evaluating authored playback. Edit mode samples the configured
default state at its range start and pauses it. Preview stop, controller removal, failed graph
reconfiguration, and PIE exit first stop playback and restore the captured baseline; if a valid
default remains, it is then sampled again without a crossfade. Skin validation checks each imported
skin independently for joint/inverse-bind count and hierarchy ownership, including sources that
reuse one joint hierarchy across multiple skin records.
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.
@@ -79,9 +93,15 @@ the rigs into separate assets or export all clips beneath one common root.
- 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.
- Explicit edit-rest clips avoid malformed source presentation poses without coupling rendering to
animation; assets without a configured clip keep their imported rest pose.
- Baseline restoration prevents stopped previews and mode changes from leaving sampled transforms or
morph weights behind.
- 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.
- The static/skinned renderer boundary and v2-to-v3 scene migration are defined by
[ADR 0033](0033-dedicated-skinned-mesh-renderer.md).
@@ -0,0 +1,36 @@
# ADR 0032: Versioned Navigation Bake And Runtime Query
## Status
Accepted
## Context
Blacksite needs a production navigation workflow on Bevy 0.19. Current high-level Bevy navigation
plugins target older Bevy releases, while baking and pathfinding are difficult, established domains
that should not be reimplemented locally. The editor also cannot own the runtime query contract:
packaged games and headless validation must consume the same data and behavior.
## Decision
Use the engine-independent Rerecast crate for deterministic 3D walkable-surface generation and
Polyanya for any-angle path queries. Blacksite owns reflected authoring components and a versioned
generated artifact under `assets/navigation/generated/`. The artifact records the source scene,
source fingerprint, agent profile, baked mesh, links, bounds, and diagnostics.
The scene crate owns fingerprinting, bake artifact IO, and validation. The game crate owns artifact
loading and path queries. Editor bake controls, overlays, and path preview call those shared/game
contracts and keep all visual helpers transient. Relevant authored geometry changes mark the
artifact stale; V1 debounces a full deterministic rebuild and reports the affected region until
Rerecast provides production-ready tiled regeneration.
## Consequences
- Navigation remains usable on Bevy 0.19 without forking an older Bevy integration crate.
- Rerecast and Polyanya versions become explicit serialized-artifact compatibility inputs; schema
migration or rebaking is required when their representation changes.
- Static navigation and explicit links ship first. Runtime obstacle carving, crowd avoidance, and
partial tile rebuilding remain future work.
- Primitive and additive-brush triangles are deterministic source geometry. Imported static meshes
use authored navigation obstacles until their normalized artifacts expose collision triangles.
- Runtime code never depends on editor UI state, and authored scenes never contain bake visualizers.
@@ -0,0 +1,60 @@
# ADR 0033: Dedicated Skinned Mesh Renderer
## Status
Accepted
## Context
The normalized model artifact originally exposed every imported primitive to
`StaticMeshRenderer`, including primitives with joint indices and weights. Whole-model static
placement could therefore detach rigged geometry from its joints and render it in bind pose. The
animation workflow avoided individual skinned-part placement, but it still represented animated
geometry as generic `ImportedModel + ModelRef`, leaving no authoring boundary between an arbitrary
source scene and geometry that requires a skeleton hierarchy.
Static, generic scene-instance, and skinned rendering have different ownership rules. Static parts
can be flattened into independent slots and triangle-mesh colliders. A skinned mesh must retain the
source joints, inverse bind poses, animation player, and hierarchy. A generic scene instance may
contain cameras, lights, or other source data and does not imply an animation contract.
## Decision
Rigged geometry uses `ActorKind::SkinnedMesh + SkinnedMeshRenderer`. The renderer stores stable
asset identity, cached source path, and source scene index. Its dedicated hydration system creates a
`HydratedSkinnedMeshRoot` and instantiates the complete source hierarchy so Bevy owns the runtime
`SkinnedMesh`, joints, inverse bind poses, and animation-player placement. The animation runtime
binds only to this dedicated root. `AnimationControllerDesc` is valid only beside a
`SkinnedMeshRenderer`.
Renderer hydration itself remains animation-agnostic. The animation adapter captures the imported
hierarchy baseline when that root becomes ready and optionally drives the explicit default clip
recorded by animation-manifest schema v3. Without a controller, the dedicated renderer remains at
the captured imported pose.
Static-mesh artifact schema v2 marks every part as skinned or unskinned. Static renderer creation
filters out skinned parts and all geometry from an animated source; static hydration enforces the
same rule even if a scene contains a hand-authored slot. Automatic renderable-model placement
chooses `SkinnedMeshRenderer` when any source part is skin-bound or the source contains animation,
and otherwise chooses `StaticMeshRenderer`. Placing a skinned or animated subasset
places its owning model through the dedicated renderer; it never creates a detached static slot.
`ImportedModel + ModelRef` remains the explicit generic scene-instance path. It is not the animation
renderer. Scene schema v3 migrates v2 entities containing both `ModelRef` and
`AnimationControllerDesc` to `SkinnedMeshRenderer + ActorKind::SkinnedMesh`; unrelated imported
scene instances remain unchanged.
Automatic triangle-mesh collider generation applies only to static renderers. Animated collision
must be authored explicitly with stable gameplay shapes or hitboxes rather than a deforming render
surface.
## Consequences
- Static renderer slots can no longer silently accept newly imported skinned or animated geometry.
- Rigged models retain the exact hierarchy Bevy needs for skinning and animation playback.
- Generic scene instances, static meshes, and skinned meshes have distinct persisted components,
actor kinds, hydration markers, validation, and editor presentation.
- A source containing both rigid and skinned nodes is placed as one skinned actor so the imported
hierarchy remains coherent; splitting it requires separate source assets.
- FBX skinning and animation remain blocked by ADR 0031 until the FBX loader can build the same
runtime hierarchy and clip contract as glTF.
@@ -0,0 +1,45 @@
# ADR 0034: Registry-driven authoring components
## Status
Accepted
## Context
The Add Component palette was registry-backed, but presence checks, copy/paste, reset, removal,
history, save filtering, validation, and most inspector dispatch were duplicated as Rust `match`
statements. `InspectorOrder` also stored active state, causing hydration and game systems to depend
on editor presentation metadata. `ActorKind` was used as validation authority, which prevented
otherwise valid component composition such as a rendered mesh that also emits light.
## Decision
- Every authoring component registration has an immutable editor/protocol ID separate from its
reflected Rust type path. Startup validation rejects duplicate IDs/types, missing reflection
adapters, and unknown recommendation/conflict references.
- Bevy reflection supplies generic presence, default insertion/reset, removal, copy/paste, and RON
values for atomic `ComponentTransaction` history. A transaction includes the derived
`ActorKind` hint so one undo restores the complete component edit.
- The registry builds the scene component allowlist. A statically linked extension uses
`register_authoring_component` to register reflection metadata, lifecycle metadata, and an
inspector callback together.
- Persisted `AuthoringComponentStates` owns component active state. `InspectorOrder` owns only card
ordering. Schema-v3 state embedded in `InspectorOrder` is moved lazily and remains a read fallback
during migration.
- `ActorKind` remains serialized for compatibility and presentation, but is derived from component
composition on load and component transactions. Validation enforces component data and explicit
geometry-source conflicts rather than comparing behavior with the stored hint. Compatible
components, including mesh plus light, may coexist.
## Consequences
- New statically linked authoring components participate in save filtering and generic component
operations without adding editor-core history or persistence branches.
- Runtime systems read active state independently from inspector layout. Old scenes preserve their
disabled components and upgrade in memory before their next save.
- Geometry source conflicts remain explicit, while presentation categories no longer prohibit
unrelated behavior composition.
- Existing whole-entity spawn/duplicate snapshots still have typed fields. Moving those snapshots
and every built-in inspector renderer to the reflected registry is follow-up work; the generic
transaction path is the required path for new component operations.
@@ -0,0 +1,60 @@
# ADR 0035: Shared Material Assets and Renderer Slots
## Status
Accepted
## Context
Renderer material authoring previously mixed copied `MaterialDesc` values, imported source-material
defaults, and static-mesh draw data. That made a renderer's ownership unclear, encouraged material
copies per actor, and left rigged geometry without the same assignment model as static geometry.
Matching imported materials by a display name was also unsafe: names are neither unique nor stable
when a model is reimported.
Static and skinned renderers need the same Unity-like authoring contract without sharing their mesh
or hydration components. A project material must be reusable, an instance must express explicit
overrides over one base material, and each renderer must expose stable material slots independently
from its draw or skeleton representation.
## Decision
- Project materials use versioned `MaterialAsset` documents. A `MaterialInstanceAsset` references
one direct base `MaterialAsset` and stores parameter and texture overrides. Nested material
instances are invalid.
- `MaterialRef` is the assignment type. Its registry UUID and subasset ID are authoritative;
`source_path` is a cached loading hint that validation or migration may repair after a move.
- `StaticMeshRenderer` and `SkinnedMeshRenderer` each own a `RendererMaterialSet`. They do not share
a mesh component or hydration path. Each `RendererMaterialSlot` has a stable ID, a presentation
name, a read-only imported `source_material`, and an optional explicit `material` assignment.
Explicit assignment wins; clearing it returns to the imported source material.
- Static draw parts and imported skinned-hierarchy draws bind to material slots by stable IDs.
Reimport reconciles by ID only. An explicit assignment whose source slot disappears is retained as
an `OrphanedMaterialAssignment`; the editor never silently reconnects it by display name.
- Asset Browser **Apply Material** assigns a shared material or material instance to every material
slot on each selected static or skinned renderer. Renderer inspectors provide per-slot
Browse/Select/Locate/Clear controls and expose orphan warnings.
- `HydratedRendererMaterialBinding` identifies each runtime draw's owner, slot, and effective
material. A skinned renderer material-only edit patches the instantiated hierarchy without
reloading its source hierarchy or joints.
- `MaterialPropertyBlocks` are runtime-only, per-slot overrides. They do not mutate a shared asset
and are excluded from scene and prefab persistence. Persisting a reusable variation requires an
explicit material instance.
- Scene schema v4 migrates legacy renderer assignments into `RendererMaterialSet`. Project material,
material-instance, shader-schema, and scene rewrites are performed by the explicit transactional
`cargo upgrade-project` command; ordinary loading remains read-only.
## Consequences
- Static and skinned renderers have a consistent material-slot workflow while retaining distinct
geometry ownership and hydration behavior.
- An assignment remains a reference rather than a copied material value, so editing or replacing a
shared asset does not create actor-local material copies. Material/base/schema/evaluator
dependency revisions update the shared runtime handle in place across all assigned slots.
- Source reimport cannot silently move an override to the wrong draw. Orphans require an explicit
user decision to reassign or discard.
- Legacy primitive/actor `MaterialDesc` paths remain compatibility paths until their consumers move
to renderer slots; new mesh-renderer work uses shared references.
- Runtime property blocks have no editor promotion workflow yet.
- Material graph authoring, nested instances, blended/transmissive materials, and a generalized
per-renderer property-block inspector are outside this decision.
@@ -0,0 +1,72 @@
# ADR 0036: Surface ABI v1 and Solari Evaluator Parity
## Status
Accepted
## Context
Arbitrary full-pipeline WGSL cannot be carried safely between Bevy's raster pipelines and Solari's
ray-hit shaders. A custom fragment shader may own bindings, entry points, derivatives, discard, or
other stage-specific behavior that has no direct ray-tracing equivalent. Treating such a shader as
a `StandardMaterial` in Solari would produce a different material, while tracing skinned source
vertices would produce bind-pose geometry instead of the rasterized deformation.
Blacksite needs one constrained material expression that can produce the same surface values in
forward/deferred raster rendering and at Solari ray hits, while leaving transforms, skinning,
lighting, fog, shadows, and render-pipeline bindings under engine ownership.
## Decision
- `blacksite_surface` owns versioned Surface ABI v1. A custom evaluator implements:
```wgsl
fn evaluate(
input: SurfaceInput,
params: SurfaceParams,
samples: SurfaceSamples,
) -> Surface
```
`SurfaceInput` provides UV0, world position, and world normal. `Surface` returns base color,
tangent-space normal, emissive, metallic, perceptual roughness, reflectance, occlusion, alpha,
and lit/unlit model selection.
- The ABI has 16 `vec4` parameter lanes, eight sampled 2D texture slots with UV transforms, and a
400-byte `SurfaceUniform`. Shader schemas map typed Bool/Float/Vec2/Vec3/Color/Enum properties and
texture properties into that fixed layout. Exceeding either limit is a validation error.
- Evaluators cannot declare bindings or shader entry points and cannot use compute/storage,
ray-query, derivative, discard, barrier/subgroup, texture-store, or atomic constructs. The engine
supplies resources, entry points, vertex transforms/skinning, lighting, fog, and shadows.
- Raster rendering composes the evaluator between the engine-owned Surface header and footer and
installs it as an `ExtendedMaterial<StandardMaterial, SurfaceExtension>` for forward, deferred,
and prepass pipelines. Tangent-space normals are applied when the mesh supplies tangents.
- The maintained `third_party/bevy_solari` fork packs the same uniform and texture set, namespaces
validated evaluator functions, and generates a shader-ID dispatch library for ray hits. Eligible
non-deformed geometry uses the evaluator for hit material fields, tangent-space normal, emissive,
unlit behavior, and cutout candidate acceptance.
- Opaque and cutout are the supported alpha modes. Solari treats geometry as potentially
non-opaque and evaluates the exact Surface alpha and cutoff before accepting a cutout ray
candidate.
- Plain materials without a custom evaluator keep Bevy's standard raster and Solari material path.
Dependency revisions cover Material Instances, their direct base, shader schema, and evaluator.
Naga syntax/semantic validation and the cross-pipeline restrictions run before installation;
invalid updates produce diagnostics and retain the last successfully installed evaluator/library.
- Meshes with `SkinnedMesh`, runtime morph weights, or morph targets are excluded from Solari until
an instance-keyed deformed-vertex and BLAS update path exists. They continue to render through
Bevy's raster path; Solari diagnostics report the exclusion. No bind-pose ray-tracing fallback is
allowed.
## Consequences
- Custom material code is portable because it describes a surface, not an entire render stage.
- Raster and Solari evaluate the same source for supported, Solari-eligible static or rigid
geometry. Normal parity requires tangents; Solari compatibility diagnostics identify missing
tangents and other unsupported mesh layouts.
- Dynamic skinned/morph Solari geometry remains deliberate future work. This is a geometry parity
limit, not permission to substitute source/bind-pose vertices.
- ABI layout or semantic changes require a new version and migration. The fixed lanes and texture
count trade arbitrary resource layouts for deterministic cross-renderer packing.
- Blend, transmission, refraction, custom vertex displacement, arbitrary entry points, and
stage-specific shader behavior are unsupported by Surface ABI v1.
- Maintaining evaluator parity requires carrying the focused Solari fork until the necessary hooks
exist upstream; its dispatch and cutout behavior are covered by local tests.
@@ -36,6 +36,8 @@ Each actor should contain:
Actor
ActorName
InspectorOrder
AuthoringComponentStates
ActorKind // derived compatibility/display hint
```
Use stable IDs for save files:
@@ -59,6 +61,7 @@ Every editor-visible component should be registered.
```rust
pub struct EditorComponentDescriptor {
pub id: &'static str, // stable editor/protocol identity
pub type_name: &'static str,
pub display_name: &'static str,
pub addable: bool,
@@ -69,12 +72,19 @@ pub struct EditorComponentDescriptor {
The registry controls:
- Scene persistence and reflected presence
- Visibility
- Addability
- Removal rules
- Custom inspectors
- Search metadata
- Categories
- Requirements, recommendations, and conflicts
Add, remove, reset, copy/paste, and extension-owned edits use reflected
`ComponentTransaction` history. All component deltas plus the derived `ActorKind` update are one
undo step. See [the extensibility guide](extensibility.md) and
[ADR 0034](../adr/0034-registry-driven-authoring-components.md).
## Inspector Layout
@@ -183,6 +193,9 @@ Asset selector requirements:
## Static Mesh Renderer
This renderer is restricted to unrigged, non-animated geometry. Imported parts marked skinned, or
parts from a source containing animation, are not valid static slots.
Recommended structure:
```rust
@@ -222,6 +235,24 @@ Static Mesh Renderer
Collapsed slots reduce inspector height.
## Skinned Mesh Renderer
Rigged, skin-bound, or animated model geometry uses a separate asset-owned renderer:
```rust
pub struct SkinnedMeshRenderer {
pub asset_id: String,
pub path: String,
pub scene_index: usize,
}
```
It has no independent static slots. Hydration instantiates the source hierarchy beneath a
`HydratedSkinnedMeshRoot`, retaining Bevy joint entities, inverse bind poses, `SkinnedMesh`
bindings, and animation-player placement. The inspector shows the source, scene, and stable asset
ID; source reassignment happens through asset placement rather than field-by-field mesh editing.
`AnimationControllerDesc` is an optional sibling component and requires this renderer.
## Property Drawing
Generic reflection is the fallback.
@@ -230,6 +261,7 @@ Custom inspectors should exist for:
- Transform
- Static Mesh Renderer
- Skinned Mesh Renderer
- Materials
- Physics
- Audio
+16 -6
View File
@@ -20,6 +20,10 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| [prefab-authoring.md](prefab-authoring.md) | Stable nested overrides, source Apply/conflicts, variants, unpacking, and local conversion |
| [audio-authoring.md](audio-authoring.md) | Audio clip placement, source/listener controls, audition, buses, runtime parity, and validation |
| [animation-authoring.md](animation-authoring.md) | glTF rig/clip import, stable controller states, preview, runtime API, and validation |
| [navigation-authoring.md](navigation-authoring.md) | Bounds, source geometry, deterministic bake, viewport path preview, and runtime query workflow |
| [extensibility.md](extensibility.md) | Static authoring component lifecycle registration, stable IDs, composition, and generic history |
| [material-system.md](material-system.md) | Shared Material/Material Instance assets, static/skinned renderer slots, Surface ABI, Solari scope, and migration |
| [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation |
## Subsystems (code → doc)
@@ -32,6 +36,9 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| `play/` | PIE session, editor mode state | architecture.md |
| `play/audio_preview.rs` / `game::audio` | Non-dirty editor audition and authored runtime playback/bus adapter | audio-authoring.md, ADR 0030 |
| `assets/animation.rs` / `ui/animation_inspector.rs` / `game::animation` | Generated animation manifests, controller authoring/preview, and runtime state adapter | animation-authoring.md, ADR 0031 |
| `ui/navigation_inspector.rs` / `scene::navigation` / `game::navigation` | Navigation authoring, deterministic bake artifacts, viewport preview, and runtime path queries | navigation-authoring.md, ADR 0032 |
| `assets/materials.rs` / `shared::renderer_material` / `shared::hydration::{static_meshes,skinned_meshes}` | Shared material discovery, stable renderer slots, and draw binding | material-system.md, ADR 0035 |
| `blacksite_surface` / `game_hot::rendering::solari` / `third_party/bevy_solari` | Surface ABI packing, raster composition, Solari evaluator dispatch, and deformation eligibility | material-system.md, rendering.md, ADR 0036 |
| `assets/` | Catalog, asset DB, static mesh artifacts, `thumbnails/`, `materials.rs`, prefab overrides v2 | this file (below), prefab-authoring.md, ADR 0017, ADR 0027 |
| `shared::prefab_overrides` | Versioned stable override schema and editor-independent runtime application | prefab-authoring.md, ADR 0027 |
| `project/` | Workspace, settings UI, user prefs, support diagnostics | roadmap Phase 1 |
@@ -41,7 +48,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| `ext/` | Command palette, BRP, game panel adapters | ADR 0007 |
| `ui/mod.rs` | Dock layout, unified viewport, menus | README controls |
| `ui/scene_tabs.rs` | Main-toolbar scene tabs and composition controls | multi-scene-composition.md, ADR 0026 |
| `ui/component_registry.rs` | Editor-visible component descriptors and Add Component palette metadata | ADR 0018 |
| `ui/component_registry.rs` | Stable authoring component identities, lifecycle metadata, save policy, and inspector callbacks | extensibility.md, ADR 0034 |
| `ui/asset_browser/` | Asset Browser tree, grid/list, details | roadmap Phase 4b |
| `history/` | Undo/redo command stack | README controls |
| `crates/scene` | Schema stamp/migrate/validate (shared) | ADR 0006, ADR 0008 |
@@ -57,23 +64,26 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
- **Unified viewport** uses one render-to-texture target for both the editor fly camera and the possessed player camera so HDR/atmosphere is not broken by sub-viewport cropping.
- **PIE:** F8 possess/eject while sim runs; **F6** pauses/resumes simulation in Play; project settings drive shared rendering for the active viewport camera.
- **Asset browser** mirrors the on-disk `assets/` directory with project tree, breadcrumb, search/filter/sort, grid/list views, texture/model/material thumbnails, a details pane, and context-aware row/menu actions; narrow docks prioritize content, keep the root panel fixed, switch list view to a compact single-column layout, and hide tree/details panes when they would crowd the content area. The footer stays pinned while only the project tree, asset content, and details panels scroll. **Built-ins** holds spawnable primitives and lights. **Materials** folder scans `assets/materials/*.ron`, renders material thumbnails on a sphere using `MaterialDesc`, and exposes shader-schema-driven parameters/textures in the details editor; **Shaders** holds shader schema RON files. **Audio** accepts Bevy-supported Ogg/Vorbis and Speex (`.ogg`, `.oga`, `.spx`), WAV, MP3, and FLAC clips under `assets/audio/`, with a dedicated filter, waveform icon, format/file details, and stable registry-backed references that retain a runtime source path. glTF/GLB/FBX rows can expand into a shelf of normalized embedded mesh, material, and texture subassets with independent generated thumbnails. Mesh subassets can be selected, dragged into the viewport, or placed from details/context menus; material subassets render source-material spheres; texture subassets can be applied to the selected actor. Model import settings are staged with **Apply** / **Revert**, asset context menus can regenerate thumbnails, material asset details edit shared `MaterialAsset` fields, and file asset deletion moves sources/generated artifacts into `assets/.trash/`. Before thumbnail loading, glTF sources preflight local external buffers/images and show a stable non-retryable failure state when a dependency is missing instead of repeatedly invoking the asset loader.
- **Static mesh renderer** — model drag/drop defaults to `ActorKind::StaticMesh + StaticMeshRenderer` using normalized artifacts under `assets/meshes/generated/`. Renderer slots store imported `EditorAssetRef` mesh/material references, not source FBX/glTF paths. `SceneInstance` placement keeps the legacy `ImportedModel + ModelRef` path for full scene playback.
- **Animation authoring** — glTF/GLB imports generate UUID-keyed rig/clip manifests and expandable skeleton/clip shelves. Clip drag creates an animated actor or adds one exact-signature-compatible state to a selected imported model through typed history. `AnimationControllerDesc` exposes named states, ranges, loop/speed, default/crossfade, and non-dirty runtime-backed preview; project validation resolves the same stable refs and blocks animated/skinned FBX with conversion guidance. Production acceptance remains open in Gitea #46. See [animation-authoring.md](animation-authoring.md) and [ADR 0031](../adr/0031-animation-authoring-runtime-contract.md).
- **Static/skinned renderer split** — model drag/drop uses normalized artifacts under `assets/meshes/generated/`. Unrigged, non-animated sources create `ActorKind::StaticMesh + StaticMeshRenderer`; skin-bound or animated sources create `ActorKind::SkinnedMesh + SkinnedMeshRenderer` and preserve the imported hierarchy. Static slots never contain marked skinned primitives or geometry from animated sources. `SceneInstance` placement keeps `ImportedModel + ModelRef` for generic full-source scenes. See [ADR 0033](../adr/0033-dedicated-skinned-mesh-renderer.md).
- **Animation authoring** — glTF/GLB imports generate UUID-keyed rig/clip manifests and expandable skeleton/clip shelves. Clip drag creates a skinned actor or adds one exact-signature-compatible state to a selected skinned actor through typed history. `AnimationControllerDesc` exposes named states, ranges, loop/speed, default/crossfade, and non-dirty runtime-backed preview; project validation resolves the same stable refs and blocks animated/skinned FBX with conversion guidance. Production acceptance completed in Gitea #46. See [animation-authoring.md](animation-authoring.md) and [ADR 0031](../adr/0031-animation-authoring-runtime-contract.md).
- **Navigation authoring** — bounds, obstacles, areas, and links use typed history and viewport visualizers. Rerecast produces a versioned fingerprinted artifact; Polyanya powers both editor path preview and the game-owned runtime API. The existing horizontal toolbar path button creates or bakes bounds, while Scene > Navigation exposes the complete workflow. See [navigation-authoring.md](navigation-authoring.md) and [ADR 0032](../adr/0032-versioned-navigation-bake-and-runtime-query.md).
- **Brush authoring** — `ActorKind::Brush + BrushDesc` stores persisted convex blockout faces, validates authored geometry in the inspector and Window → Brush Diagnostics, and hydrates active valid brushes into generated mesh children. See [brushes.md](brushes.md).
- **Draw Brush** — `B`, toolbar pencil, or command `brush.draw` enters a floor-polygon draw mode. LMB places snapped points, Backspace removes the last point, Enter locks the outline for height editing, mouse up/down adjusts height, and Enter/LMB creates additive prism brushes through history. Esc/right-click cancels. Simple concave outlines decompose into convex brush parts; self-intersections remain blocked.
- **Brush edit modes** — with a brush selected, `1`/`2`/`3`/`4` enter vertex, edge, face, and clip element modes. Element modes show brush handles in the viewport, own LMB picking, support Shift multi-select, show a mode badge, and Esc returns to object mode. Vertex/edge/face selections use the standard `W`/`E`/`R` gizmo at the element pivot and commit undoable `SetBrush` edits. Clip previews a bounds-based half-brush and commits with Enter; command-palette intersect, convex merge, and subtract operations use the same preview/commit lifecycle for conservative cuboid/prism blockout.
- **Collider split** — imported mesh collision lives in a separate `ColliderDesc::StaticMesh` plus optional `RigidBodyDesc`; renderer slots own only render visibility, shadows, mesh, and material references.
- **Material assets** — `MaterialAsset` RON (`label` + `MaterialDesc`) is shader-schema aware. Actor material edits live on the actor `MaterialDesc`; static mesh slot material refs are source/default selectors, and content-browser asset inspectors are the path for editing shared material assets.
- **Material assets and renderer slots** — Material and direct-base Material Instance documents are shared assets. `StaticMeshRenderer` and `SkinnedMeshRenderer` each own stable material slots with imported source defaults and explicit shared assignments; Clear returns to the source default, while reimported missing slots retain overrides as orphans instead of matching by name. Runtime-only property blocks never mutate or persist into the shared asset. Custom Surface evaluators use the same constrained ABI for raster and Solari-eligible non-deformed geometry; skinned/morph geometry is deliberately excluded from Solari until deformed BLAS updates exist. See [material-system.md](material-system.md), [ADR 0035](../adr/0035-shared-material-assets-and-renderer-slots.md), and [ADR 0036](../adr/0036-surface-abi-and-solari-parity.md).
- **Prefab authoring** — shared `PrefabOverrides` targets generated actors by nested anchor chain plus stable `ActorId`, and applies reflected property/component plus same-layer structural operations in editor and game hydration. The editor supports scoped Revert and transactional **Apply to source** with three-way conflict checks, exact-file undo guards, and recoverable changed/broken/conflict states. `HydratedPrefabMember` keeps generated content out of owner serialization; linked-root saves retain local structure as variants. **Unpack Layer** preserves nested links, while **Convert to Local** recursively removes them. See [prefab-authoring.md](prefab-authoring.md) and [ADR 0027](../adr/0027-stable-prefab-ownership-and-variants.md).
- **Visual language** uses a near-black industrial shell, a compact Blacksite identity mark, restrained amber actions/primary selection, cyan secondary selection, semantic status colors, stable grouped controls, and shared elevated viewport chips. Primary/secondary selection roles remain consistent across hierarchy rows, viewport x-ray shells/corner brackets, the selection HUD, and transform interactions. See [visual-language.md](visual-language.md).
- **Hierarchy** shows authored objects plus useful runtime context (`Player`, `PlayerCamera`, Project Sun). Ordinary runtime rows remain read-only; generated prefab rows expose override-aware inspection and same-layer remove/reparent actions while rejecting cross-instance/layer and composition-boundary drops. Locks prevent selection, gizmos, drag participation, structural targets, and mutating context actions. Authored reparenting preserves world placement and records parent/local-transform/manual-order changes as one undoable command.
- **Player placement** is authored through `PlayerSpawn`; selecting the runtime player in Edit mode redirects to a saved `Player Start`.
- **World lighting** has two layers: project default sun/ambient settings, and optional scene-authored directional `LightDesc` overrides. **Scene → Lighting** menu and **Rendering** panel (Window) restore project sun or bake a scene directional from project settings. **Apply** in Project Settings updates ambient and sun illuminance live.
- **Rendering** — `GiMode` + post-process volumes; see [rendering.md](rendering.md). **Window → Rendering** shows requested/effective active-camera stack, fallback reason, Solari eligibility, viewport GI badge, and volume HUD.
- **Inspector** shows a responsive header, **Transform**, registered authoring component cards, and an Add Component footer (`actor_inspector`) that expands an inline search shelf above the button; only the component body scrolls. Rows wrap or stack inside narrow docks instead of forcing the panel wider, and legacy authoring sections use the same component-card shell. Component card carets collapse/expand for the current editor session, status dots toggle persisted active state, and triple-dot menus provide reset, copy/paste values, move, remove, and documentation slots. Inactive authoring components remain in the scene but are skipped by hydration/runtime queries, stripping their generated meshes, lights, physics, or post-process effects. The Add Component shelf is registry-driven with persistent search, category groups, descriptions, hydration hints, duplicate/conflict disabled states, and recommendation hints. `StaticMeshRenderer` uses concept-style slot cards with model thumbnails, imported mesh/source-material selectors, visibility, and shadow flags. Actor material authoring lives in the `Authoring Material` component, whose texture refs use Asset Browser picker/drop controls. Empty source material refs display the inherited source material from the generated static mesh artifact as **Source default**; selector **Browse** assigns explicit normalized imported sub-assets, **Locate** focuses the owning asset in the Asset Browser, and **Clear** returns optional material slots to the inherited source default. `ColliderDesc` and `RigidBodyDesc` are separate component cards. Game crates add sections via `ActorInspectorSection` + `game::editor_ext::actor_inspector_section_ids()`.
- **Inspector** shows a responsive header, **Transform**, registered authoring component cards, and an Add Component footer (`actor_inspector`) that expands an inline search shelf above the button; only the component body scrolls. Rows wrap or stack inside narrow docks instead of forcing the panel wider, and legacy authoring sections use the same component-card shell. Component card carets collapse/expand for the current editor session, status dots toggle persisted `AuthoringComponentStates`, and triple-dot menus provide registry-backed reset, copy/paste values, move, remove, and documentation slots. `InspectorOrder` controls presentation only. The Add Component shelf is registry-driven with persistent search, category groups, descriptions, hydration hints, duplicate/conflict disabled states, and recommendation hints. Static game/editor extensions register reflected lifecycle metadata and their inspector together; see [extensibility.md](extensibility.md) and [ADR 0034](../adr/0034-registry-driven-authoring-components.md).
- **Command palette** (`Ctrl+P`): opens centered, clears and focuses the filter, selects the first result, searches both human-facing labels and stable command IDs, and supports arrow-key selection and Enter to run. Commands include `scene.reset_lighting`, `brush.draw`, `brush.subtract`, `brush.intersect`, `brush.merge_convex`, `rendering.create_volume`, `rendering.select_volumes_at_camera`, `rendering.focus_active_volumes`, `selection.group`, `selection.focus`, `selection.reset_transform`, and play commands.
- **Editor input routing** gives egui text fields first claim on keyboard input. Viewport shortcut keys require viewport pointer focus and are suspended while RMB/MMB camera navigation is active.
- **ActorKind** is required on saved level objects (schema v2). Save strips hydrated ECS before writing `.scn.ron`.
- **ActorKind** remains required as a saved compatibility/display hint, is repaired from primary
components on load and component transactions, and does not prohibit compatible composition such
as renderer plus light. Component validation owns requirements and geometry-source conflicts.
- **Scene persistence and recovery** use transactional same-directory writes for authored scenes and bounded user-local recovery snapshots for dirty saved scenes. Recovery runs every 120 seconds by default, keeps five generations, never marks the scene clean, and appears as a status/File-menu restore or discard action when newer than the authored file. Restore leaves the original scene dirty until manually saved. See [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
- **Scene visualizers** expose actor root icons, colliders, lights, player spawns, gameplay markers, volumes, prefab/model anchors, Project Sun, and runtime player/camera markers without changing saved scene data. Spot lights show inner/outer cones and cameras show near/far frusta. Viewport options independently gate visualizer categories and include actor icon and transform-gizmo size sliders.
- **Clean game-view overlay** (`G`) hides editor chrome, grid, selection outlines, transform gizmos, actor root icons, visualizers, and selectable proxies without changing camera ownership; `Ctrl+G` toggles grid.
+28 -14
View File
@@ -15,15 +15,22 @@ mesh artifact. Expanding a model row shows:
- animation clips with duration and event count;
- mesh, material, and texture entries from the static import contract.
Model Import Settings also exposes **Default animation**. Choosing a clip stores its stable
sub-asset ID and makes normal renderable-model placement create a one-state controller for that
exact clip. The editor samples the clip at its authored range start and pauses it as the edit-mode
rest presentation. **Imported rest pose** creates no controller and preserves the source node pose;
Blacksite never guesses the first clip. Generic Scene Instance placement remains animation-free.
Skeleton rows are inspect-only. Dragging an animation clip into the viewport creates one
`ImportedModel` actor with a stable `ModelRef` and `AnimationControllerDesc` and selects it for
immediate inspection. When an imported-model actor is selected, the same drag assigns the clip as a
`SkinnedMesh` actor with a stable `SkinnedMeshRenderer` and `AnimationControllerDesc` and selects it for
immediate inspection. When a skinned-mesh actor is selected, the same drag assigns the clip as a
new controller state instead. Assignment is one undoable command and requires an exact
skeleton-signature match.
Skinned primitive rows are inspect-only because their vertex data requires the source skin
hierarchy. Their thumbnails render the complete source scene, and drag/place actions direct authors
to place the model or an animation clip instead of creating an invalid detached mesh.
Skinned primitive rows place their owning model through `SkinnedMeshRenderer` because their vertex
data requires the source skin hierarchy. Their thumbnails render the complete source scene; no
drag, details action, or context-menu action can create an invalid detached static-mesh slot.
Unrigged primitives continue to place independently through `StaticMeshRenderer`.
## Controller Inspector
@@ -35,7 +42,10 @@ and property changes use typed editor history and participate in scene dirty tra
The Preview section selects a state, plays or pauses it, stops playback, and scrubs within the
authored range. Preview requests use the game runtime adapter and do not change the controller,
history, or scene dirty state. Entering PIE clears any paused edit-mode scrub so the authored
default state can run; leaving PIE clears transient playback while retaining authored data.
default state can run; leaving PIE clears transient playback while retaining authored data. The
runtime captures imported descendant transforms and morph weights before evaluating animation.
Stop, controller removal, invalid graph rebuild, and PIE exit restore that baseline before the
configured edit-rest state is sampled again, so a preview cannot strand the actor in its last pose.
## Runtime API
@@ -51,31 +61,34 @@ game::animation::request_animation_state(
An omitted crossfade uses the controller default. Invalid actor or state requests return an error
and preserve current playback. If edited controller data cannot rebuild its runtime graph, the old
graph is stopped and cleared instead of continuing stale playback. `AnimationGraph`,
`AnimationPlayer`, transitions, preview state, and hydrated model roots are runtime-only and never
`AnimationPlayer`, transitions, preview state, and hydrated skinned-mesh roots are runtime-only and never
serialize into authored scenes.
## Stable Identity And Moves
`ModelRef`, skeleton references, and clip references carry the model registry UUID. Generated
`SkinnedMeshRenderer`, skeleton references, and clip references carry the model registry UUID. Generated
artifacts are keyed by that UUID; source paths are cached resolution and repair hints. When one
model is moved or renamed on disk, catalog refresh reconciles it by its animation-manifest content
hash, preserves the UUID, and regenerates both manifests with the new source path. An identical copy
is not treated as a move while the original still exists. Ambiguous content matches intentionally
receive a new identity rather than silently binding the wrong asset.
Legacy path-only `ModelRef` values remain readable and use their cached path. Reassign or replace a
legacy model actor to opt it into stable move resolution.
Scene schema v3 migrates legacy animated actors that paired `ModelRef` with
`AnimationControllerDesc` to the dedicated skinned renderer. Generic `ImportedModel + ModelRef`
scene instances remain readable and intentionally do not become animation actors.
Skeleton compatibility hashes the exact Bevy 0.19 glTF node-name segments and bind poses, including
whitespace and slash characters. The readable joint paths shown by the editor are deliberately not
used as identity. Animation-manifest schema v1 artifacts must be reimported to generate schema v2
signatures.
signatures; schema v3 adds the explicit default-clip ID. Schema v2 deserializes as Imported rest
pose and never receives an inferred default.
## Validation And Format Boundary
Interactive diagnostics and `cargo validate-levels` resolve registry UUIDs, generated manifests,
stable subasset IDs, source dependencies, default/state IDs, playback ranges, speeds, crossfades,
runtime format support, exact source-content fingerprints, and exact rig compatibility. Findings
runtime format support, explicit default-clip resolution, exact source-content fingerprints, and
exact rig compatibility. Findings
identify the owning actor and controller property and include a repair action. Packaging includes
the same source files and generated artifacts checked by validation.
@@ -86,6 +99,7 @@ Bevy creates a separate `AnimationPlayer` for each root. Split those rigs into s
export them beneath one common root. Animation v1 also does not provide implicit retargeting, blend
trees, a visual state graph, root motion, IK, or motion matching.
See [ADR 0031](../adr/0031-animation-authoring-runtime-contract.md) for the persistent/runtime
boundary and [the working implementation plan](../../.cursor/plans/animation_authoring_2026-07-11.plan.md)
See [ADR 0031](../adr/0031-animation-authoring-runtime-contract.md) for the controller/runtime
boundary, [ADR 0033](../adr/0033-dedicated-skinned-mesh-renderer.md) for renderer ownership, and
[the working implementation plan](../../.cursor/plans/animation_authoring_2026-07-11.plan.md)
for acceptance gates.
+34 -7
View File
@@ -182,18 +182,45 @@ On play enter/exit the editor snapshots **player sim state only** (transform, ve
2. `EditorOnly` entities (cameras, helpers) are filtered from hierarchy and save; visualizer proxies can be picked but resolve back to source entities.
3. Player placement is stored as `PlayerSpawn`; the runtime `Player` is never serialized.
4. `SceneIo` writes native Bevy dynamic scenes under `assets/levels/`, routed through `scene::document::SceneDocument`. The active tab is materialized in the ECS world; inactive tabs retain normalized authored snapshots and independent dirty/recovery state. `SceneComposition` resources reference validated project-relative subscenes by stable IDs, and runtime-only `ComposedSceneMember` ownership prevents child actors from being flattened into the owner save. See [multi-scene-composition.md](multi-scene-composition.md) and ADR 0026.
5. Hydration systems in `game` spawn meshes, colliders, lights, and static mesh renderer parts at runtime. Level-object roots are initialized with Bevy visibility hierarchy components before generated children are attached, so authoring `EditorVisibility` participates in normal visibility propagation. `ActorId` and `ComponentInstanceId` are the persisted identities; raw Bevy `Entity` IDs are runtime-only and must not become tool-facing document IDs.
5. Hydration systems in `game` spawn meshes, colliders, lights, static mesh renderer parts, and
dedicated skinned-model hierarchies at runtime. Level-object roots are initialized with Bevy
visibility hierarchy components before generated children are attached, so authoring
`EditorVisibility` participates in normal visibility propagation. `ActorId` and
`ComponentInstanceId` are the persisted identities; raw Bevy `Entity` IDs are runtime-only and
must not become tool-facing document IDs.
6. Brush actors store authored convex geometry as `BrushDesc`; hydration rebuilds generated mesh children from those faces and strips the children before save.
## Model import (glTF + FBX)
- **Import:** File → Import Assets copies glTF/GLB/FBX into `assets/models/`. FBX imports also copy a sibling `{name}.fbm/` folder when present (embedded textures).
- **Processing:** the asset registry generates normalized static mesh manifests under `assets/meshes/generated/`. The manifests store stable part IDs, glTF/FBX mesh/material subasset labels, source metadata, dependencies, and import settings. These artifacts are hidden from the Asset Browser catalog.
- **Browser subassets:** model rows can expand into a content shelf backed by the generated manifest. Mesh subassets can be selected or dragged into the viewport as `StaticMeshRenderer` actors, material subassets expose source defaults, and texture dependencies can be applied to selected actors without treating glTF and FBX differently. The thumbnail studio renders each generated model/subasset/material preview into its own render target before registering it in the cache so later thumbnails cannot overwrite earlier cache entries.
- **Default placement:** model drag/drop creates `ActorKind::StaticMesh + StaticMeshRenderer`. Renderer slots reference imported `EditorAssetRef` values (`asset_id` + `sub_asset_id`) and hydration resolves those through the generated artifact. `SingleActor` hierarchy mode stores all parts in one renderer; `SourceHierarchy` creates a root with child static mesh actors.
- **Collision:** when collider generation is enabled, placement adds `RigidBodyDesc` and `ColliderDesc::StaticMesh` using the same imported mesh refs. Renderer slots no longer own collider state.
- **Scene-instance placement:** asset details can switch placement to `SceneInstance`; that keeps `ImportedModel + ModelRef`, which hydrates to `WorldAssetRoot`. glTF uses `GltfAssetLabel::Scene`; FBX uses `bevy_ufbx` (`path#SceneN`). `FbxPlugin` is registered in `GamePlugin`.
- **Limitations:** Binary FBX only (not ASCII). Static mesh placement stores animation/skinning/camera/light metadata and warnings but does not play those features; use Scene Instance for full-scene playback.
- **Processing:** the asset registry generates normalized model manifests under
`assets/meshes/generated/`. The manifests store stable part IDs, glTF/FBX mesh/material subasset
labels, whether each part is skin-bound, source metadata, dependencies, and import settings.
These artifacts are hidden from the Asset Browser catalog.
- **Browser subassets:** model rows can expand into a content shelf backed by the generated
manifest. Unrigged mesh subassets place as independent `StaticMeshRenderer` actors. A skinned
subasset places its owning source through `SkinnedMeshRenderer`, retaining joints and inverse bind
poses. Material subassets expose source defaults, and texture dependencies can be applied to
selected actors. The thumbnail studio renders each generated model/subasset/material preview into
its own render target before registering it in the cache so later thumbnails cannot overwrite
earlier cache entries.
- **Default placement:** **Renderable Asset (Auto)** creates
`ActorKind::StaticMesh + StaticMeshRenderer` for unrigged, non-animated models and
`ActorKind::SkinnedMesh + SkinnedMeshRenderer` when any part is skin-bound or the source contains
animation. Static renderer slots
reference imported `EditorAssetRef` values and exclude skinned parts. Static `SingleActor` mode
stores all parts in one renderer; `SourceHierarchy` creates a root with child static mesh actors.
Skinned placement always preserves the imported source hierarchy.
- **Collision:** when collider generation is enabled, static placement adds `RigidBodyDesc` and
`ColliderDesc::StaticMesh` using the same imported mesh refs. Skinned render surfaces do not
receive automatic triangle colliders; author stable gameplay collision explicitly.
- **Scene-instance placement:** asset details can switch placement to `SceneInstance`; that keeps
`ImportedModel + ModelRef` for a generic source scene and hydrates to `WorldAssetRoot`. It is not
the animation renderer. glTF uses `GltfAssetLabel::Scene`; FBX uses `bevy_ufbx` (`path#SceneN`).
`FbxPlugin` is registered in `GamePlugin`.
- **Limitations:** Binary FBX only (not ASCII). Animated or skinned FBX remains blocked until its
loader can construct the same hierarchy and clips as the glTF skinned path. See ADRs 0031 and
0033.
## Undo / history
+4 -3
View File
@@ -24,8 +24,8 @@ Default HTTP endpoint follows Bevy 0.19 remote defaults (port **15702**, routes
| Allowed (examples) | Forbidden on level objects |
|--------------------|----------------------------|
| `Transform`, `Name`, `ActorKind` | `PointLight`, `SpotLight`, `DirectionalLight` |
| `Primitive`, `StaticMeshRenderer`, `MaterialDesc`, `MaterialOverride`, `LightDesc` | `Mesh3d`, `MeshMaterial3d`, `RigidBody`, `Collider` |
| `ModelRef`, `RigidBodyDesc`, `ColliderDesc`, legacy `PhysicsBody`, gameplay markers | `WorldAssetRoot`, generated static mesh children, internal visibility types |
| `Primitive`, `StaticMeshRenderer`, `SkinnedMeshRenderer`, `MaterialDesc`, `MaterialOverride`, `LightDesc` | `Mesh3d`, `MeshMaterial3d`, `RigidBody`, `Collider` |
| `ModelRef`, `RigidBodyDesc`, `ColliderDesc`, legacy `PhysicsBody`, gameplay markers | `WorldAssetRoot`, generated static/skinned roots, internal visibility types |
| `PostProcessVolumeDesc` | Runtime post-process components on cameras |
Prefer:
@@ -33,7 +33,8 @@ Prefer:
1. Editing `LightDesc` instead of `SpotLight` / `DirectionalLight`
2. Editing `MaterialDesc` instead of `StandardMaterial` handles
3. Editing `StaticMeshRenderer` instead of child `Mesh3d` entities
4. Editing `ColliderDesc` / `RigidBodyDesc` instead of runtime Avian components
4. Editing `SkinnedMeshRenderer` instead of its hydrated joint/mesh hierarchy
5. Editing `ColliderDesc` / `RigidBodyDesc` instead of runtime Avian components
5. Version-controlled `assets/levels/*.scn.ron` for durable changes
See [ADR 0009 — Authoring vs hydrated](../adr/0009-authoring-vs-hydrated.md).
@@ -0,0 +1,96 @@
# Renderer, Material, and Component Foundation Evaluation
Date: 2026-07-11
Branch: `codex/renderer-material-component-foundation`
This record captures implementation evidence for the dedicated skinned renderer, shared Material
and Material Instance workflow, registry-driven authoring components, and custom Surface contract.
The permanent design contracts live in [ADR 0033](../../../adr/0033-dedicated-skinned-mesh-renderer.md),
[ADR 0034](../../../adr/0034-registry-driven-authoring-components.md),
[ADR 0035](../../../adr/0035-shared-material-assets-and-renderer-slots.md), and
[ADR 0036](../../../adr/0036-surface-abi-and-solari-parity.md). The user workflow lives in the
[material-system guide](../../material-system.md).
## Live editor evidence
All images below are native Wayland captures from the running editor. The temporary actors and
assignments used for visual verification were not saved into the authored scene.
### Dedicated skinned renderer and stable material slots
![RobotExpressive in its explicit Standing edit pose with a dedicated Skinned Mesh Renderer and stable named material slots](skinned-mesh-renderer-material-slots.png)
The actor is hydrated through `SkinnedMeshRenderer`, not `StaticMeshRenderer`. Its imported
hierarchy remains intact, the configured default Standing clip is sampled in edit mode, and every
draw binding exposes a stable slot ID plus source-material fallback.
### Shared custom Surface assigned through a Material Instance
![Custom Surface Material Instance assigned across the skinned renderer slots](custom-surface-on-skinned-renderer.png)
Applying `surface_tint_instance` updates the existing hydrated draw bindings in place. The visible
blue Surface evaluation does not respawn the hierarchy or reset the sampled pose.
### Sparse Material Instance authoring
![Material Instance editor showing sparse shader and texture overrides](material-instance-sparse-overrides.png)
Instances reference one direct base Material. Unchecked values inherit; selecting or dropping a
texture creates only that override, and **Clear** removes the binding so inheritance resumes.
### Registry-driven component composition
![One actor composed from Static Mesh Renderer and Light components](mesh-light-component-composition.png)
The actor combines renderer and light components without an `ActorKind` exclusivity rule. The
registry owns add/remove/reset/copy/paste/history/persistence behavior; `ActorKind` remains a
derived compatibility and presentation hint.
### Larger material thumbnail previews
![Material thumbnails with tightly framed sphere previews](larger-material-thumbnail-previews.png)
Material spheres now fill roughly 78-81% of the preview while retaining edge padding. Model and
mesh-subasset framing is unchanged.
Additional captures:
- [Material editor and Create Instance action](material-editor-create-instance.png)
- [Registry-driven Add Component categories](component-registry-add-menu.png)
## Acceptance results
| Area | Result | Evidence |
|------|--------|----------|
| Dedicated static/skinned ownership | Pass | Separate authored/hydrated renderer types; rigged/animated manifests are rejected by static hydration |
| Pose lifecycle | Pass | Explicit stable default clip; transform and morph-weight baseline restore on stop, controller removal, preview reset, and PIE exit |
| Renderer material slots | Pass | Stable named IDs, imported fallback, explicit assignment, orphan retention, and in-place material patching |
| Material assets/instances | Pass | Versioned shared assets, direct-base sparse instances, transient property blocks, Apply/Revert/Create Instance |
| Texture parameters | Pass | Project-wide picker includes imported texture subassets; base/schema/stored/instance slots share browse, drop, reject, and clear behavior |
| Component lifecycle | Pass | Stable registry IDs, reflected transactions/history, persistence allowlist, independent active state, and compatible composition |
| Surface raster/Solari semantics | Pass for eligible geometry | Shared ABI packing, evaluator, textures, normal/emissive/unlit values, and cutout predicate |
| Project migration | Pass | Transactional schema-v4 upgrader, backup/rollback path, canonical slots and active-state split; second dry run is empty |
| Project validation | Pass | 59 dependencies, 5 non-blocking findings, 0 blocking errors |
## Automated verification
| Command/suite | Result |
|---------------|--------|
| `cargo test -p shared --offline` | 84 passed |
| `cargo test -p scene --offline` | 64 passed, 1 ignored migration fixture |
| `cargo test -p game --lib --offline` | 37 passed |
| `cargo test -p game_hot --lib --offline` | 16 passed |
| `cargo test -p editor --lib --offline` | 171 passed |
| `cargo test -p blacksite_surface --offline` | 3 passed plus doc tests |
| `cargo test -p bevy_solari --lib --offline` | 1 passed |
| `cargo --locked --offline validate-levels` | 0 blocking errors |
| `cargo --offline upgrade-project --project . --json` | No pending changes or warnings |
| `cargo fmt --all -- --check` / `git diff --check` | Pass |
## Deliberate boundary
Bevy 0.19's maintained Solari path does not expose dynamic post-morph/post-skin vertex buffers and
BLAS updates. Skinned and morph-deformed actors therefore remain visible in raster but are omitted
from ray tracing with an actionable diagnostic. This is safer than tracing a stale bind-pose ghost;
dynamic deformed BLAS support remains future work and the corresponding Gitea acceptance item stays
open.
+49
View File
@@ -0,0 +1,49 @@
# Authoring component extensibility
The authoring component registry is the lifecycle boundary between game-owned components and the
editor. Stable component IDs are API keys; reflected Rust type paths are serialization adapters and
may change during refactors.
## Register a statically linked component
Derive `Component`, `Reflect`, and `Default`, and expose Bevy's component/default reflection data:
```rust
#[derive(Component, Reflect, Default)]
#[reflect(Component, Default)]
struct WeaponTuning {
damage: f32,
}
```
During editor setup, call
`editor::ui::component_registry::register_authoring_component::<WeaponTuning>(...)` with an
`EditorComponentDescriptor` and inspector callback. The descriptor's stable `id` must never be a
Rust type path. Registration fails on duplicate IDs or reflected types, and startup checks that all
declared types and relationships resolve.
Once registered, the component automatically participates in registry presence checks, scene save
filtering, default add/reset, reflected copy/paste and removal, and atomic component history. The
inspector callback owns the component's UI body; mutations should use
`history::reflected_component_transaction` so component data and the derived `ActorKind` hint undo
together.
## Composition and enable state
`ActorKind` is a compatibility/display hint, not a component container. Requirements and conflicts
belong to component registrations. Render, light, audio, physics, and gameplay behaviors may be
composed unless an explicit conflict prohibits the pair; primary geometry sources are mutually
exclusive.
Persisted enablement lives in `AuthoringComponentStates`. `InspectorOrder` only controls visual card
order. Runtime and hydration code must use
`authoring_component_active(states, legacy_order, component_type_path)`; the legacy order argument
preserves disabled state while schema-v3 scenes migrate.
## Current boundary
Whole-entity spawn/duplicate snapshots and built-in inspector bodies still contain typed adapters.
Do not extend those match lists for new component-only edits: use the registry transaction API.
Dynamic-library component types are not supported; extensions are statically linked and registered
before the editor's startup validation runs.
+149
View File
@@ -0,0 +1,149 @@
# Material System
Blacksite uses shared project materials and renderer-owned material slots. Static and skinned mesh
renderers expose the same assignment workflow, but remain separate components with separate mesh
and hydration ownership. The permanent contracts are [ADR 0035](../adr/0035-shared-material-assets-and-renderer-slots.md)
and [ADR 0036](../adr/0036-surface-abi-and-solari-parity.md).
## Mental model
| Concept | Owns | Saved? |
|---------|------|--------|
| Material asset | Reusable shader choice, render state, parameters, and textures | Yes, under `assets/materials/` |
| Material instance | Overrides over one direct base material | Yes, under `assets/materials/` |
| Renderer material slot | A stable reference on one static or skinned renderer | Yes, in scenes/prefabs |
| Imported source material | Read-only default supplied by model import | Yes, as the slot fallback |
| Material property block | Temporary per-renderer/per-slot runtime overrides | No |
A renderer slot stores a `MaterialRef`, not a copy of the material. The registry UUID and subasset
ID identify the target; the cached path is only a loading hint. A material instance may reference a
material, but may not reference another instance.
## Assign materials
1. Select a static- or skinned-mesh actor.
2. In **Static Mesh Renderer** or **Skinned Mesh Renderer**, find the material slot by its imported
name and stable ID.
3. Use **Browse** or **Select** to assign a Material or Material Instance. **Locate** reveals the
current asset in the Asset Browser.
4. Use **Clear** to remove only the explicit assignment. The slot returns to its read-only imported
source material.
From the Asset Browser, **Apply Material** assigns the selected material to every material slot on
each selected static or skinned renderer. Use the per-slot inspector when different draws need
different assignments.
Static draw slots and material slots are separate. Removing a static draw retains its explicit
material assignment as an orphan rather than guessing a replacement. Reimport also reconciles
slots by stable ID, never by display name. Resolve an orphan explicitly in the renderer inspector.
## Author shared assets
Material files and material-instance files are RON documents under `assets/materials/`. The Asset
Browser identifies the document kind, exposes its schema-driven properties and texture bindings,
and uses stable subasset IDs (`material:source` or `material:instance`). Built-in shader schemas
live under `assets/shaders/`.
Select a Material and use **Create Instance** to create a direct-base variant beside it. The
instance inspector exposes its base Material plus sparse property and texture override checkboxes;
unchecked values continue to inherit. Material instances cannot inherit from other instances.
Material render state exposes Opaque/Cutout, alpha cutoff, and Double Sided in the base Material
inspector.
Every standard and shader-schema texture slot uses the project texture picker. **Browse** lists
texture assets across the project, including imported model texture subassets, and a texture can be
dragged from the Asset Browser directly onto a slot. Non-texture drops are ignored. **Clear** removes
the base Material value; on a Material Instance it removes the sparse override so the slot inherits
from its base again. Dropping or browsing a texture onto an unchecked instance slot creates the
override automatically.
The supported render states are:
- **Opaque** — no alpha candidate test.
- **Cutout** — alpha is compared with the material's cutoff in raster and, for eligible geometry,
at Solari ray candidates.
- **Double sided** — stored on the shared material render state.
Editing a shared asset never writes copies into renderer components. The runtime watches the
Material, direct base, shader schema, and evaluator dependencies and updates the shared hydrated
handle in place. Standard and custom Surface changes therefore propagate to every assigned static
or skinned renderer slot without reloading geometry, joints, or the current animation pose. Invalid
Surface edits retain the last-good evaluator generation and emit diagnostics.
## Custom Surface evaluators
A custom shader schema may reference evaluator WGSL. Evaluators return material properties through
one constrained entry point:
```wgsl
fn evaluate(
input: SurfaceInput,
params: SurfaceParams,
samples: SurfaceSamples,
) -> Surface {
var surface = surface_default();
surface.base_color = samples.values[0];
surface.perceptual_roughness = params.lanes[0].x;
return surface;
}
```
Surface ABI v1 supplies UV0, world position, world normal, 16 parameter lanes, and eight sampled 2D
textures. The evaluator returns base color/alpha, tangent-space normal, emissive, metallic,
roughness, reflectance, occlusion, and lit/unlit model selection. Mesh tangents are required for a
custom tangent-space normal to affect raster output and for Solari mesh compatibility.
Do not declare bindings or `@vertex`, `@fragment`, or `@compute` entry points. Storage resources,
ray queries, derivatives, discard, barriers/subgroups, texture stores, and atomics are rejected.
The engine owns the render stages and composes the same validated evaluator into raster and Solari.
## Solari scope
For eligible non-deformed triangle geometry, Solari uses the same Surface evaluator, packed
parameters, textures, normal, emissive/unlit choice, and cutout alpha decision as raster rendering.
The standard material path remains unchanged for materials without a custom evaluator. See the
[rendering guide](rendering.md) for GI selection and fallback diagnostics.
Skinned meshes and morph-deformed meshes are currently excluded from Solari. This prevents rays
from tracing their undeformed source/bind pose while raster shows the animated pose. They remain
visible in raster, and Rendering diagnostics report the deformed exclusion. Dynamic deformed
vertex/BLAS updates are future work.
Surface ABI v1 does not support blended transparency, transmission/refraction, custom vertex
displacement, or arbitrary pipeline stages.
`assets/materials/surface_tint.ron` and `assets/shaders/surface_tint.*` are the committed minimal
custom-Surface example used for editor and renderer verification.
## Upgrade and validate a project
Normal project loading does not rewrite material or scene files. Preview the explicit transactional
upgrade first:
```bash
cargo upgrade-project --project .
cargo upgrade-project --project . --apply
```
Apply mode stages the complete rewrite, creates a timestamped backup under
`.blacksite/backups/material-component-v4-*`, and rolls back on failure. Commit or otherwise back up
the project before applying, inspect the diff afterward, then run:
```bash
cargo --locked validate-levels
```
Validation reports unresolved material/schema/texture references, nested or incompatible instance
bases, and unsupported project content through the same editor/headless finding model.
## Troubleshooting
| Symptom | Check |
|---------|-------|
| Clearing a slot appears to do nothing | Clear removes the explicit override; the imported source material is still effective. |
| Assignment disappeared after reimport | Look for an orphaned assignment. Slots are intentionally not matched by name. |
| Skinned material edit resets the pose | This is a regression: material-only changes must patch the existing hierarchy rather than reload it. |
| Custom evaluator is rejected | Check the required `evaluate` signature, ABI lane/texture limits, and forbidden constructs. |
| Custom normal has no visible effect | Verify the mesh has tangents. |
| Animated actor is missing from Solari GI | Expected for current skinned/morph geometry; inspect the deformed-exclusion diagnostic. |
| Material reference is unresolved | Run project validation and repair/reselect the stable asset reference; do not hand-edit a display-name match. |
+66
View File
@@ -0,0 +1,66 @@
# Navigation Authoring
Blacksite navigation v1 uses authored bounds, obstacles, areas, and links to produce a deterministic
Rerecast bake artifact. Editor preview and packaged gameplay query that artifact through the same
`game::navigation::NavigationRuntime` Polyanya path API.
## Authoring
Use **Scene > Navigation** or the path icon in the existing top toolbar to create navigation actors:
- **Navigation Bounds** defines an axis-aligned bake region, agent profile, generated artifact path,
and optional debounced auto-bake.
- **Navigation Obstacle** carves a blocked volume from overlapping bounds.
- **Navigation Area** records a named walkable/blocked volume and traversal cost. V1 applies blocked
areas during bake and retains walkable cost metadata for a future per-polygon cost callback.
- **Navigation Link** connects otherwise isolated regions. Endpoints are local to the actor;
direction, enabled state, and traversal cost are authored.
V1 source geometry includes primitives and additive brushes. Imported static-mesh manifests do not
yet contain normalized collision triangles, so imported objects require authored navigation
obstacles until that artifact contract is extended.
Each navigation actor must own exactly one navigation component. Inspector changes are undoable and
save-time validation rejects invalid extents, profiles, area IDs/costs, and link endpoints.
## Bake And Preview
Select a bounds actor and click **Bake** in its Inspector, use **Scene > Navigation > Bake Selected
Bounds**, or click the toolbar path icon. The generated artifact must remain under
`assets/navigation/generated/`. Its fingerprint includes the source scene, bounds, agent settings,
overlapping primitive/additive-brush triangles, obstacles, areas, and links. Distant authoring is
excluded so independent bounds do not invalidate one another. Relevant edits immediately mark it
stale; auto-bake waits 0.75 seconds after the latest change before rebuilding. A failed auto-bake
reports once and waits for another authored change before retrying.
The viewport overlay draws authored volumes, baked polygon edges, link endpoints, and the current
path test. Set **Path start** and **Path end** on the bounds card and choose **Test Path**. Green/red
endpoint markers and an amber route show the exact result returned by the game runtime API.
## Headless And Runtime
Bake one scene or every scene under `assets/levels/`:
```bash
cargo bake-navigation --project . --scene assets/levels/navigation_authoring_showcase.scn.ron
cargo bake-navigation --project .
cargo bake-navigation --project . --check
```
`--check` never writes. It fails when an artifact is missing, malformed, or stale, making it suitable
for CI. `cargo validate-levels` applies the same fingerprint policy, validates link proximity, and
adds current navigation artifacts to package dependencies.
Gameplay loads and queries an artifact without editor dependencies:
```rust
let navigation = game::navigation::NavigationRuntime::load(path)?;
let path = navigation.query(start, destination)?;
```
The returned path contains world-space points, total length, and the optional stable actor ID of an
off-mesh link used by the route.
See [ADR 0032](../adr/0032-versioned-navigation-bake-and-runtime-query.md) for dependency and
ownership decisions and [the implementation plan](../../.cursor/plans/navigation_authoring_2026-07-11.plan.md)
for acceptance gates.
+1 -1
View File
@@ -147,7 +147,7 @@ with implementation sequencing in
| Milestone | Exit condition | Status |
|-----------|----------------|--------|
| M6 Reliability, recovery, and project workflow | Transactional save/recovery, stable sessions, project launcher, hardened hierarchy/prefabs, multi-scene composition | Implementation complete; all six scoped issues are closed after prefab #43 passed workspace, headless, packaged-runtime, and live editor acceptance |
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44, #45, and #47 are complete. Audio passed automated, headless, live editor/PIE, and packaged-runtime acceptance. Remaining scoped work is animation #46, navigation #48, source-control safety #49, and final readiness gate #50 |
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44, #45, #46, and #47 are complete. Navigation #48 is in implementation; source-control safety #49 and final readiness gate #50 remain. |
Production readiness is not inferred from feature count. Gitea
[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50)
+3 -1
View File
@@ -12,7 +12,9 @@ An **in-process Bevy editor and game foundation** for a server-authoritative mul
4. **Input as intent** — Gameplay consumes `protocol` intent in `FixedUpdate`, enabling determinism, replays, and networking.
5. **Strict crate boundaries** — `sim` and `protocol` stay rendering-free; native-only deps stay in `editor`.
6. **BRP-aligned tooling** — Custom egui UX plus Bevy Remote Protocol for automation and future interop with the official Bevy editor. BRP mutates **authoring** components only ([editor/brp.md](editor/brp.md), [ADR 0009](adr/0009-authoring-vs-hydrated.md)).
7. **Actor model** — Every saved level object has `ActorKind`; hydration is derived ([ADR 0010](adr/0010-actor-kind-and-inspector.md)).
7. **Composable actor model** — Every saved level object carries a derived `ActorKind` display hint,
while registered authoring components own behavior, requirements, conflicts, persistence, and
hydration ([ADR 0034](adr/0034-registry-driven-authoring-components.md)).
## Audience