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.