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