Files
aevolution/docs/engineering/CLIENT.md
T
dingoandClaude Opus 5.5 6262c778c7 Add M9.8e reproducible Windows client package
Static-runtime client-package preset with /Brepro and a build identity printed by
evo-client --version (ADR-0086). tools/client packages an explicit allowlist with
licence texts from the verified sources, BUILD-INFO and SHA256SUMS into a
deterministic ZIP, refusing credentials, profile paths and non-system imports;
verification runs the extracted client without Visual Studio, and a self-test
proves each guard. Publication via Gitea Actions waits for a Windows runner.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 16:48:12 -04:00

105 lines
6.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](../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.
Organisms/inspector: [encodings and budget](ORGANISM_RENDERING.md), ADR-0081.
Remote dev region: [operations](../networking/DEV_SESSION_OPERATIONS.md), ADR-0083.
Engineering panels and launcher: [UI state](CLIENT_UI_STATE.md), 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`)
reads the endpoint, server name, dev CA file and 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, durable
watermark, grants left and the last ten intentions with their outcome (sent,
admitted, rejected, durable, not committed, unknown). That list is the record;
short notifications expire and can be dismissed.
## Build and run
After [explicit SDL preparation](CLIENT_DEPENDENCIES.md), in a compiler shell:
```sh
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](CLIENT_PACKAGING.md)).
`--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:
```sh
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.