Run a non-blocking TLS 1.3 session server inside evo-server's loop: environment views come from the region's own field/terrain stores with an explicitly empty organism presentation; admitted intentions ride the next synthetic input (content unchanged) and return a durable no-effect outcome from the host's final acknowledgement, or not_committed when dropped. Sessions are bound to their connection, epochs close stale sessions, and connections have bounded output, input rate and deadlines. SessionClient and evo-client --connect consume one single-use grant per Hello (refusals before admission keep it), reset to a fresh baseline on every session, keep stale views visible and report in-flight intentions as unknown after loss. evo-dev-session generates dev credentials, grant bundles and runs a restart probe. The dev deployment gains a drill-time, loopback-only listener with an optional Secret, enforced by the policy check, and tools/ops/session-drill.sh. Protocol v1 gains IntentOutcome and the capacity close reason before any deployment. ADR-0083 records the maintainer-confirmed decisions; M8-dev/stage remains not passed and no cluster change was made. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
79 lines
4.4 KiB
Markdown
79 lines
4.4 KiB
Markdown
# Native engineering client (M9.2–M9.7)
|
||
|
||
This opens a resizable native window showing camera-controlled environment habitats
|
||
and biology-derived organisms (M9.5) from a local in-memory fixture authority.
|
||
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.
|
||
Organisms/inspector: [encodings and budget](ORGANISM_RENDERING.md), ADR-0081.
|
||
Remote dev region: [operations](../networking/DEV_SESSION_OPERATIONS.md), ADR-0083.
|
||
`--connect HOST:PORT --server-name NAME --ca FILE --grants FILE` (preset
|
||
`client-network`) replaces the local fixture with a dev session: views come from the
|
||
region, WASD sends intentions, and chips at y=72 show the connection (green/amber/red)
|
||
and the last intention (white admitted, green durable, red rejected, grey unknown).
|
||
|
||
## 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.
|
||
`--inspect` shows biology gauges for the organism under the pointer.
|
||
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
|
||
chips show environment then organism freshness (green current, amber stale, red
|
||
none; magenta marker: organisms truncated); the bottom-left legend shows the ramp.
|
||
The organism cluster is near (410 mm, 480 mm); zoom in with the wheel 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.
|