Files
aevolution/docs/engineering/ENVIRONMENT_RENDERING.md
dingoandClaude Opus 5.5 feca07f791 Implement M9.4 revision-tagged microscopic environment rendering
Add SDL-free owned EnvironmentPresentation copied from M6.3 views (no
store pointers or validation tokens), a single-slot EnvironmentLayer that
rejects foreign/regressed updates and reports none/current/stale against
observed authority watermarks, and a bounded camera projection with
explicit missing, not-requested, present-zero, undefined-moisture and
stale encodings (at most 2313 clipped rectangles, reused buffer).

The engineering app renders a local in-memory fixture authority with
configurable refresh cadence and layer selection. ADR-0080 records the
decision; validation evidence and limits are in VALIDATION.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 17:45:53 -04:00

5.0 KiB

M9.4 microscopic environment rendering

Decision: ADR-0080. Headers: include/evo/client/environment_view.hpp (presentation values, freshness) and include/evo/render/environment.hpp (rectangle projection). Neither includes SDL. Dependency direction: world (read-only views) -> client views -> render environment -> immutable Frame -> private SDL renderer. Nothing flows back.

auto view = world::query_environment(fields, terrain, tick, footprint, mask);
auto presentation = client::present_environment(*view, slice_z); // owned copy
layer.accept(std::move(*presentation));             // rejects foreign/regressed
layer.observe({identity, authority_tick, field_watermark}); // later: stale?
render::build_environment(rects, layer.current(), layer.freshness(), camera, display);

Presentation values

A presentation is one Z slice of 1..256 cells, strictly ordered by voxel (x, y), with the source revision (world/frame, tick, field watermark) and request mask. Cells copy chunk revision, the habitat box and volume, substrate, terrain material and fill, per-field presence/quantity and moisture status. Validation rejects inconsistent presence vs mask, quantities on non-present fields, habitat boxes outside their voxel, volume mismatch, out-of-range voxels, mixed slices, duplicates/unsorted cells and invalid saturation. No store pointer, ChunkView token, native handle or authority capability is retained. A presentation stays valid after its source stores are destroyed.

Freshness and update ordering

EnvironmentLayer keeps at most one presentation (no history or queue) and the newest observed authority revision. accept rejects another world/frame (foreign_world) or any regression of tick, field watermark or a shared voxel's chunk revision (regressed) without mutation. Equal revisions are accepted so a camera-driven footprint change can replace the cells. observe records the authority's latest revision (also before the first presentation); a regressed or foreign watermark rejects. Freshness is:

State Meaning Presentation
none nothing accepted (or reset) red chip, no cells
current presentation equals newest observed revision green chip
stale authority advanced, or host validation failed (mark_stale) amber chip, dimmed fills, amber voxel outlines

A late presentation newer than the displayed one but older than the observed watermark is accepted and shown stale. Restore/reconnect requires reset; ADR-0052 restored stores are different owners, so their revisions need not continue.

Encodings

Each visible cell emits: terrain square (material colour blended from void by fill; unknown material IDs are cyan), habitat encoding, then a voxel outline when the voxel is at least 8 logical units wide. Habitat encodings:

Data Encoding
present, nonzero ramp(log2(quantity / habitat um^3) mapped from [-30, 12])
present zero black fill
requested but missing 2x2 magenta/dark checker
not requested hollow grey outline
moisture with zero water capacity rust "undefined" fill
moisture available ramp(saturation) linear in [0, 1]

Mass is fg, energy pJ; both use density per cubic micrometre of the habitat's effective volume. Values outside the ramp clamp to its ends; the eight-step legend (bottom-left) shows the ramp, not physical units. Habitats under 4 logical units collapse to one rectangle in the encoding's primary colour, so missing remains magenta and not-requested grey. Nothing is interpolated between habitats and no value is inferred from material IDs.

Geometry and resource bounds

Projection uses the CAMERA_INPUT formula on voxel edges, so shared edges between neighbouring voxels (including signed chunk seams) are computed from identical world coordinates. Edges may lie on the exclusive world bound. Cells fully outside the viewport emit nothing; others clip to [0, width] x [0, height] before float conversion. Output is at most 256 * 9 + 9 = 2313 rectangles, within the 4096 frame limit including host UI. build_environment clears and reserves the caller's buffer once; reuse keeps capacity constant. No textures or caches exist.

Engineering app

evo-client hosts a local in-memory fixture authority: 16x8 habitats at z=-16000 with varied boxes, varying water and organic energy, present-zero phosphorus and never-opened nitrogen/incident energy. Every 60 frames it advances its tick and moves 1/8 of one site's water to a neighbour through FieldStore::transfer. --refresh-every N (1..1000, default 1) refreshes the view every N authority ticks; between refreshes the observed watermark shows the stale state. --layer selects water, nitrogen, phosphorus, organic-carbon, organic-nitrogen, organic-phosphorus, organic-other, organic-energy, incident-energy, heat or moisture. The fixture is never persisted or published; M9.7 replaces it with server views. It is not biology, an ecosystem or a world-generation rule.