4.5 KiB
[Reviewed]
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 was opt-in (--inspect); M9.8c replaces it in
the app with the labelled toolkit Inspector (ADR-0084) using the same picking rule.
The gauge API remains a tested library component.
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.
Presentation amendment, 2026-10-22
The native microscope now layers translucent cyan membranes and cytoplasm, amber metabolic organelles and a violet centre. Existing phenotype mappings for extent, wall thickness, flagella, conversion and producer chloroplasts remain in force. Identical biology receives the same palette; the controlled cell differs only by its existing focus ring. Dead outlines remain broken and stale opacity is applied to organelles as well as the membrane. No new biological parameter is introduced. See the visual refresh.