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:
1 parent
0553a85220
commit
0798aa5d57
169 files changed
+27098
-3469
No files matched your search
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user