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:
@@ -1,11 +1,13 @@
|
||||
# Native engineering client (M9.2–M9.4)
|
||||
# Native engineering client (M9.2–M9.5)
|
||||
|
||||
This opens a resizable native window showing camera-controlled environment habitats
|
||||
from a local in-memory fixture authority (M9.4). It does not run an ecosystem,
|
||||
and biology-derived organisms (M9.5) from a local in-memory fixture authority.
|
||||
It does not run an ecosystem,
|
||||
connect to a server or implement cellular gameplay.
|
||||
Contract: [client architecture](../architecture/CLIENT_ARCHITECTURE.md), ADR-0078.
|
||||
Camera/input: [contracts and limits](CAMERA_INPUT.md), ADR-0079.
|
||||
Environment: [presentation and encodings](ENVIRONMENT_RENDERING.md), ADR-0080.
|
||||
Organisms/inspector: [encodings and budget](ORGANISM_RENDERING.md), ADR-0081.
|
||||
|
||||
## Build and run
|
||||
|
||||
@@ -29,6 +31,7 @@ one explicit backend, without fallback. `--frames N` exits after N bounded steps
|
||||
window and pauses drawing. These options permit unattended smoke checks.
|
||||
`--layer NAME` selects the displayed field or `moisture`; `--refresh-every N`
|
||||
(1..1000 fixture authority ticks) delays view refresh so the stale state is visible.
|
||||
`--inspect` shows biology gauges for the organism under the pointer.
|
||||
Usage errors exit 2, lifecycle/fixture failures exit 1, orderly exit returns 0.
|
||||
|
||||
Engineering controls: arrow keys pan, mouse wheel zooms around the pointer, WASD
|
||||
@@ -37,8 +40,9 @@ toggles UI capture: the top-left bar turns orange and navigation/movement input
|
||||
is suppressed. Leaving capture/focus loss requires fresh presses. This is a
|
||||
focus exercise, not the final player UI. The host's input tick is a local fixture
|
||||
counter and is never interpreted as authoritative server time. The top-right
|
||||
chip shows environment freshness (green current, amber stale, red none); the
|
||||
bottom-left legend shows the value ramp.
|
||||
chips show environment then organism freshness (green current, amber stale, red
|
||||
none; magenta marker: organisms truncated); the bottom-left legend shows the ramp.
|
||||
The organism cluster is near (410 mm, 480 mm); zoom in with the wheel to see it.
|
||||
|
||||
For native X11 regression on a CI host:
|
||||
|
||||
@@ -48,7 +52,9 @@ xvfb-run -a env SDL_VIDEO_DRIVER=x11 ./build/client/evo-client-lifecycle-tests
|
||||
|
||||
CTest uses the dummy driver. `client-environment` is an SDL-free suite for
|
||||
presentation validation, ordering/freshness, encodings, seams and bounds; it
|
||||
prints an `environment_profile` line (rectangles, bytes, microseconds per build). The lifecycle suite runs 32 open/destroy rounds,
|
||||
prints an `environment_profile` line (rectangles, bytes, microseconds per build).
|
||||
`client-organisms` covers phenotype derivation, controller parity, death/removal,
|
||||
dense scenes and truncation, ordering, picking and the inspector. The lifecycle suite runs 32 open/destroy rounds,
|
||||
resize/scale queries, non-unit drawable-scale pixel checks, minimize/restore,
|
||||
show/hide, focus/foreign events, reset/loss and close. Separate process checks
|
||||
exercise initialization failure. Tests stay active under NDEBUG. Synthetic
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
# 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) - 25 (inspector) - 3 (host UI) = 1755, so 1024
|
||||
organisms always fit as bodies. No textures, caches or history are kept.
|
||||
|
||||
## Engineering inspector
|
||||
|
||||
`--inspect` enables hover inspection: the topmost organism whose drawn (floored)
|
||||
box contains the pointer gets a white highlight, and a bottom-right panel shows
|
||||
ten gauges in order: extent (log10 over 3 decades um), total mass (12 decades fg),
|
||||
membrane share, maintenance (12 decades pJ/tick), movement speed (5 decades),
|
||||
ingestion rate (6 decades), conversion, realized growth, damage, thermal shortfall
|
||||
(5 decades mK). The panel darkens to brown for remnants. Rectangles only: there is
|
||||
no text, ImGui or input capture; 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.
|
||||
@@ -3344,3 +3344,48 @@ extended `ci-client` stage was not observed locally. No full headless suite or
|
||||
TSan rerun (headless sources unchanged; client state is main-thread-only). No
|
||||
physical DPI, real GPU, Wayland, accessibility or human visual acceptance is
|
||||
claimed. No network traffic, database, deployment or persistent format changed.
|
||||
|
||||
## M9.5 organism and debug views — 2026-10-01
|
||||
|
||||
Implemented ADR-0081 and ORGANISM_RENDERING.md: biology-derived
|
||||
`OrganismPresentation` (no controller/owner/level fields), `OrganismLayer`
|
||||
ordering/freshness, budgeted organism projection with explicit truncation, and an
|
||||
opt-in rectangle-only hover inspector. ImGui was evaluated as optional and not
|
||||
adopted. The app adds a static 48-organism fixture built from real genomes.
|
||||
|
||||
Executed:
|
||||
|
||||
- Windows MSVC 19.44 Release via `tools/windows-check.ps1 -Preset client -Action
|
||||
check` (child `powershell.exe`): 5/5 labeled tests including `client-organisms`.
|
||||
App runs `--frames 300 --refresh-every 2 --inspect` and `--frames 120 --layer
|
||||
moisture` exited 0; `--frames 0` exited 2 (usage).
|
||||
- Linux GCC 14 Release (`build/client-probe-linux`): 7/7 labeled tests, native
|
||||
Xvfb/X11 lifecycle suite, X11 app with `--inspect --refresh-every 3`.
|
||||
- Clang 19 Debug ASan/UBSan (`build/client-asan`): 5/5 labeled tests, X11
|
||||
lifecycle, X11 app (`--inspect --layer moisture --refresh-every 2`, 300 frames)
|
||||
and hidden dummy-driver app (`--inspect`, 200 frames); leak detection on, no
|
||||
suppressions.
|
||||
- Organism tests: phenotype equals `derive_phenotype` (20 um cube, hand-checked
|
||||
bounds 390..410 at 1000 units/mm); a structured binding pins the cell's seven
|
||||
fields; membrane thickness cap, motility ring and ingestion mark only with the
|
||||
capabilities; conversion/growth/damage change body colour; visibility floor and
|
||||
halo; byte-identical rectangles and inspector panels for player- and
|
||||
NPC-controlled hosts with identical biology (ids 5 vs 900), translation-only
|
||||
differences when moved; death (remnant colour, no ring/mark, same size) and
|
||||
removal (absence, then empty presentation); 1024 visible organisms collapsing to
|
||||
bodies within the 1755 app budget, explicit truncation at budget 500 (498 drawn
|
||||
plus marker), invalid budget; a worst-case frame (environment bound + organisms
|
||||
+ inspector + UI) within `Frame` limits; regression/foreign/watermark ordering
|
||||
and stale dimming; 15 invalid presentation shapes and over-capacity; topmost picking on
|
||||
floored bounds; gauge values and widths.
|
||||
- Visual sanity check (offline rasterization of the app fixture at habitat zoom
|
||||
and 2000 units/mm with the inspector): 3-unit floored organisms were hard to see
|
||||
against habitats, so the floor became 5 units with a dark halo for collapsed
|
||||
bodies. Not human, colour-vision or accessibility acceptance.
|
||||
- clang-tidy 19 with warnings-as-errors on the five new/changed translation units:
|
||||
passed after reserving a test vector. Repository-wide clang-format 19 passed.
|
||||
|
||||
Limits: Docker/Gitea execution of the extended `ci-client` stage was not observed
|
||||
locally. No headless source changed; no full headless suite or TSan rerun. The
|
||||
fixture population is static presentation data, not ecology. No network, database,
|
||||
deployment, persistent format or simulation rule changed.
|
||||
|
||||
Reference in New Issue
Block a user