Build renderer and material component foundations

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

No files matched your search

@@ -0,0 +1,68 @@
# Navigation Mesh Authoring, Bake Diagnostics, And Path Preview
Working implementation plan for Gitea issue
[`#48`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/48).
This is the navigation production loop required by the M7 content-production milestone.
## Status
Architecture and dependency compatibility are established. Implementation and production
acceptance are in progress.
## Outcome
A level designer can author navigation bounds, obstacles, areas, links, and agent profiles; bake a
deterministic versioned artifact; inspect stale or invalid data; preview a path in the viewport; and
use the same artifact through a game-owned runtime query API and headless release validation.
## Architecture
- Shared reflected components own bounds, obstacles, area volumes, links, and scene bake settings.
- The scene crate owns deterministic source fingerprinting, bake artifact IO, and validation.
- Rerecast performs the 3D walkable-surface bake without coupling navigation to a Bevy plugin
release. Polyanya performs proven any-angle runtime and editor-preview path queries.
- Overlapping primitive and additive-brush triangles enter the deterministic bake source; distant
geometry and navigation authoring are excluded from each bounds fingerprint.
- The game crate owns loading and querying baked artifacts. Editor UI calls that public API for
preview rather than implementing a second pathfinder.
- Generated artifacts live under `assets/navigation/generated/`, are project-relative runtime
dependencies, and never serialize viewport helpers into authored scenes.
## Implementation Sequence
1. Add reflected authoring schema, versioned bake artifact, source fingerprint, validation, and
exact agent-profile settings.
2. Add deterministic Rerecast bake input extraction for authored bounds/obstacles and headless bake
command coverage.
3. Add game-owned artifact loading and Polyanya path-query API, including authored off-mesh links.
4. Add typed inspectors, create commands, bake/stale status, viewport overlay, and start/end path
preview.
5. Add owner-attributed project validation for invalid links, missing/stale artifacts, unreachable
preview samples, and bake failures.
6. Commit a small sample scene/artifact and run automated, headless, live editor, PIE, and packaged
runtime acceptance.
## Acceptance Gates
- A designer can create bounds and obstacles, bake, view the resulting mesh, and preview a valid
start-to-end path.
- Agent radius, height, climb, and slope settings deterministically affect the bake fingerprint.
- Relevant geometry or navigation-authoring changes mark the artifact stale; unrelated scene
metadata does not.
- Invalid or dangling links, samples outside the mesh, isolated regions, and bake failures identify
the owning actor or setting and provide a repair action.
- Runtime path queries and editor preview use the same game-owned API and versioned artifact.
- Helper meshes, lines, endpoints, and bake state are transient and never serialize.
- Headless bake and project validation pass for the committed sample fixture, and package dependency
collection includes the current artifact.
## Deliberate Boundaries
- V1 supports static baked navigation plus explicit links. Dynamic crowd avoidance and runtime tile
carving are separate work.
- Full partial-tile regeneration waits for upstream Rerecast tiling support. V1 records affected
source bounds and debounces a deterministic full bake while reporting the dirty region.
- Area costs are authored and validated in V1; path-cost weighting beyond walkable/blocked areas is
deferred until the runtime exposes per-polygon cost callbacks.
- Imported static meshes remain obstacle-authored in V1 because their normalized manifests do not
yet expose deterministic collision triangles to the headless scene crate.
@@ -0,0 +1,43 @@
# Renderer, material, and component foundation
## Goal
Separate static and skinned renderer ownership, restore deterministic skinned edit poses, add shared
material/material-instance slots, and make authoring components registry-driven and composable.
## Component foundation milestone
- Give authoring components immutable IDs distinct from Rust type paths.
- Split persisted active state from inspector ordering with legacy-state migration.
- Route presence, persistence, add/remove/reset/copy/paste, and component history through Bevy
reflection and atomic transactions.
- Treat `ActorKind` as a derived compatibility/display hint; validate component data and explicit
requirements/conflicts.
- Provide one statically linked extension registration helper and reflection round-trip fixture.
- Verify registry integrity, transaction undo/redo, scene save inclusion, composition, and legacy
enable-state preservation.
## Related renderer/material milestone
- Keep `StaticMeshRenderer` and `SkinnedMeshRenderer` as separate authoring and hydration paths.
- Give both renderer types stable imported-source/explicit Material slots and preserve orphaned
assignments by ID across source changes.
- Add versioned Material and direct-base Material Instance assets, sparse editor overrides, shared
handle live refresh, and runtime-only property blocks.
- Capture and restore imported Transform/MorphWeights baselines; sample only the explicitly chosen
default edit clip and never reload a rig for a material-only change.
- Compose one validated Surface evaluator into raster and Solari, including normal/emissive/unlit
fields and exact cutout candidate acceptance. Safely omit skinned/morph geometry from Solari until
instance-owned deformed vertices and dynamic BLAS updates exist.
- Upgrade scenes/materials explicitly to schema v4 with dry-run, staged writes, backup, rollback,
stable slot normalization, and active-state separation.
## Acceptance
- Shared, scene, game, game-hot, editor, Surface, and maintained Solari-fork tests pass.
- `cargo --locked validate-levels` reports zero blocking findings.
- A second project-upgrade dry run reports no changes after apply.
- Editor evidence shows the stable component cards, static/skinned material slots, Material Instance
workflow, deterministic animated actor pose, and Surface/Solari diagnostics.
- Gitea implementation issue and related roadmap issues link the documentation and screenshot
evidence without claiming unsupported dynamic deformed BLAS behavior.