Files
aevolution/docs/engineering/CLIENT.md
T
dingoandClaude Opus 5.5 feca07f791 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>
2026-10-01 17:45:53 -04:00

3.6 KiB
Raw Blame History

Native engineering client (M9.2–M9.4)

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, ADR-0078. Camera/input: contracts and limits, ADR-0079. Environment: presentation and encodings, ADR-0080.

Build and run

After explicit SDL preparation, in a compiler shell:

cmake --preset client
cmake --build --preset client --parallel 4
ctest --preset client --no-tests=error
./build/client/evo-client

Windows: tools/windows-check.ps1 -Preset client -Action check configures the MSVC environment. Use .exe for executable paths. Linux requires the X11 or Wayland development packages described in the dependency guide; the Docker ci-client stage supplies the tested X11 subset.

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

xvfb-run -a env SDL_VIDEO_DRIVER=x11 ./build/client/evo-client-lifecycle-tests

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 events and software rendering do not qualify physical DPI, keyboard, GPU loss or compositor behavior; those remain a hardware matrix at M9.8.

Analysis/sanitizers use the existing options, for example configure --preset asan -B build/client-asan -DEVO_BUILD_CLIENT=ON with Clang 19. This instruments owned frame/platform/app/test code, not SDL/system libraries. Linux X11 builds link X11 directly (SDL_X11_SHARED=OFF) to preserve library lifetime across SDL cycles. No preload or leak suppression is required. The diagnosed M9.1 dynamic unload behavior and qualification evidence are documented in VALIDATION.md.

Headless defaults keep both EVO_BUILD_CLIENT and EVO_BUILD_CLIENT_PROBE OFF. No prepared SDL sources, display or client runtime are needed for evo-sim or server tests. No Kubernetes deployment change belongs to this desktop gate.