Files
dingo 8ce609d344
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m32s
Foundation / postgres-tools (push) Successful in 26s
Foundation / server-image (push) Successful in 4m11s
Foundation / image (push) Successful in 4m36s
feat(client): add liquid presentation and clearer cellular HUD
2026-10-22 09:08:03 -04:00

225 lines
14 KiB
Markdown
Raw Permalink 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. 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.
**Microscope view** (2026-10-16, cellular play): the world sits inside a rounded eyepiece
with a vignette. Cells are drawn from their phenotype: a membrane whose wall thickens
with membrane mass, one flagellum per 150 um/s of speed, coral organelles by energy
conversion, a torn membrane when dead. Food patches are granules coloured by nutrient
(energy gold, carbon umber, nitrogen blue, phosphorus rose, other grey); a nutrient
that runs out loses its colour. The HUD:
- a status pill;
- Field notes (legend, food in range, steering, recent actions, help);
- Vitals (energy and matter in readable units, bars toward the next bud);
- an action dock (feed, engulf, bud, last result);
- a "Mutation ready [E]" callout opening the evolution window (cards with before/after
drawings and per-nutrient costs, Choose, Decline all), which also shows the end of
a life.
The toolkit draws these shapes; the rectangle renderer still draws everything else.
**Sign in / Register** (Windows, ADR-0131) opens the system browser for Keycloak.
After sign-in the client fetches a 10-minute grant from `grants.aeternalisgames.com`
and connects to the cellular DEV region. It renews the grant before expiry and after a
lost connection. **Play in DEV** reconnects while signed in. **Sign out** closes the
session and revokes the login. `--profile NAME` keeps a separate saved login per
profile, so two clients on one machine can use two accounts; the browser always
shows the login form, so you choose the account. Start them one at a time: sign-in
uses loopback port 47600. Only the region CA file is still read from the form.
The manual endpoint and grant-bundle fields stay under "Manual connection
(developer grants)".
## 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 blue-green 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.
## 2026-10-22 liquid presentation
[The native visual refresh](CLIENT_VISUAL_REFRESH.md) adds blue-green optical
texture, flowing current ribbons, nutrient silhouettes, thin pool membranes,
a shared brighter cell palette and colored action buttons. Field notes, Vitals
and Nearby can minimize and restore. Nearby is a camera-centred map of received
observations with a local-axis compass; it never reveals hidden food. Temperature
readouts remain explicitly unavailable until phase 3 and a session contract carry
real body/ambient observations. No simulation or protocol version changes.