Files
aevolution/docs/adr/0081-organism-presentation.md
dingo 8ce609d344
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m32s
Foundation / postgres-tools (push) Successful in 26s
Foundation / server-image (push) Successful in 4m11s
Foundation / image (push) Successful in 4m36s
feat(client): add liquid presentation and clearer cellular HUD
2026-10-22 09:08:03 -04:00

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.