71 lines
3.9 KiB
Markdown
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.
|