Files
aevolution/docs/engineering/CLIENT_VISUAL_REFRESH.md

6.4 KiB

Cellular liquid presentation refresh

Scope: native client presentation, 2026-10-22, requested by the maintainer using the screenshots, two recordings and visual references in Aevolution-Client-SS. This is a procedural first pass using the existing SDL3/ImGui renderer, not the photorealistic lighting of the reference images. No asset or runtime dependency is added. Headless libraries, biological rules, persistence and wire formats are unchanged.

Visual language

  • Blue-green liquid illumination replaces the black eyepiece interior. A fixed caustic mesh gives optical texture; it carries no environmental measurement. Current ribbons and travelling highlights follow the replicated flow field. A maximum 30 by 30 sample grid bounds cost even in a tall viewport.
  • Nutrients keep their established colors and gain distinct silhouettes: gold lobes for energy, umber facets for carbon, blue vesicles for nitrogen, rose rosettes for phosphorus, pale angular fragments for other matter. These are readable symbols, not asserted chemical structures. At very small sizes they simplify to solid marks. The legend uses the same shapes.
  • Pools have a thin circular membrane on their contact disc, containing those same nutrient symbols. A zero channel emits no shapes. Entire deposits remain owned and removed by the server; the client does not consume or split them. The decorative membrane neither blocks a cell nor changes collision geometry.
  • All living cells share cyan membranes, translucent cytoplasm, amber metabolic organelles and a violet centre. Wall thickness, motility, conversion and green producer organelles retain their existing phenotype mappings. The viewer's own cell has only its existing focus ring, not a different biological palette. Dead cells keep their broken outline; stale scenes freeze cosmetic motion and dim observed objects.

Controls and navigation

Buttons share a rounded, bordered treatment with distinct hover, pressed and disabled states. The action dock uses mint for feeding, blue for engulfing and violet for budding. Labels and authoritative enable/disable logic remain intact; color alone does not communicate affordability or success. Existing bindings remain authoritative; decorative shortcut numbers are not invented.

Field notes, Vitals and Nearby have explicit minus/plus buttons and a separate :: drag handle. Drag the handle to place a card; releasing anchors its position. Double-click the handle to restore the responsive default. Collapsing Vitals retains energy. Placement and collapse state last for the client session and are not saved to disk. Anchors use normalized viewport coordinates and are clamped inside the window when it is resized or the UI scale changes.

Expanded card sizes depend on viewport/scale, not the current text. Overflow scrolls inside a body with a reserved vertical scrollbar gutter; headings stay fixed and long text wraps at the body width. Minimize/restore intentionally changes a card's height. The action dock likewise keeps its buttons fixed above a scrollable details area. Changing nutrient values, growth warnings, pending results, region-edge notices and stale observations cannot resize or re-anchor these panels. The responsive compact layout keeps the dock and map within the viewport.

Resource-table rows also have stable single-line geometry: names and formatted quantities never inherit prose wrapping. The amount column reserves the widest supported energy/mass readout at the current font/scale, including the full u64 range, independently of live values. A growth-limiting nutrient shows * in its existing dot slot, with the same bar outline; the marker never lengthens an amount. This prevents transitions such as 714 fg to 1.54 pg from shifting later rows.

Nearby is a camera-centred observation map with a fixed six-millimetre radius. It reads the received food and organism views only, including observations outside the viewport. Empty space means unknown, not confirmed empty. Rings denote pools, dots nutrients and triangles cells; the controlled cell has a ring. The compass labels local +Y/-Y and +X/-X, consistent with the camera. Planetary north and a global explored-world map have not been defined by this gate. Disconnected data is explicitly stale. The map is read-only and cannot issue movement or reveal unobserved resources.

Temperature contract gap and proposed follow-up

Inspection found an architectural dependency: session v13 has reserves, motion, currents and observed food, but no body or ambient temperature observations. ADR-0178 and phase 3 of the region/movement plan explicitly leave the thermal field and per-cell thermal state pending. A client-only gradient or body temperature would fabricate game state. Implementation of that affected feature stops here.

Vitals reserves a Body -- / Water -- readout with an explanation on hover. No heat colors, danger thresholds or warmer/colder arrows are emitted.

Proposed resolution, not an accepted protocol or biological rule:

  1. Complete phase 3's authoritative body/ambient model and its versioned persistence/replay contract.
  2. Add bounded, perception-filtered body and local ambient temperatures with units, freshness and availability to a new negotiated session version.
  3. Define the spatial sampling distance and visible-neighbour coverage for warmer/colder guidance. No client extrapolation into hidden regions.
  4. Render measured body/water values and a separate thermal overlay. A direction arrow requires sufficient current samples; equal, missing or stale samples suppress it. Comfort and harm use observed phenotype limits, not UI constants.

Validation

Field notes, Vitals and Nearby can be resized by dragging any edge or corner. Minimum dimensions keep controls readable, while larger content scrolls inside the chosen bounds. Sizes last for the client session, survive minimize/restore, and adapt to UI scale and viewport limits. Double-click the heading's drag handle to reset both size and position. Resizing captures input before world controls.

The native panel suite exercises multiple sizes, collapse/restore and input capture alongside existing mutation, affordability and action tests. See VALIDATION for executed builds, screenshots and environmental limits. The supplied reference art is design input, not a runtime asset or a claim of achieved photorealism.