Toolkit-independent launcher, selection, label and outcome-log models with bounded inputs and fixed error text; Dear ImGui overlay in the native adapter with toolkit-first event routing and capture; engineering panels for fixture vs dev region, legend, inspector, session outcomes, notices and dialog. Additive SessionClient::unreachable_attempts() bounds unreachable connects. Docs, CI targets and validation evidence updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
87 lines
4.8 KiB
Markdown
87 lines
4.8 KiB
Markdown
# 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) - 6 (host UI: capture bar, intention dot and a
|
|
four-sided selection outline) = 1777, so 1024 organisms always fit as bodies. No textures, caches or history are kept.
|
|
|
|
## Engineering inspector
|
|
|
|
M9.8c: a non-drag left click selects the topmost organism whose drawn (floored)
|
|
box contains the point, else the habitat cell (include/evo/client/selection.hpp).
|
|
The selection gets a white outline and the toolkit Inspector shows labelled rows
|
|
with units (include/evo/client/labels.hpp): state, voxel, offset, extent, masses,
|
|
surface, maintenance, movement, ingestion, conversion, growth, damage and thermal
|
|
shortfall. The organism id is never shown. A selection whose organism disappears
|
|
from the latest view is cleared; while no view exists it is kept. Habitat cells
|
|
list every field as a value, present zero, MISSING (requested, no value) or not
|
|
requested, and moisture as undefined when there is no capacity. The previous
|
|
rectangle gauge inspector (`--inspect`) remains a tested library component but is
|
|
no longer wired into the app. 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.
|