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

71 lines
3.9 KiB
Markdown

[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.