Files
aevolution/docs/adr/0080-environment-presentation.md
T
2026-10-08 12:08:53 -04:00

3.9 KiB

[Reviewed]

ADR-0080: Revision-tagged environment presentation

Status

Accepted for the M9.4 engineering client. Colours, ramps and thresholds are presentation choices, not physical scales, biology or final player UI.

Context

M6.3 views carry typed quantities, explicit absence, tick, field watermark and per-chunk revisions, but also private store identities and validation tokens. The renderer must not retain those, must not turn missing data into zero, and must not grow geometry with world size. M9.7 will receive views from a server, so the presentation boundary cannot depend on local store objects.

Decision

Add an SDL-free, owned EnvironmentPresentation (include/evo/client/ environment_view.hpp): one Z slice of at most 256 copied cells, each with voxel, chunk revision, habitat box/volume, substrate, terrain material/fill, per-field presence (not_requested, missing, present) with fg/pJ quantity, and moisture status. create validates mask/presence consistency, habitat geometry, slice, strict (x, y) order and bounds; present_environment adapts a local M6.3 view and copies no tokens or store pointers. The type is the transport-neutral input for later server views; it is not a capability and never authorizes consumption.

EnvironmentLayer holds at most one presentation and the newest observed authority revision (identity, tick, field watermark). It rejects other worlds/frames and any regression of tick, field revision or a shared voxel's chunk revision; equal revisions are accepted (new footprint). A presentation is stale when an observed revision is ahead of it or the host reports failed validation; none when absent. Restore/reconnect to another lineage requires explicit reset.

build_environment (include/evo/render/environment.hpp) projects cells through the M9.3 camera into clipped logical rectangles, in cell order: terrain square, habitat encoding, voxel outline, then a status chip and legend. Encodings: present values on a fixed log2 density ramp (quantity/habitat um^3 over [-30, 12]); present zero black; missing a magenta checker; not requested a hollow grey outline; zero water capacity a distinct "undefined" colour. Stale dims fills and outlines voxels amber; the chip is green/amber/red for current/stale/none. Small cells collapse to one encoded rectangle. Output is at most 256*9+9 rectangles in a caller-reused buffer; no textures, caches or per-world allocation exist.

The engineering app owns an in-memory local fixture authority (FieldStore + ChunkStore) that performs conserved same-channel water moves via the public API and refreshes views at a configurable cadence. It is never persisted or published and is replaced by M9.7 server views. No new dependency, simulation rule or format.

Alternatives considered

  • Render directly from EnvironmentView: retains store identities/tokens and couples the renderer to local stores; rejected.
  • Auto-ranged colour scale per view: hides absolute change between refreshes.
  • Textures/field images: unnecessary for 256 bounded habitats; adds GPU lifetime.
  • Silently keeping the newest arrival: out-of-order updates could roll back state.

Benefits

Explicit absence/zero/unrequested/undefined/stale presentation, bounded memory and work, deterministic output and SDL-free tests; rendering cannot mutate resources.

Costs

Fixed ramp clamps extreme densities; one Z slice and one field per frame. Global field watermark marks whole views stale (ADR-0052 conservatism).

Risks

Colour choices are not accessibility-qualified; human visual and colour-vision review remain M9.8 work. Validation of authority revisions is only as honest as the host/server supplying them; M9.6/9.7 must authenticate and bound them.

Consequences

M9.5 adds organism presentation on the same frame budget; M9.7 builds EnvironmentPresentation from protocol views and feeds server watermarks to observe. Changing ramp/encoding semantics requires updating this ADR and tests.