Files
aevolution/docs/engineering/CLIENT_VISUAL_REFRESH.md
T
dingo d057374148
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 5s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m29s
Foundation / postgres-tools (push) Successful in 20s
Foundation / server-image (push) Canceled after 1m43s
Foundation / image (push) Canceled after 1m43s
fix(client): stabilize HUD and anchor draggable panels
2026-10-26 15:13:15 -04:00

96 lines
5.5 KiB
Markdown

# 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.
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](../adr/0178-durable-liquid-region.md) and phase 3 of the
[region/movement plan](../../Cellular_Region_Movement_Plan.md) 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
The native panel suite exercises multiple sizes, collapse/restore and input
capture alongside existing mutation, affordability and action tests. See
[VALIDATION](VALIDATION.md) for executed builds, screenshots and environmental
limits. The supplied reference art is design input, not a runtime asset or a
claim of achieved photorealism.