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>
This commit is contained in:
@@ -71,8 +71,9 @@ Tab toggle is processed in event order, so subsequent presses after that toggle
|
||||
belong to its new capture state.
|
||||
|
||||
The standalone host uses an increasing **local fixture tick**, not server time.
|
||||
It draws a world-anchored rectangle, a capture indicator and an intention dot.
|
||||
Camera panning uses 400 logical units/second with elapsed time clamped to 0.1 s;
|
||||
wheel zoom uses 2^(steps/4). These are presentation controls. No network messages,
|
||||
world modifications or organism actions occur. M9.6 must bind intention ticks
|
||||
It draws a capture indicator, an intention dot and (since M9.4) the environment
|
||||
fixture. Camera panning uses 400 logical units/second with elapsed time clamped to
|
||||
0.1 s; wheel zoom uses 2^(steps/4). These are presentation controls. Input never
|
||||
sends network messages, modifies the world or acts for an organism; the M9.4
|
||||
fixture authority's own water moves are independent of input. M9.6 must bind intention ticks
|
||||
and counters to secure sessions; the server independently validates all requests.
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
# Native engineering client (M9.2–M9.3)
|
||||
# Native engineering client (M9.2–M9.4)
|
||||
|
||||
This opens a resizable native window containing a camera-controlled presentation fixture.
|
||||
It does not simulate a world, connect to a server or implement cellular gameplay.
|
||||
This opens a resizable native window showing camera-controlled environment habitats
|
||||
from a local in-memory fixture authority (M9.4). It does not run an ecosystem,
|
||||
connect to a server or implement cellular gameplay.
|
||||
Contract: [client architecture](../architecture/CLIENT_ARCHITECTURE.md), ADR-0078.
|
||||
Camera/input: [contracts and limits](CAMERA_INPUT.md), ADR-0079.
|
||||
Environment: [presentation and encodings](ENVIRONMENT_RENDERING.md), ADR-0080.
|
||||
|
||||
## Build and run
|
||||
|
||||
@@ -25,14 +27,18 @@ Close the window to exit. `--renderer software` or `--renderer vulkan` requests
|
||||
one explicit backend, without fallback. `--frames N` exits after N bounded steps
|
||||
(including paused steps), maximum 100000; `--hidden` opens without showing the
|
||||
window and pauses drawing. These options permit unattended smoke checks.
|
||||
Usage errors exit 2, lifecycle failures exit 1, orderly exit returns 0.
|
||||
`--layer NAME` selects the displayed field or `moisture`; `--refresh-every N`
|
||||
(1..1000 fixture authority ticks) delays view refresh so the stale state is visible.
|
||||
Usage errors exit 2, lifecycle/fixture failures exit 1, orderly exit returns 0.
|
||||
|
||||
Engineering controls: arrow keys pan, mouse wheel zooms around the pointer, WASD
|
||||
updates the small intention indicator without moving the world fixture. Tab
|
||||
toggles UI capture: the top-left bar turns orange and navigation/movement input
|
||||
is suppressed. Leaving capture/focus loss requires fresh presses. This is a
|
||||
focus exercise, not the final player UI. The host's input tick is a local fixture
|
||||
counter and is never interpreted as authoritative server time.
|
||||
counter and is never interpreted as authoritative server time. The top-right
|
||||
chip shows environment freshness (green current, amber stale, red none); the
|
||||
bottom-left legend shows the value ramp.
|
||||
|
||||
For native X11 regression on a CI host:
|
||||
|
||||
@@ -40,7 +46,9 @@ For native X11 regression on a CI host:
|
||||
xvfb-run -a env SDL_VIDEO_DRIVER=x11 ./build/client/evo-client-lifecycle-tests
|
||||
```
|
||||
|
||||
CTest uses the dummy driver. The lifecycle suite runs 32 open/destroy rounds,
|
||||
CTest uses the dummy driver. `client-environment` is an SDL-free suite for
|
||||
presentation validation, ordering/freshness, encodings, seams and bounds; it
|
||||
prints an `environment_profile` line (rectangles, bytes, microseconds per build). The lifecycle suite runs 32 open/destroy rounds,
|
||||
resize/scale queries, non-unit drawable-scale pixel checks, minimize/restore,
|
||||
show/hide, focus/foreign events, reset/loss and close. Separate process checks
|
||||
exercise initialization failure. Tests stay active under NDEBUG. Synthetic
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
# M9.4 microscopic environment rendering
|
||||
|
||||
Decision: [ADR-0080](../adr/0080-environment-presentation.md). 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.
|
||||
|
||||
```cpp
|
||||
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.
|
||||
@@ -3284,3 +3284,63 @@ No full headless suite or TSan rerun; owned client state remains main-thread-onl
|
||||
No physical keyboard/IME, human visual, real multi-monitor DPI, Wayland or real
|
||||
GPU-failure qualification is claimed from injected events and Xvfb. No network
|
||||
traffic, database, world mutation or deployment operation was introduced.
|
||||
|
||||
## M9.4 microscopic environment rendering — 2026-10-01
|
||||
|
||||
Implemented ADR-0080 and ENVIRONMENT_RENDERING.md: owned revision-tagged
|
||||
`EnvironmentPresentation` copied from M6.3 views (no tokens/store pointers),
|
||||
single-slot `EnvironmentLayer` ordering/freshness, and bounded camera-projected
|
||||
rendering with explicit missing, not-requested, present-zero, undefined-moisture
|
||||
and stale encodings. The app shows a local in-memory fixture authority (finite
|
||||
same-channel water moves via `FieldStore::transfer`); it is not a server view.
|
||||
|
||||
Executed:
|
||||
|
||||
- Windows MSVC 19.44 Release via `tools/windows-check.ps1 -Preset client -Action
|
||||
check` (run as a child `powershell.exe`): 4/4 labeled tests, including the new
|
||||
`client-environment` suite. App runs with `--frames 240/300`, `--refresh-every
|
||||
2`, `--layer organic-carbon` exited 0; `--layer bogus` exited 2;
|
||||
`SDL_VIDEO_DRIVER=evo-invalid` still fails at SDL initialization (error 2),
|
||||
after fixture creation, so `client-init-failure` keeps testing the SDL path.
|
||||
- Linux GCC 14 Release (`build/client-probe-linux`, probe + client): 6/6 labeled
|
||||
tests; native Xvfb/X11 lifecycle suite; X11 app runs (moisture, refresh 3).
|
||||
- Clang 19 Debug ASan/UBSan (`build/client-asan`): 4/4 labeled tests, native X11
|
||||
lifecycle, hidden X11 app (refresh 2), visible X11 moisture app and dummy-driver
|
||||
nitrogen app (400 frames, refresh 3) with leak detection, no suppressions.
|
||||
- clang-tidy 19 with warnings-as-errors on the four new/changed translation units:
|
||||
passed after reserving a test vector, widening a test product, and annotating
|
||||
two intentional out-of-range enum inputs (the rejection under test).
|
||||
Repository-wide clang-format 19 check passed.
|
||||
- Tests cover: synthetic known fields (exact ramp colour for log2 density -3,
|
||||
present zero, missing checker geometry, hollow unrequested outline, undefined
|
||||
zero-capacity moisture, collapsed small habitats); seams across chunk
|
||||
boundaries -16/0/16 at three zooms, three centres and two DPI ratios, compared
|
||||
with `Camera::world_to_screen`; voxels on the exclusive world bound; stale
|
||||
updates (older tick, chunk-revision regression, foreign world, regressed and
|
||||
pre-presentation watermarks, late-but-stale presentations, reset); failed
|
||||
local validation after a field transfer; unchanged field/terrain snapshots
|
||||
after presenting/rendering; presentations outliving their stores; 20 invalid
|
||||
presentation shapes; 330 camera/mode/freshness combinations over 256 cells,
|
||||
all within viewport, the 2313 bound, constant buffer capacity and Frame
|
||||
limits including host UI.
|
||||
- Profile (`environment_profile`, 256 visible cells, stale, nitrogen layer,
|
||||
checker detail): 1701 rectangles; 53,248 presentation-cell bytes; 46,260-byte
|
||||
reused output buffer; mean build 13.4 us (MSVC Release, this workstation),
|
||||
6.6 us (GCC 14 Release, WSL2), 175 us (Clang ASan Debug). Indicative only; no
|
||||
frame-time threshold is claimed.
|
||||
- Visual sanity check: the fixture's output was rasterized offline for water,
|
||||
stale, nitrogen (missing), moisture and organic-carbon (not requested). This
|
||||
raised the not-requested outline from grey 140 to 210 for contrast with rock.
|
||||
This is not human/colour-vision acceptance.
|
||||
- Headless: a fresh MSVC Release directory with both client options OFF built
|
||||
`evo-sim`; seed 123456 / eight entities / 1000 ticks replayed with unchanged
|
||||
`d61ad5bf0c928c76`, `replay_verified=true`.
|
||||
|
||||
Limits: pre-existing `build/release` failed to link untouched headless objects
|
||||
(unresolved MSVC STL `__std_rotate`/`__std_find_first_not_of_trivial_pos_1`),
|
||||
consistent with stale objects from a different STL build; the fresh directory
|
||||
above passed, and that directory was left as found. Docker/Gitea execution of the
|
||||
extended `ci-client` stage was not observed locally. No full headless suite or
|
||||
TSan rerun (headless sources unchanged; client state is main-thread-only). No
|
||||
physical DPI, real GPU, Wayland, accessibility or human visual acceptance is
|
||||
claimed. No network traffic, database, deployment or persistent format changed.
|
||||
|
||||
Reference in New Issue
Block a user