Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 2m23s
Foundation / checks (tsan) (push) Successful in 10m11s
Foundation / checks (client) (push) Failing after 14m26s
Foundation / checks (network) (push) Successful in 18m54s
Foundation / checks (checks) (push) Successful in 42m9s
Foundation / checks (postgres) (push) Successful in 43m51s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
188 lines
12 KiB
Markdown
188 lines
12 KiB
Markdown
# 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. Cellular play uses the authoritative
|
||
v10 server; the client presents observations and sends intentions. The separate
|
||
engineering motion probe predicts only its synthetic marker.
|
||
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: [M10 client sessions](../networking/M10_CLIENT_SESSIONS.md), ADR-0093
|
||
(the M9.7 path, ADR-0083, is no longer used by the client).
|
||
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`, 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
|
||
|
||
### Cellular v10
|
||
|
||
Choose **Cellular play (v10)** before connecting, or add `--cellular` to the
|
||
connection command. For the current M11.9 DEV opening use grants for world 100,
|
||
region 4 and fresh playtest accounts (ADR-0123). The client does not deploy or
|
||
provision a region.
|
||
|
||
- **Cell:** energy and C/N/P/other reserves, latest maintenance/movement/intake,
|
||
and Engulf/Bud buttons. Engulf and Bud are individual requests; automatic feeding
|
||
resumes after their action tick. The server chooses prey and funds/places descendants. Last observed
|
||
engulf/bud feedback stays visible with its tick, even after later idle ticks.
|
||
- **Food:** automatic feeding defaults on and targets the first stocked, contacted
|
||
patch in the owner's ordered view. Manual selection disables auto-feed; Stop
|
||
feeding disables it too. Speed (1-100%), precision (20% of selected speed), and
|
||
Slow near food are local intention preferences. The latter defaults on and limits
|
||
approach speed toward 500 um/s within 1 mm of a stocked patch, recomputed from the
|
||
observed phenotype. Protocol integer precision can exceed that cap at extreme
|
||
speeds. These preferences never change authoritative speed, contact or intake.
|
||
- **Evolution:** choose one unranked mutation from the owner's earned offer.
|
||
The current development-2 cellular trial uses per-second capability rates and
|
||
maintenance; mass is in femtograms. Plain-language descriptions explain each
|
||
capability change. Construction energy and all four matter costs use the amended
|
||
v10 candidate records (ADR-0129); choices are disabled when current reserves cannot
|
||
fund them. The server rechecks funding when the request commits.
|
||
- **Life ended:** the server's cause, when delivered, and **Start new life**.
|
||
Each new life uses a new request ID. Duplicate clicks and reconnects reuse the
|
||
outstanding request, and held world input is cleared while no current life is
|
||
available. A missing view alone is never presented as a known death.
|
||
- **Log:** the last eight discrete requests and optional engineering panels.
|
||
Sent/admitted are distinct from committed. A committed engulf/bud intention
|
||
does not itself prove biological success; the tick feedback reports its effect.
|
||
|
||
The dark teal UI uses the existing embedded scalable font. At narrow sizes the
|
||
Evolution panel becomes the **Life** tab; panels remain within the viewport and
|
||
scroll vertically. Existing Ctrl+= / Ctrl+- scaling and rebindable movement apply.
|
||
Food patches have a thin contact boundary and a stock marker, with amber for the
|
||
current target and dimming while disconnected. The camera starts at a closer 6 mm
|
||
view and keeps the followed cell beside the journal. Organism shapes and biological
|
||
colour encodings remain those of ADR-0081 for every controller.
|
||
|
||
One discrete request is outstanding at a time. During an automatic reconnect its
|
||
ID and original payload stay in memory. Bud/engulf recovery queries the original
|
||
action; mutation recovery repeats the exact selection. A lost reply remains
|
||
unresolved until an authoritative final result arrives. **Keep result as unknown**
|
||
retains it in the bounded record and permits another explicit request; it does
|
||
not cancel the original. Request history is not persisted across app exit or an
|
||
explicit disconnect to the launcher.
|
||
|
||
Existing protocol limits: a mutation result lost across a server restart may
|
||
remain unresolved (the host's final-choice replay cache is transient); type 27
|
||
death notices are not a historical death query. Automatic feeding uses observed
|
||
contact, so a patch crossed entirely between observations can still be missed;
|
||
slowing near food reduces that risk without predicting authority.
|
||
|
||
Food reading (2026-10-15): zoomed-in patches carry a gold `E` for remaining energy
|
||
and a teal `M` for remaining matter. The Food tab shows energy stock and all four
|
||
matter channels, and explicitly labels matter-only and depleted patches. Auto-feed
|
||
prefers an energy-bearing patch when several stocked patches touch the cell;
|
||
manual selection remains available. These stocks are shared and finite. Uptake
|
||
is capacity-limited and maintenance precedes feeding, so processing a feeding
|
||
attempt does not guarantee gaining energy or surviving. The Cell tab reports
|
||
net reserve change across successive observed ticks (including all spending),
|
||
last-tick upkeep/movement, and an energy-free target warning. It does not claim an
|
||
exact intake amount that v10 does not carry.
|
||
|
||
Pending birth feedback now says that the server has not confirmed a cell. The
|
||
client rechecks the same request every two seconds. A confirmed funding/placement
|
||
refusal or cancellation enables an explicit new request without requiring a first
|
||
world view. An existing-life result waits for that life instead. The scheduler
|
||
fix in ADR-0127 is also required on the server: a client upgrade cannot repair a
|
||
region tick blocked by an unfulfillable nursery request or replenish its nursery.
|
||
|
||
Coordinate contract discrepancy found during this work: the cellular bridge sends
|
||
ADR-0102 lower-left footprint coordinates through the general presentation's
|
||
centre-offset fields. Assistance deliberately interprets only cellular-session
|
||
coordinates as the bridge sends them. Renderer/bridge geometry changes are deferred:
|
||
a future scoped contract amendment should either carry an explicit coordinate
|
||
convention or consistently convert the cellular presentation to centres, updating
|
||
contact assistance, picking and replication tests together. This upgrade does not
|
||
silently change the shared organism geometry contract.
|
||
|
||
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.
|