Files
aevolution/docs/architecture/CLIENT_ARCHITECTURE.md
T
dingoandClaude Opus 5.5 9bb147de82 Implement M9.5 biology-derived organism rendering and inspector
Add OrganismPresentation cells derived via biology::derive_phenotype with
no controller, owner or level fields (pinned by test), so identical
biology renders identically for players and NPCs. OrganismLayer reuses
the ADR-0080 ordering/freshness semantics; death is a remnant state and
removal is absence. Rendering takes an explicit rectangle budget, falls
back to body-only detail and marks truncation instead of dropping data.
An opt-in rectangle-only hover inspector shows phenotype gauges; ImGui is
not adopted. ADR-0081 records the decision; evidence in VALIDATION.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 18:21:53 -04:00

4.4 KiB
Raw Blame History

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.

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 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, 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, 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. ImGui is not adopted.

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.