Files
aevolution/docs/engineering/CLIENT.md
T
dingoandClaude Opus 5.5 28629e1001
Foundation / checks (ecs) (push) Successful in 2m23s
Foundation / checks (deploy) (push) Successful in 4m12s
Foundation / checks (tsan) (push) Successful in 11m26s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (network) (push) Canceled after 17m48s
Foundation / checks (postgres) (push) Canceled after 17m48s
Foundation / checks (checks) (push) Canceled after 17m53s
Foundation / checks (client) (push) Canceled after 17m58s
Cellular microscope UI: living cells, nutrient food, HUD and evolution cards
From the maintainer's design review. In cellular play the world sits in a rounded
eyepiece with a vignette:
- Cells are drawn from their phenotype: the membrane wall thickens with membrane
  mass, flagella follow speed, organelles follow energy conversion, and a dead
  cell's membrane is torn.
- Food patches are granules coloured by nutrient, so a nutrient that runs out
  loses its colour.

The side panels become a HUD:
- a status pill and Field notes;
- Vitals in readable units (nJ, ng) with bars toward the next bud;
- an action dock with the last result explained;
- a "Mutation ready [E]" callout opening an evolution window of cards with
  before/after drawings and per-nutrient costs, which also handles the end of a
  life.

New ink, lavender and amber palette. Client only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 08:53:55 -04:00

14 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. 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, 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.

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 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, 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.