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
@@ -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
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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
@@ -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
|
||||
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
|
||||
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 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.
|
||||
BIN
Binary file not shown.
BIN
Binary file not shown.
BIN
Binary file not shown.
BIN
Binary file not shown.
BIN
Binary file not shown.
BIN
Binary file not shown.
BIN
Binary file not shown.
@@ -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.
|
||||
|
||||
@@ -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. |
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
|
||||
Reference in new issue
Block a user