Files
aevolution/docs/engineering/CLIENT.md
T
dingoandClaude Opus 5.5 1819ebc0ab
Foundation / checks (checks) (push) Successful in 32m47s
Foundation / checks (client) (push) Failing after 10m1s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m53s
Foundation / checks (network) (push) Successful in 11m18s
Foundation / checks (postgres) (push) Successful in 40m20s
Foundation / checks (tsan) (push) Successful in 7m46s
Foundation / postgres-tools (push) Skipped
Foundation / image (push) Skipped
Foundation / server-image (push) Skipped
Switch the engineering client to M10 sessions (M10.5c)
evo-client's remote mode now runs over RegionSessionClient (QUIC, session
v2): snapshot-fed environment and organism views, the camera following the
server's view until the user moves it and then driving the interest, intention
records with a simulated state, and reconnects with the next grant of a bundle.
The launcher reads 160-byte M10 grants and defaults to the dev route.

- quic::resolve_ipv4 shared by the client and evo-session-probe
- evo-session-probe grants: owner-only bundles of 1-64 grants
- evo-server --m10-max-grant-lifetime (dev only, 60..3600 s)
- presets client-network/client-package build QUIC; msquic links the CRT
  fully static; msquic.dll and msquic/OpenSSL licences in the Windows package
- client-remote-session test against a loopback region
- ADR-0093/0091/0086 amendments, M10_CLIENT_SESSIONS guide, validation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 11:57:07 -04:00

6.3 KiB
Raw Blame History

Native engineering client (M9.2–M9.8d)

This opens a resizable native window showing camera-controlled environment habitats and organisms either from a local in-memory fixture authority or from one dev region over an authenticated dev session. It does not run an ecosystem locally, predict remote state or implement cellular gameplay. Contract: client architecture, ADR-0078. Camera/input: contracts and limits, ADR-0079. Environment: presentation and encodings, ADR-0080. Organisms/inspector: encodings and budget, ADR-0081. Remote dev region: M10 client sessions, ADR-0093 (the M9.7 path, ADR-0083, is no longer used by the client). Engineering panels and launcher: UI state, ADR-0084.

Without arguments a launcher opens. Local fixture is labelled as an in-memory stand-in, never as a server or ecosystem. Connect (preset client-network, with QUIC) reads the endpoint, server name, dev CA file and M10 grant bundle file when pressed; nothing is saved and no path, certificate or grant byte is shown or logged. Errors use fixed wording. A connection with no Welcome after three failed attempts (refused, TLS failure or timeout) or a refused grant fails with Retry/Cancel. --fixture or --connect HOST:PORT --server-name NAME --ca FILE --grants FILE skip the launcher (an unreadable file then exits 1). While running, a banner names the mode (LOCAL FIXTURE or DEV REGION with its phase); Disconnect asks for confirmation. The Session panel shows session/epoch, server tick, simulated watermark, grants left, the snapshot, interest and snapshot bytes, and the last ten intentions with their outcome (sent, admitted, rejected, simulated, unknown; M10.5c). That list is the record; short notifications expire and can be dismissed.

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. Controls are saved to controls-v1.txt in the per-user settings directory (Windows: %APPDATA%\Aeternalis Games\Evolution Engineering Client); --controls FILE uses another file and --show-controls opens the Controls panel at start. An invalid file is reported, left unchanged, and defaults apply. --version prints the build identity (unpackaged outside packaging; ADR-0086, packaging). --pick X,Y performs one scripted world click at window coordinates and --screenshot FILE.bmp (requires --frames) saves the last frame; both exist for unattended visual review. Usage errors exit 2, lifecycle/fixture failures exit 1, orderly exit returns 0.

Engineering controls (defaults; rebindable, ADR-0085): arrow keys pan, mouse wheel zooms around the pointer, WASD updates the small intention indicator (sent as intentions in remote mode). A left click without dragging selects the topmost organism, else the habitat cell, for the Inspector; a click that lands on a panel or dismisses a notification never selects through it. Toolkit events are processed first: while a text field is focused or the pointer is over a panel, keys/wheel/clicks do not reach the world. Tab toggles UI capture (fixture or remote view): the bottom-left bar turns orange and navigation/movement input is suppressed until Tab is pressed again. Leaving capture/focus loss requires fresh presses. Choosing Local fixture ends any remote attempt; nothing connects or sends behind the LOCAL FIXTURE banner. The host's input tick is a local fixture counter and is never interpreted as authoritative server time. The top-right chips show environment then organism freshness (green current, amber stale, red none; magenta marker: organisms truncated); the Legend panel explains the layer scale and missing/zero/not-requested/stale encodings. The fixture organism cluster is near (410 mm, 480 mm); zoom in to see it.

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). client-organisms covers phenotype derivation, controller parity, death/removal, dense scenes and truncation, ordering, picking and the inspector. 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.