Add terrain material layer painting
CI / Format, lint, test, build (push) Waiting to run

This commit is contained in:
Rbanh committed 2026-07-12 21:00:13 -04:00
1 parent 293811aecd
commit d1a56f77cc
23 files changed
+1730 -62

No files matched your search

+3
View File
@@ -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.
+2 -1
View File
@@ -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
![Terrain layer paint stroke](terrain-material-paint-stroke.png)
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.
+25 -6
View File
@@ -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/).