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>
This commit is contained in:
dingo
2026-10-01 18:21:53 -04:00
co-authored by Claude Opus 5.5
parent feca07f791
commit 9bb147de82
21 changed files with 1169 additions and 33 deletions
+7 -1
View File
@@ -410,7 +410,13 @@ fixture ticks, not server time.
ordered freshness (none/current/stale) and bounded camera-projected rendering
with explicit missing, unrequested, present-zero and undefined encodings under
ADR-0080. A local in-memory fixture authority stands in for server views until
M9.7. Evidence in engineering/VALIDATION.md. Next gate: M9.5.
M9.7. Evidence in engineering/VALIDATION.md.
**M9.5 status (2026-10-01):** biology-derived organism presentations with no
controller/ownership fields, identical rendering for identical phenotypes,
alive/dead/removed handling, budgeted detail with explicit truncation, and an
opt-in rectangle-only engineering inspector under ADR-0081. ImGui is not adopted.
Evidence in engineering/VALIDATION.md. Next gate: M9.6.
**Goal:** a native desktop cellular viewer/controller with input, camera, renderer,
readable organism/environment views and a real development-server connection.
+15 -13
View File
@@ -2,20 +2,22 @@
## Current gate — 2026-10-01
M9.4 renders microscopic environment views
([ADR-0080](adr/0080-environment-presentation.md)). The client copies M6.3 views
into owned, revision-tagged presentations; `EnvironmentLayer` rejects foreign or
regressed updates and shows none/current/stale against observed authority
watermarks. Habitats, terrain cells and voxel boundaries project through the
M9.3 camera into at most 2313 clipped rectangles, with explicit missing,
not-requested, present-zero, undefined-moisture and stale encodings. See
[ENVIRONMENT_RENDERING.md](engineering/ENVIRONMENT_RENDERING.md) and
[VALIDATION.md](engineering/VALIDATION.md). Remote Gitea client execution of the
extended CI stage remains unverified locally.
M9.5 renders organisms and an engineering debug view
([ADR-0081](adr/0081-organism-presentation.md)). Organism presentations are
derived from M3 phenotypes and contain no controller, owner or level field, so
identical biology renders identically for players and NPCs. Death shows as a
remnant; removal is absence. Rendering is budgeted with explicit truncation; the
opt-in inspector draws biology gauges only. ImGui is not adopted. See
[ORGANISM_RENDERING.md](engineering/ORGANISM_RENDERING.md) and
[VALIDATION.md](engineering/VALIDATION.md). Remote Gitea execution of the
extended client CI stage remains unverified locally.
Next: **M9.5**, organism and debug views. The app's environment comes from a local
in-memory fixture authority, not a connected region; its tick is a fixture counter.
No deployment, simulation rules, persistent formats or world snapshots changed.
Next: **M9.6**, the narrow secure dev-session protocol. The app still shows a local
in-memory fixture (static organism population, environment water moves); no
ecology runs in the client and no deployment, rule or format changed.
M9.4 added owned revision-tagged environment presentations and explicit
missing/stale rendering ([ADR-0080](adr/0080-environment-presentation.md)).
M9.3 added local-mm pan/zoom camera mapping and bounded sequence/tick input
intentions ([ADR-0079](adr/0079-camera-and-input-intentions.md)).
+69
View File
@@ -0,0 +1,69 @@
# ADR-0081: Biology-derived organism presentation and engineering inspector
## Status
Accepted for the M9.5 engineering client. Colours, scales, floors and gauge
mappings are presentation choices, not biology rules or final player UI.
## Context
The vision requires shared presentation: perceivable biological state follows the
same rules for players and NPCs, with no player/NPC/level/ownership labels. The
M3 contract derives a `Phenotype` from genome, growth and environment. No placed,
authoritative organism view exists yet (the M1 particle fixture must not be
mapped into the habitat plane), and organisms are micrometre scale beside 1 m
voxels. A debug view is needed without letting debug ownership leak into play.
## Decision
Add `OrganismPresentation` (include/evo/client/organism_view.hpp): up to 1024
copied cells in one Z slice, ordered by an opaque id, each holding voxel and
micrometre centre offset, the M3 `Phenotype`, `GrowthState` and alive/dead state.
The cell has **no controller, owner, account, name, level or player/NPC field**;
a structured-binding test pins the field list. `present_organism` derives the
phenotype with `biology::derive_phenotype`, so visuals come only from biology.
Removal is absence from a later presentation. `OrganismLayer` reuses ADR-0080
ordering/freshness semantics (identity, tick, revision; none/current/stale).
`append_organisms` (include/evo/render/organism.hpp) projects bodies through the
camera: side = extent (with a uniform 5-unit visibility floor), body colour from
conversion, realized growth and damage, a membrane outline sized by membrane mass
share, a motility ring when movement speed is nonzero, an ingestion mark scaled
by log ingestion rate. Dead remnants blend toward a remnant colour and drop the
ring/mark. Collapsed bodies get a dark halo. Output respects a caller budget: full
detail when every visible organism fits at 10 rectangles, otherwise one body each;
any organisms beyond the budget are counted, not drawn, and a magenta truncation
marker appears beside the organism freshness chip. Order is id order.
The engineering inspector (include/evo/client/organism_inspector.hpp, src/client/ui)
picks the topmost organism under the pointer using the same drawn bounds, and
draws a highlight plus ten normalized phenotype gauges. It shows biology values
only; there is nothing else to show. It is opt-in (`--inspect`).
ImGui remains optional and is **not adopted**: rectangles suffice for gauges, and
a UI library would need its own dependency ADR, text/font handling and input
capture integration. Revisit when engineering text is needed (M9.8 or later).
The app adds a static fixture population built from real genomes. No ecology,
movement or lifecycle runs in the client; the host does not decide energy,
mutation, reproduction or death.
## Alternatives considered
- Per-controller colour or icon: violates shared presentation; rejected.
- True-scale only: micrometre organisms vanish at habitat zoom; the floor is
uniform and documented, with true values available in the inspector.
- Dropping organisms silently over budget: hides data; truncation is explicit.
- ImGui inspector now: dependency and text scope not justified for this gate.
## Benefits
Biology-only, deterministic, bounded output; identical rendering for identical
biology regardless of host bookkeeping; testable without SDL.
## Costs
Below the floor, drawn sizes do not compare; gauges have no numeric text. Single
Z slice and 1024 organisms per presentation.
## Risks
Gauge/colour choices are not accessibility-qualified. A future host could still
add labels outside these APIs; review must keep debug overlays out of player UI.
## Consequences
M9.7 builds `OrganismPresentation` from server views. Any new visual parameter
must derive from biology and update this ADR, tests and ORGANISM_RENDERING.md.
+1
View File
@@ -92,3 +92,4 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0078: Native client lifecycle](0078-native-client-lifecycle.md) - main-thread RAII application, immutable presentation frames and explicit surface/device failure handling.
- [ADR-0079: Camera and input intentions](0079-camera-and-input-intentions.md) - local-mm projection, bounded sequence/tick intentions, focus/UI capture and explicit host event ordering.
- [ADR-0080: Environment presentation](0080-environment-presentation.md) - owned revision-tagged environment presentations, ordered freshness and bounded explicit missing/stale rendering.
- [ADR-0081: Organism presentation](0081-organism-presentation.md) - biology-only organism cells without controller labels, budgeted rendering with explicit truncation and an engineering gauge inspector; ImGui deferred.
+11 -1
View File
@@ -1,4 +1,4 @@
# Native client boundary (M9.2–M9.4)
# 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.
@@ -12,6 +12,9 @@ flowchart LR
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
@@ -59,6 +62,13 @@ 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. 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
+3 -2
View File
@@ -46,8 +46,9 @@ the simulation state. Durable account references live in orchestration mapping.
M9.2 implements the opt-in [native client boundary](CLIENT_ARCHITECTURE.md):
copied immutable presentation frames and one main-thread platform owner. M9.4
projects owned copies of M6.3 environment views (ADR-0080); the dependency runs
world -> client views -> render only. It does not yet render organisms or connect
to a region server.
world -> client views -> render only. M9.5 renders organisms from M3 phenotypes
(ADR-0081) without controller or ownership labels. It does not yet connect to a
region server.
| Boundary | Owns | Must not own |
|---|---|---|
+11 -5
View File
@@ -1,11 +1,13 @@
# Native engineering client (M9.2–M9.4)
# Native engineering client (M9.2–M9.5)
This opens a resizable native window showing camera-controlled environment habitats
from a local in-memory fixture authority (M9.4). It does not run an ecosystem,
and biology-derived organisms (M9.5) from a local in-memory fixture authority.
It does not run an ecosystem,
connect to a server or implement cellular gameplay.
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.
## Build and run
@@ -29,6 +31,7 @@ one explicit backend, without fallback. `--frames N` exits after N bounded steps
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.
`--inspect` shows biology gauges for the organism under the pointer.
Usage errors exit 2, lifecycle/fixture failures exit 1, orderly exit returns 0.
Engineering controls: arrow keys pan, mouse wheel zooms around the pointer, WASD
@@ -37,8 +40,9 @@ toggles UI capture: the top-left bar turns orange and navigation/movement input
is suppressed. Leaving capture/focus loss requires fresh presses. This is a
focus exercise, not the final player UI. The host's input tick is a local fixture
counter and is never interpreted as authoritative server time. The top-right
chip shows environment freshness (green current, amber stale, red none); the
bottom-left legend shows the value ramp.
chips show environment then organism freshness (green current, amber stale, red
none; magenta marker: organisms truncated); the bottom-left legend shows the ramp.
The organism cluster is near (410 mm, 480 mm); zoom in with the wheel to see it.
For native X11 regression on a CI host:
@@ -48,7 +52,9 @@ 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). The lifecycle suite runs 32 open/destroy rounds,
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
+82
View File
@@ -0,0 +1,82 @@
# M9.5 organism rendering and engineering inspector
Decision: [ADR-0081](../adr/0081-organism-presentation.md). Headers:
`include/evo/client/organism_view.hpp`, `include/evo/render/organism.hpp`,
`include/evo/client/organism_inspector.hpp`. None includes SDL. Dependency
direction: biology (phenotype) -> client views -> render organism -> client UI
inspector -> immutable `Frame`. Environment rules (ADR-0080) are unchanged.
```cpp
auto cell = client::present_organism(id, voxel, x_um, y_um, genome, growth, environment,
client::OrganismState::alive); // derive_phenotype
layer.accept(*client::OrganismPresentation::create(revision, slice_z, cells));
render::append_organisms(rects, budget, layer.current(), layer.freshness(), camera);
if (auto i = client::pick_organism(*layer.current(), camera, pointer))
client::append_inspector(rects, client::inspector_rectangles, layer.current()->cells()[*i], camera);
```
## Shared presentation rule
An `OrganismCell` holds only: opaque id (draw order, never displayed), voxel and
micrometre centre offset, `Phenotype`, `GrowthState`, alive/dead. There is no
controller, owner, account, name, level or player/NPC field, and no API accepts
one. Identical biology renders identically wherever the host keeps its controller
bookkeeping; tests verify byte-identical rectangles and inspector panels for a
player-controlled and an NPC organism with the same genome and growth.
## Validation and ordering
Presentations hold 0..1024 cells (empty is valid: no organisms in view), strictly
ascending nonzero ids, one Z slice, offsets in [0, 1e6) um, consistent masses
(total = structural + membrane), extent within one voxel, conversion/growth/damage
<= 1000 per thousand and a known state. `OrganismLayer` rejects foreign worlds and
regressed tick/revision, tracks observed watermarks and reports none/current/stale
like `EnvironmentLayer`. Death is a state; removal is absence from a later
presentation. Neither is decided by the client.
## Visual encodings
| Biology | Encoding |
|---|---|
| extent (um) | body side at camera scale; minimum 5 logical units for all organisms |
| conversion per thousand | body hue, teal (0) to amber (1000) |
| realized growth | body brightness, 40% to 100% |
| damage | blend toward red, up to 80% |
| membrane mass share | light outline, thickness side*share/2 in [1, side/4] |
| movement speed > 0 | light ring 2 units outside the body (alive only) |
| ingestion rate > 0 | dark central mark, 15%..50% of side by log10 rate over 6 decades (alive only) |
| dead | body blended 75% toward remnant brown; no ring or mark |
| stale presentation | all organism colours dimmed; amber organism chip |
Bodies under 6 units draw as a dark halo plus body. Thermal shortfall,
maintenance and mass are inspector-only. The organism freshness chip sits below
the environment chip (top-right): green current, amber stale, red none. A magenta
marker left of it means organisms were not drawn because of the frame budget.
## Budget
`append_organisms` appends at most `budget` rectangles (minimum 2 for the chip and
marker). If every visible organism fits at 10 rectangles, full detail is used;
otherwise each visible organism is a single body; beyond the budget, organisms are
counted as visible but not drawn and the marker appears. The engineering app
budgets 4096 - 2313 (environment) - 25 (inspector) - 3 (host UI) = 1755, so 1024
organisms always fit as bodies. No textures, caches or history are kept.
## Engineering inspector
`--inspect` enables hover inspection: the topmost organism whose drawn (floored)
box contains the pointer gets a white highlight, and a bottom-right panel shows
ten gauges in order: extent (log10 over 3 decades um), total mass (12 decades fg),
membrane share, maintenance (12 decades pJ/tick), movement speed (5 decades),
ingestion rate (6 decades), conversion, realized growth, damage, thermal shortfall
(5 decades mK). The panel darkens to brown for remnants. Rectangles only: there is
no text, ImGui or input capture; this is engineering UI, not player UI.
## Fixture population
The app adds 48 organisms from real genomes: a 4x4 cluster 60 um apart near the
(0, 0) voxel's 410 mm / 480 mm offset for zoomed viewing, and one in every second
voxel along x and y.
Genome parameters, growth and damage vary by id; ids 5 and 23 are dead remnants.
It is static presentation data refreshed with the environment cadence, not an
ecosystem, controller or spawning rule.
+45
View File
@@ -3344,3 +3344,48 @@ extended `ci-client` stage was not observed locally. No full headless suite or
TSan rerun (headless sources unchanged; client state is main-thread-only). No
physical DPI, real GPU, Wayland, accessibility or human visual acceptance is
claimed. No network traffic, database, deployment or persistent format changed.
## M9.5 organism and debug views — 2026-10-01
Implemented ADR-0081 and ORGANISM_RENDERING.md: biology-derived
`OrganismPresentation` (no controller/owner/level fields), `OrganismLayer`
ordering/freshness, budgeted organism projection with explicit truncation, and an
opt-in rectangle-only hover inspector. ImGui was evaluated as optional and not
adopted. The app adds a static 48-organism fixture built from real genomes.
Executed:
- Windows MSVC 19.44 Release via `tools/windows-check.ps1 -Preset client -Action
check` (child `powershell.exe`): 5/5 labeled tests including `client-organisms`.
App runs `--frames 300 --refresh-every 2 --inspect` and `--frames 120 --layer
moisture` exited 0; `--frames 0` exited 2 (usage).
- Linux GCC 14 Release (`build/client-probe-linux`): 7/7 labeled tests, native
Xvfb/X11 lifecycle suite, X11 app with `--inspect --refresh-every 3`.
- Clang 19 Debug ASan/UBSan (`build/client-asan`): 5/5 labeled tests, X11
lifecycle, X11 app (`--inspect --layer moisture --refresh-every 2`, 300 frames)
and hidden dummy-driver app (`--inspect`, 200 frames); leak detection on, no
suppressions.
- Organism tests: phenotype equals `derive_phenotype` (20 um cube, hand-checked
bounds 390..410 at 1000 units/mm); a structured binding pins the cell's seven
fields; membrane thickness cap, motility ring and ingestion mark only with the
capabilities; conversion/growth/damage change body colour; visibility floor and
halo; byte-identical rectangles and inspector panels for player- and
NPC-controlled hosts with identical biology (ids 5 vs 900), translation-only
differences when moved; death (remnant colour, no ring/mark, same size) and
removal (absence, then empty presentation); 1024 visible organisms collapsing to
bodies within the 1755 app budget, explicit truncation at budget 500 (498 drawn
plus marker), invalid budget; a worst-case frame (environment bound + organisms
+ inspector + UI) within `Frame` limits; regression/foreign/watermark ordering
and stale dimming; 15 invalid presentation shapes and over-capacity; topmost picking on
floored bounds; gauge values and widths.
- Visual sanity check (offline rasterization of the app fixture at habitat zoom
and 2000 units/mm with the inspector): 3-unit floored organisms were hard to see
against habitats, so the floor became 5 units with a dark halo for collapsed
bodies. Not human, colour-vision or accessibility acceptance.
- clang-tidy 19 with warnings-as-errors on the five new/changed translation units:
passed after reserving a test vector. Repository-wide clang-format 19 passed.
Limits: Docker/Gitea execution of the extended `ci-client` stage was not observed
locally. No headless source changed; no full headless suite or TSan rerun. The
fixture population is static presentation data, not ecology. No network, database,
deployment, persistent format or simulation rule changed.