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:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user