This commit is contained in:
1 parent
293811aecd
commit
d1a56f77cc
23 files changed
+1730
-62
No files matched your search
@@ -54,6 +54,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [0037](adr/0037-collaborative-authored-file-safety.md) | Exact authored-file revisions, observational Git status, and optional ownership providers |
|
||||
| [0038](adr/0038-non-blocking-native-dialog-broker.md) | Worker-owned native waits with one-shot main-thread workflow completion |
|
||||
| [0039](adr/0039-inline-height-grid-terrain-foundation.md) | Inline authored height grids with deterministic runtime-only chunk hydration |
|
||||
| [0040](adr/0040-terrain-material-layer-weights.md) | Four-channel terrain material layers, compact normalized weights, and raster transport |
|
||||
|
||||
## Editor framework
|
||||
|
||||
@@ -83,6 +84,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [editor/terrain.md](editor/terrain.md) | Terrain schema, inspector workflow, chunk hydration, collision, and follow-on boundaries |
|
||||
| [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
|
||||
| [editor/evaluations/terrain-sculpt-tools/](editor/evaluations/terrain-sculpt-tools/) | Live screenshot and acceptance results for modal terrain sculpt tools |
|
||||
| [editor/evaluations/terrain-material-layers/](editor/evaluations/terrain-material-layers/) | Live screenshot and acceptance results for terrain material assignment, blending, painting, and history |
|
||||
| [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
|
||||
| [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements |
|
||||
|
||||
@@ -106,6 +108,7 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans
|
||||
| `source_control_collaboration_safety_*.plan.md` | Exact authored-file guards, observational Git status, conflict recovery, and provider contract |
|
||||
| `production_readiness_acceptance_*.plan.md` | Release-candidate evidence matrix, blocker sequence, clean-checkout checks, soak, budgets, and independent sign-off |
|
||||
| `material_library_and_targeted_drop_*.plan.md` | Dedicated Material Library, exact viewport slot/primitive/brush targeting, hover preview, cancel, and grouped history |
|
||||
| `terrain_material_layers_*.plan.md` | Terrain shared-material layers, normalized weights, blended hydration, and modal painting |
|
||||
|
||||
## Crate responsibilities (quick reference)
|
||||
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
# ADR 0040: Terrain Material Layers And Weight Transport
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Terrain needs multiple shared project materials, editable weight painting, deterministic persistence,
|
||||
and raster behavior that remains consistent between the editor and game. Duplicating full material
|
||||
descriptors into scenes would break the shared Material/Material Instance contract. Storing floating
|
||||
point weights would also create avoidable scene churn and normalization drift.
|
||||
|
||||
## Decision
|
||||
|
||||
`TerrainDesc` stores at most four `TerrainMaterialLayer` entries referencing shared assets and one
|
||||
RGBA8 weight tuple per height sample. Every explicit tuple sums to 255; an absent weight array means
|
||||
full channel-zero coverage for backward compatibility. Generated terrain chunks transport normalized
|
||||
weights through `Mesh::ATTRIBUTE_COLOR`.
|
||||
|
||||
`shared` owns persistence, validation, chunk generation, and a runtime-only terrain material binding.
|
||||
`blacksite_surface` owns the terrain-specific `ExtendedMaterial` and blends each resolved layer's
|
||||
albedo, tangent-space normal, metallic, and roughness inputs. Invalid or unavailable references leave
|
||||
the existing visible terrain fallback in place and emit diagnostics. Terrain remains excluded from
|
||||
Solari geometry until a matching ray-tracing evaluator exists.
|
||||
|
||||
Editor paint strokes materialize the implicit default map only when needed. Each pointer stroke is a
|
||||
single reflected `TerrainDesc` transaction; cancel restores the exact original descriptor.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Four channels give fixed shader bindings, compact deterministic scenes, and simple normalization.
|
||||
- Adding more than four simultaneous layers requires a deliberate schema and renderer revision.
|
||||
- Weight resolution follows the height grid; independent high-resolution splat maps remain future work.
|
||||
- Terrain raster rendering gains project-material texture parity while Solari terrain parity remains an
|
||||
explicit later milestone rather than using a semantically different proxy.
|
||||
@@ -33,6 +33,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
| [evaluations/native-dialog-responsiveness/](evaluations/native-dialog-responsiveness/) | Live native-Wayland screenshot and verification record for non-blocking picker responsiveness |
|
||||
| [evaluations/terrain-foundation/](evaluations/terrain-foundation/) | Live screenshot and verification record for height-grid terrain schema and chunk hydration |
|
||||
| [evaluations/terrain-sculpt-tools/](evaluations/terrain-sculpt-tools/) | Live screenshot and verification record for modal sculpt controls, footprint, and stroke history |
|
||||
| [evaluations/terrain-material-layers/](evaluations/terrain-material-layers/) | Live screenshot and verification record for blended layers, assignment, painting, and history |
|
||||
| [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity |
|
||||
| [evaluations/production-readiness/](evaluations/production-readiness/) | Current #50 release-candidate matrix and required clean-checkout, soak, performance, limitation, and independent-signoff evidence |
|
||||
|
||||
@@ -42,7 +43,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
|-------------|----------------|-----|
|
||||
| `lib.rs` / `EditorPluginGroup` | Ordered plugin bundle, lib/bin split | ADR 0008, architecture.md |
|
||||
| `shared::components::BrushDesc` / `shared::hydration::brushes` | Persisted brush authoring data and generated runtime mesh hydration | brushes.md, ADR 0021 |
|
||||
| `shared::components::TerrainDesc` / `shared::hydration::terrain` | Persisted height grid and generated render/collider chunks | terrain.md, ADR 0039 |
|
||||
| `shared::components::TerrainDesc` / `shared::hydration::terrain` / `blacksite_surface` | Persisted height/layer grids, generated chunks, and raster blending | terrain.md, ADR 0039, ADR 0040 |
|
||||
| `scene/` | Level I/O, tabs, composition materialization, schema, viewport render-target setup | architecture.md, multi-scene-composition.md, ADR 0026 |
|
||||
| `viewport/` | Camera, selection, gizmos, render views | architecture.md |
|
||||
| `play/` | PIE session, editor mode state | architecture.md |
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
# Terrain Material Layers Acceptance
|
||||
|
||||
## Evidence
|
||||
|
||||

|
||||
|
||||
The native Wayland editor is shown with the deterministic terrain showcase selected, two shared
|
||||
material layers visible in the Inspector, Paint active in the existing horizontal viewport toolbar,
|
||||
and the cyan terrain-following brush footprint over the blended PBR surface.
|
||||
|
||||
## Live Acceptance
|
||||
|
||||
- `Concrete` and `Surface Tint` blend continuously across all four generated chunks.
|
||||
- Layer assignment, clear, reorder, remove, UV tiling, and per-layer sample coverage are visible in
|
||||
the Terrain card without nesting a second panel.
|
||||
- Paint and Erase share the existing horizontal toolbar with layer, radius, and strength controls.
|
||||
- A Paint drag changed layer-two coverage from 13/25 to 16/25 samples and produced exactly one
|
||||
`Undo: Paint Terrain Material` history entry.
|
||||
- Ctrl+Z restored 13/25 samples; Ctrl+Y restored 16/25 samples.
|
||||
- The cyan footprint followed the actual sampled terrain surface and the transform gizmo remained
|
||||
absent while Paint owned viewport input.
|
||||
- Forward PBR and the project `blacksite_surface` terrain extension compiled without GPU pipeline
|
||||
errors. The invalid deferred-only prepass override found during QA was removed from both project
|
||||
material extensions.
|
||||
|
||||
## Automated Coverage
|
||||
|
||||
- Terrain layer/weight RON round-trip and structural validation.
|
||||
- RGBA8 normalization rejection and normalized vertex-color transport.
|
||||
- Paint/Erase normalization and brush-footprint isolation.
|
||||
- Multi-dab single-transaction undo/redo.
|
||||
- Exact restoration of an implicit pre-stroke weight map on cancel.
|
||||
|
||||
Packaged build tests remain intentionally skipped per current project direction. Source workspace
|
||||
format/check/clippy/tests, project validation, navigation bake validation, and diff hygiene are the
|
||||
required gate for this ticket.
|
||||
Binary file not shown.
+25
-6
@@ -24,6 +24,20 @@ closes the sculpt tool. Flatten captures the height under the initial press. Smo
|
||||
copy of the current neighborhood per dab, and Noise uses a deterministic per-stroke seed so authored
|
||||
results remain reproducible.
|
||||
|
||||
## Material Layers And Paint Workflow
|
||||
|
||||
The Terrain card owns up to four shared Material or Material Instance layers. Use the plus icon to
|
||||
add a channel, then browse or drag a material into its selector. Each layer exposes independent UV
|
||||
tiling and can be reordered or removed; channel weights move with the layer. The first added layer
|
||||
adopts a legacy Base Material assignment so existing terrain converts without visual loss.
|
||||
|
||||
With at least two layers assigned, select the paint-brush button beside Sculpt in the existing
|
||||
horizontal viewport toolbar. Choose **Paint** or **Erase**, select the target layer, then LMB-drag.
|
||||
Paint increases the selected channel while proportionally reducing the others; Erase redistributes
|
||||
weight to the remaining channels. Every sample stays normalized to 255, the terrain-following cyan
|
||||
or amber footprint previews the brush, and release records one undo entry. Escape or right-click
|
||||
restores the exact pre-stroke weights or closes the idle tool.
|
||||
|
||||
`assets/levels/terrain_authoring_showcase.scn.ron` is the deterministic foundation fixture. Its 5×5
|
||||
grid forms an asymmetric hill split into four 2×2-quad chunks. It validates chunk boundaries,
|
||||
normals, selection through generated children, collider generation, inspector state, and save
|
||||
@@ -32,19 +46,24 @@ stripping without requiring external assets.
|
||||
## Data And Hydration
|
||||
|
||||
- Heights are finite normalized values multiplied by Height Scale at hydration time.
|
||||
- Up to four Material/Material Instance references remain shared assets rather than copied material
|
||||
descriptors. RGBA8 weights are stored per height sample; an absent array means full layer zero.
|
||||
- Generated chunk vertex colors carry normalized weights into the `blacksite_surface` terrain
|
||||
material, which blends layer base color/texture, normal, metallic, and roughness inputs.
|
||||
- Sample Spacing controls X/Z distance and the grid remains centered on the actor origin.
|
||||
- Chunk Size is measured in quads. Neighboring chunks share boundary samples but not runtime mesh
|
||||
assets, allowing later stroke updates to rebuild only affected chunks.
|
||||
- A resolvable shared Material/Material Instance source supplies the chunk material. Missing or
|
||||
invalid references produce a warning and visible terrain fallback rather than missing geometry.
|
||||
- Missing, unassigned, or invalid layer references produce a clear diagnostic and visible terrain
|
||||
fallback rather than missing geometry.
|
||||
- Generated `HydratedTerrainChunk` children own mesh, optional trimesh collider, and shadow state.
|
||||
They are runtime-only and never serialized as authored actors.
|
||||
- Foundation chunks are explicitly excluded from Solari submission and remain raster-visible while
|
||||
Auto/Solari is active. Terrain Surface/layer parity enters with the material-layer work in `#24`;
|
||||
the editor never substitutes a black or semantically different ray-traced terrain proxy.
|
||||
Auto/Solari is active. Raster material-layer parity is shipped; matching Solari terrain evaluation
|
||||
remains explicit future work, and the editor never substitutes a semantically different proxy.
|
||||
|
||||
Material layers and weight painting are tracked by Gitea `#24`. The persistence decision is recorded in
|
||||
[ADR 0039](../adr/0039-inline-height-grid-terrain-foundation.md).
|
||||
The terrain foundation is recorded in [ADR 0039](../adr/0039-inline-height-grid-terrain-foundation.md),
|
||||
and layer weight persistence/render transport in
|
||||
[ADR 0040](../adr/0040-terrain-material-layer-weights.md).
|
||||
|
||||
Live native-Wayland evidence and focused verification are recorded in the
|
||||
[terrain foundation evaluation](evaluations/terrain-foundation/).
|
||||
Reference in new issue
Block a user