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
107 lines
6.3 KiB
Markdown
107 lines
6.3 KiB
Markdown
# Native client boundary (M9.2–M9.5)
|
||
|
||
Implemented scope: desktop lifecycle and primitive presentation, not gameplay.
|
||
ADR-0077 selects SDL; ADR-0078 defines its ownership and view boundary.
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
App[evo-client main thread] --> Platform[Application / private SDL adapter]
|
||
App --> Frame[Owned immutable render Frame]
|
||
Platform --> Render[Private SDL renderer]
|
||
Frame --> Render
|
||
World[M6.3 EnvironmentView] -- copied once --> Views[EnvironmentPresentation / Layer]
|
||
Views --> Env[build_environment + Camera]
|
||
Env -- bounded rectangles --> Frame
|
||
Bio[M3 Phenotype] -- derive_phenotype --> Orgs[OrganismPresentation / Layer]
|
||
Orgs --> OrgRender[append_organisms + inspector]
|
||
OrgRender -- budgeted rectangles --> Frame
|
||
```
|
||
|
||
`include/evo/client/application.hpp` and `include/evo/render/frame.hpp` contain
|
||
no SDL, world-store, network or database types. The application owns one SDL
|
||
runtime, window and renderer on the process main thread; concurrent application
|
||
instances are rejected. Destruction releases renderer, window, then SDL. Partial
|
||
initialization releases everything acquired. No application object may outlive
|
||
main or be used/destroyed on another thread.
|
||
|
||
`Frame::create` validates and copies at most 4096 rectangles. Its const span is
|
||
valid until frame destruction/assignment. `Application::step(const Frame&)`
|
||
borrows it for the call only; there is no queue, stored pointer or simulation
|
||
mutation. Coordinates are logical window units, top-left origin, +Y down. They
|
||
are presentation units, never world millimetres. M9.3 implements world-screen mapping;
|
||
M9.4 projects environment samples. In particular, do not retain M6 validation
|
||
tokens/store pointers in a renderer or serialize them as a client protocol.
|
||
|
||
Window state records logical size, drawable pixel size and display content scale
|
||
separately. Resizes/display changes query SDL rather than trust event payloads.
|
||
Drawing scales independently by pixel/logical width and height; content scale is
|
||
for future UI sizing, not a second pixel multiplier. Hidden/minimized/zero-area
|
||
windows skip rendering. Focus loss disables the future input admission flag;
|
||
M9.3 clears all held intentions on admission loss. Close is terminal.
|
||
|
||
Each step consumes at most 256 events, filters window-specific events and renders
|
||
one frame. Target reset needs only redraw (no cached textures). Device reset
|
||
recreates the renderer from CPU frame data. Device loss, recreation/query/draw
|
||
failure latch an error until destruction; no silent backend substitution or busy
|
||
recovery loop. Typed errors reach the process boundary. The host paces frames
|
||
outside the renderer and catches allocation/standard-library exceptions.
|
||
|
||
M9.3 also exposes separate `poll_events()` and `present(frame)` calls so camera
|
||
mapping uses current resize/input state. SDL-free camera and input contracts are
|
||
specified in [CAMERA_INPUT.md](../engineering/CAMERA_INPUT.md) and ADR-0079.
|
||
UI capture and event-backlog handling suppress held world input; sequence/tick
|
||
intentions do not confer server authority. M9.6 owns session binding.
|
||
|
||
M9.4 ([ENVIRONMENT_RENDERING.md](../engineering/ENVIRONMENT_RENDERING.md),
|
||
ADR-0080) adds SDL-free `client/environment_view.hpp` and
|
||
`render/environment.hpp`. A presentation copies at most 256 cells of one Z slice
|
||
from a view and retains no store, token or native handle. `EnvironmentLayer`
|
||
holds one presentation, rejects foreign or regressed revisions and reports
|
||
none/current/stale against observed authority watermarks. The projection emits
|
||
at most 2313 clipped rectangles with explicit missing, unrequested, present-zero,
|
||
undefined and stale encodings. The client libraries link the headless world
|
||
library read-only; no world or simulation target links client code.
|
||
|
||
M9.5 ([ORGANISM_RENDERING.md](../engineering/ORGANISM_RENDERING.md), ADR-0081)
|
||
adds `client/organism_view.hpp`, `render/organism.hpp` and the engineering
|
||
`client/organism_inspector.hpp`. Organism cells carry phenotype, growth, position
|
||
and alive/dead only; no controller, owner or level field exists, so players and
|
||
NPCs share one presentation. Rendering takes an explicit rectangle budget and
|
||
reports truncation; the inspector draws biology gauges only. (M9.8c replaces it in
|
||
the app with the labelled toolkit Inspector; see below.)
|
||
|
||
M9.7 (ADR-0083): in remote mode the layers are owned by `network::SessionClient`,
|
||
filled only from server views; on loss they stay visible but stale, and every new
|
||
session resets them to the server's fresh baseline. The client never predicts.
|
||
|
||
Failure tests inject actual SDL events, including foreign window IDs, with no
|
||
test-only production hooks. Real device failures and physical DPI/input require
|
||
manual hardware qualification at M9.8. The native client is opt-in and never
|
||
enters a server container. Headless configuration does not prepare/load SDL.
|
||
|
||
|
||
M9.8b adds [owned UI state](../engineering/CLIENT_UI_STATE.md): bounded notifications
|
||
and one modal, independent of toolkit/render/simulation types. The native adapter
|
||
protects externally requested capture from the legacy Tab shortcut. Session event
|
||
backpressure preserves queued events, disconnects and resolves remaining local
|
||
uncertainty as unknown, then waits for draining before reconnecting. This is not
|
||
a durable outcome-history database.
|
||
|
||
M9.8c (ADR-0084) adds toolkit-independent launcher, selection, label and outcome-log
|
||
models in `src/client/ui`. Dear ImGui is confined to the platform adapter (overlay
|
||
callback, event routing first, capture flags) and `apps/evo-client/panels.cpp`;
|
||
library headers expose no toolkit type. Panels read presentation copies only and
|
||
return requested actions; the app owns sessions, fixture and selection.
|
||
|
||
M9.8d (ADR-0085) adds SDL-free bindings (actions vs HID key usages, validation,
|
||
versioned controls file) to `evo_client_controls`; the adapter maps keys through
|
||
them and offers binding capture ahead of toolkit and world input.
|
||
|
||
The v10 cellular app shows observed reserve differences as **net** changes across
|
||
the named tick interval, never as measured intake. Duplicate views retain the last
|
||
change; reconnect and a different life reset its baseline. Energy/matter patch
|
||
markers and stock cards use copied sensor data only. A final birth refusal permits
|
||
an explicit new request even before a perception arrives; pending/unknown requests
|
||
retain their ID and an existing-life result waits for that life. These are app
|
||
presentation/control policies, not biological rules.
|