This commit is contained in:
1 parent
577d8dcb27
commit
ed21bcc52d
22 files changed
+874
-6
No files matched your search
@@ -53,6 +53,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [0036](adr/0036-surface-abi-and-solari-parity.md) | Constrained Surface ABI v1, raster/Solari evaluator parity, and deformed-geometry boundary |
|
||||
| [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 |
|
||||
|
||||
## Editor framework
|
||||
|
||||
@@ -79,6 +80,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [editor/material-system.md](editor/material-system.md) | Shared material assets and instances, renderer-slot assignment, Surface evaluators, migration, and diagnostics |
|
||||
| [editor/collaborative-file-safety.md](editor/collaborative-file-safety.md) | Guarded authored writes, compact Git/read-only status, conflict recovery, and ownership providers |
|
||||
| [editor/native-dialogs.md](editor/native-dialogs.md) | Non-blocking native dialog acquisition and main-thread result application |
|
||||
| [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/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 |
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
# ADR 0039: Inline Height-Grid Terrain Foundation
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Terrain sculpting, material painting, physics placement, recovery, and prefab workflows need one
|
||||
stable owner for height data. Generated meshes and colliders cannot be authoritative because they
|
||||
are runtime artifacts, while introducing an external binary heightmap before editing semantics exist
|
||||
would add file-move, revision, import, and multi-document transaction complexity prematurely.
|
||||
|
||||
## Decision
|
||||
|
||||
`TerrainDesc` schema v1 stores a bounded square grid of normalized finite `f32` heights directly in
|
||||
the authored scene component. It also stores sample spacing, height scale, chunk quad size, an
|
||||
optional shared base Material/Material Instance reference, collider generation, and shadow flags.
|
||||
|
||||
Hydration deterministically partitions grid quads into generated children. Boundary samples are
|
||||
duplicated between neighboring render chunks so each chunk has complete normals and independent
|
||||
triangle geometry. Chunk meshes/colliders are never `LevelObject` entities and are therefore absent
|
||||
from saved scenes, recovery documents, prefabs, and history snapshots.
|
||||
|
||||
Resolution changes are explicit destructive flat-grid replacements in the foundation inspector.
|
||||
Sculpt tools mutate the existing grid through grouped history transactions. A future external
|
||||
heightmap representation requires an explicit schema migration and authored-file ownership ADR; it
|
||||
must not silently rewrite an inline terrain during normal load.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Scene, prefab, undo, recovery, collaboration, and validation use one exact terrain document.
|
||||
- V1 grids are bounded to 1025×1025 samples to prevent accidental unbounded scene payloads.
|
||||
- Large production terrains may eventually need tiled external storage and streaming.
|
||||
- Foundation chunks remain raster-only in Solari until terrain layer materials have an exact Surface
|
||||
evaluator in `#24`; explicit exclusion is preferred to a black or mismatched ray-traced proxy.
|
||||
- Layer weights and sculpt strokes extend this descriptor contract in `#23`/`#24`; generated chunks
|
||||
remain disposable regardless of the editing representation.
|
||||
@@ -25,10 +25,12 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
| [material-system.md](material-system.md) | Shared Material/Material Instance assets, static/skinned renderer slots, Surface ABI, Solari scope, and migration |
|
||||
| [collaborative-file-safety.md](collaborative-file-safety.md) | Exact authored-file revisions, Git/read-only status, conflict recovery, and optional ownership providers |
|
||||
| [native-dialogs.md](native-dialogs.md) | Non-blocking file/folder/confirmation acquisition and main-thread result application |
|
||||
| [terrain.md](terrain.md) | Inline height-grid terrain, chunk hydration, collision, inspector workflow, and fixtures |
|
||||
| [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation |
|
||||
| [evaluations/material-library-targeted-drop/](evaluations/material-library-targeted-drop/) | Live screenshot and verification record for the docked Material Library and exact reversible surface drops |
|
||||
| [evaluations/collaborative-file-safety/](evaluations/collaborative-file-safety/) | Live screenshot and verification record for source-control status and guarded external-change recovery |
|
||||
| [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/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 |
|
||||
|
||||
@@ -38,6 +40,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 |
|
||||
| `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,42 @@
|
||||
# Terrain Foundation Evaluation
|
||||
|
||||
Date: 2026-07-12
|
||||
Branch: `codex/terrain-foundation`
|
||||
Gitea issue: `#22`
|
||||
|
||||
This record captures acceptance for the persistent height-grid terrain schema and deterministic
|
||||
runtime chunk hydration. The permanent workflow lives in the [terrain guide](../../terrain.md).
|
||||
|
||||
## Live Editor Evidence
|
||||
|
||||
The native Wayland debug editor loaded the committed
|
||||
`assets/levels/terrain_authoring_showcase.scn.ron` fixture. The screenshot uses Forward rendering to
|
||||
isolate mesh/material/light correctness while foundation terrain remains explicitly excluded from
|
||||
Solari until exact terrain layer/Surface parity lands in `#24`.
|
||||
|
||||

|
||||
|
||||
The 5×5 authored grid renders as the expected asymmetric hill, resolves the committed shared
|
||||
Material Instance, and is split into four 2×2-quad chunks with generated trimesh colliders. The
|
||||
authored scene contains no `HydratedTerrainChunk`, `Mesh3d`, or collider-constructor components.
|
||||
|
||||
## Acceptance Results
|
||||
|
||||
| Area | Result | Evidence |
|
||||
|------|--------|----------|
|
||||
| Schema and serialization | Pass | Versioned bounded descriptor, exact height count, finite-value and scale/chunk validation, RON round-trip test |
|
||||
| Chunk hydration | Pass | Deterministic four-chunk runtime fixture; topology test verifies 25 vertices and 96 indices for a 4×4-quad mesh |
|
||||
| Runtime-only ownership | Pass | Hydration test verifies children have mesh/collider/owner markers but no `LevelObject`, then verifies removal cleanup |
|
||||
| Actor/editor integration | Pass | First-class Terrain kind, registry descriptor, hierarchy/viewport icon, reflected Add Component and inspector transaction path |
|
||||
| Material behavior | Pass with boundary | Shared Material/Instance source resolves for raster; missing source uses visible fallback; Solari submission is explicitly excluded pending `#24` |
|
||||
| Project validation | Pass | 60 level dependencies, existing 5 non-blocking findings, 0 blocking errors |
|
||||
| Packaged acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged result is claimed here |
|
||||
|
||||
## Automated Verification
|
||||
|
||||
| Command/suite | Result |
|
||||
|---------------|--------|
|
||||
| Focused terrain descriptor/topology/hydration tests | 4 passed |
|
||||
| Editor component registry reflection contract | Pass |
|
||||
| `cargo check --workspace --all-targets` | Pass |
|
||||
| `cargo validate-levels --project .` | 60 dependencies, 5 findings, 0 blockers |
|
||||
Binary file not shown.
@@ -0,0 +1,38 @@
|
||||
# Terrain Authoring
|
||||
|
||||
Terrain is a first-class authored actor backed by `TerrainDesc`. Add it from the Inspector's
|
||||
**Add Component** shelf by searching for Terrain. It conflicts with other geometry sources on the
|
||||
same actor: Primitive, Brush, Static Mesh Renderer, and Skinned Mesh Renderer.
|
||||
|
||||
## Foundation Workflow
|
||||
|
||||
The Terrain card exposes grid resolution, sample spacing, height scale, chunk size, generated
|
||||
collision, shadows, base material status, and validation. **Resize Flat** deliberately replaces the
|
||||
height array with a flat grid; normal numeric edits retain all height samples. Every accepted edit is
|
||||
one reflected history transaction and rebuilds only that terrain's generated chunks.
|
||||
|
||||
`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
|
||||
stripping without requiring external assets.
|
||||
|
||||
## Data And Hydration
|
||||
|
||||
- Heights are finite normalized values multiplied by Height Scale at hydration time.
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
Sculpt brushes and grouped stroke undo are tracked by Gitea `#23`; material layers and weight
|
||||
painting are tracked by `#24`. The persistence decision is recorded in
|
||||
[ADR 0039](../adr/0039-inline-height-grid-terrain-foundation.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