Files
aevolution/docs/engineering/ORGANISM_RENDERING.md
T
dingoandClaude Opus 5.5 8e319322f4 Implement M9.7 dev region sessions with durable no-effect intentions
Run a non-blocking TLS 1.3 session server inside evo-server's loop:
environment views come from the region's own field/terrain stores with an
explicitly empty organism presentation; admitted intentions ride the next
synthetic input (content unchanged) and return a durable no-effect outcome
from the host's final acknowledgement, or not_committed when dropped.
Sessions are bound to their connection, epochs close stale sessions, and
connections have bounded output, input rate and deadlines.

SessionClient and evo-client --connect consume one single-use grant per
Hello (refusals before admission keep it), reset to a fresh baseline on
every session, keep stale views visible and report in-flight intentions as
unknown after loss. evo-dev-session generates dev credentials, grant
bundles and runs a restart probe. The dev deployment gains a drill-time,
loopback-only listener with an optional Secret, enforced by the policy
check, and tools/ops/session-drill.sh. Protocol v1 gains IntentOutcome and
the capacity close reason before any deployment. ADR-0083 records the
maintainer-confirmed decisions; M8-dev/stage remains not passed and no
cluster change was made.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 20:12:18 -04:00

4.4 KiB

M9.5 organism rendering and engineering inspector

Decision: ADR-0081. 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.

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) - 5 (host UI) = 1753, 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.