settled-reach/docs/workshops/body-map-viewer/stig-round1.md

title, description, type, status, workshop, created, owner

title	description	type	status	workshop	created	owner
Body Map Viewer — Stig's Round 1 Position	Client map component structure, step-cross UX, overlay compositing, and the client cache store decision	workshop	active	body-map-viewer	2026-07-25	Stig

Stig — Round 1 Position

Answering the four questions in my slice. Grounded in the measured appendix (①–⑤) and the current client/ui/implant/apps/atlas/ cluster as it exists on disk today, not as remembered from the T-1143 doc.

1. The client map-drawing component

Kill _canvas.scale. There is no more zoom-scaled canvas. Today's model — _canvas.position/_canvas.scale on a Node2D, _apply_transform() setting _canvas.scale = Vector2(_view_zoom, _view_zoom), every nature-overlay draw_* call wrapped in _zs()/_zs_stroke()/_zs_ring_radius() compensation — is the entire error class named in the brief (§2 of prep-grounding). The premise "server determines content, client draws map-art" doesn't just permit retiring that model, it removes the only reason it existed: the scale node was there to let one held composite serve a continuous zoom range. Stepped zoom with a server-resolved canvas per step means the client never needs to render the same data at two different implied resolutions — each step gets its own texture, drawn near enough to 1:1 that "zoom" stops being a client-side transform of derived geometry at all.

Structure: two sibling layers under one step-canvas owner, replacing the single _canvas Node2D.

• Terrain/classification layer — RTT, texel-exact. One ImageTexture per held step canvas, built server-side-derived / client-colorized, drawn via draw_texture_rect at the tunable px ratio (1:1 ideal, up to 5×5 px/gridunit fallback per the resolution tunable). This is not a new pattern — it's _rebuild_texture_if_needed/_build_tile_texture in atlas_window_overlay.gd generalized from "per-tile mosaic composite" to "the one and only terrain path." The tile-mosaic code (_draw_tile_mosaic/_draw_one_tile/_tile_texture_cache) already proves the RTT-per-cell-block shape works and composites cleanly at orbital rest state — it's not being invented, it's being promoted to universal.
• Screen-space annotation layer — unscaled sibling, literal px. Everything currently living in atlas_window_geometry_nature.gd's _zs-wrapped draw_polyline/draw_circle/draw_arc calls (rivers, settlement glyphs, POI rings, mouth markers) moves to a sibling Node2D that is never scaled. Positions are world→screen transformed per-frame (cheap — it's a linear map, not a re-derivation); sizes are constants or class-driven constants, never divided by a zoom factor. This deletes _zs(), _zs_stroke(), _zs_ring_radius(), and the entire "did I remember to wrap this call site" failure mode — by construction, not by discipline.

What retires:

• _canvas.scale/_canvas.position transform model and _apply_transform() as currently shaped (a replacement "step-canvas anchor" concept survives, see step-cross below, but it's not a continuous scale).
• The _zs/_zs_stroke/_zs_ring_radius compensation family in atlas_window_geometry_nature.gd — wholesale, once the sibling layer lands.
• select_rung()'s coverage-ceiling walk (Tyre's call to make formally, but it's dead the moment the step index replaces it — my component doesn't need a rung selector, it needs a step index).
• The AtlasViewer/orbital-mosaic-vs-window split as two code paths — under the stepped model, global zoom is just step 0, not a structurally different viewer. (T-1157's dead-goldens problem is a direct consequence of this split existing today; the redesign should collapse it, not re-target goldens at the same fork.)

What survives as-is:

• atlas_window_tile_set.gd's LRU-by-key cache shape (see §4 — it's the right skeleton for the new client cache, wrong eviction policy alone).
• _filter_for_granularity_v2() — NEAREST vs LINEAR sampling filter choice per rung is still a real question at RTT scale-ratio draw time, independent of the transform model change.
• atlas_window_water_clip.gd, atlas_marker_overlay.gd, atlas_legend_panel.gd, atlas_overlay_bar.gd — these are compositing/UI chrome, not the transform mechanism; they consume whatever the new layer pair exposes and shouldn't need structural rewrites, only call-site updates.

T-1158 (viewer decomposition into input/orchestration/canonical-frame clusters) is subsumed, not scheduled separately — the canonical-frame state machine T-1158 wanted to extract is the exact thing that changes shape under stepped zoom (no more continuous zoom floor, no more _canonical_fit_zoom() fitting a float zoom — the "canonical frame" becomes "step 0"). Extracting the old cluster now would be extracting code about to be deleted. Recommend cancelling T-1158 with the supersession note and letting the new component's structure be decided fresh as part of this implementation (naturally three pieces again — input/pan, step-cross orchestration, and the two draw layers — but that's a consequence of good decomposition, not a retained ticket).

2. Step-cross experience

Hold-fetch-swap, not blend-fetch-swap, as the baseline — a morph is a separate, optional cosmetic layer on top.

Sequence on a scroll-step:

1. Player scrolls one notch. Compute the new step's data-canvas bounds (cursor-anchored — the center the new canvas should be requested around is the world point under the cursor, matching the surviving entry-seam behavior).
2. If that canvas is already in the client cache (§4), swap immediately — this is the common case for backtracking (zoom out then back in) and for revisiting a spot, and it's why the cache matters for feel, not just bandwidth.
3. If not cached, hold the current step's texture displayed, unscaled, while the fetch is in flight — this is the "between-step magnification" red flag's actual mechanism: showing the coarser canvas magnified to fill the new step's viewport for the fetch duration. Measurement ① confirms this window is short: District-class server derive is sub-millisecond served, and even an uncached 330K-gridunit step canvas is ~75 ms derive + ~5 ms PNG-encode server-side (measurement ④'s "derivation cost for context" row) — the hold interval is double-digit milliseconds, not a visible stall.
4. On arrival: decode, build/update the ImageTexture (measurement ⑤: worst case 8.3M px update is ~4.3–4.6 ms median, comfortably under one frame), swap the terrain layer, re-run the annotation layer's world→screen transform against the new step's bounds.

ImageTexture upload cost is a non-gating input, confirmed by ⑤. Every canvas size the workshop cites uploads in single-digit ms with no observed frame-budget break, including the frame-delta-spike case. This means the step-count/canvas-size decision (Dudley's/Tyre's call) can be made on derivation cost and wire size alone — upload is not a constraint that trades off against them. One concrete implementation note from ⑤: prefer texture.update() reuse over fresh create_from_image() per step, not for raw speed (reuse is marginally slower in the raw numbers — 4.3–4.6 ms vs 3.2 ms median at 8.3M px) but because it avoids per-step Texture object churn on the RenderingServer side that the microbenchmark doesn't capture. And: use L8 wherever a plane is genuinely single-channel — 4–9× cheaper than RGBA8 at every size in ⑤, a free win if any wire field (elevation, a grayscale classification pass) can ship single-channel before the client colorizes it.

The morph/tween is real but strictly cosmetic, and I'd sequence it after the hold-fetch-swap baseline ships, not with it. A cross-fade or scale-tween between the held step-N texture and the arriving step-(N+1) texture, purely in screen space, never touching derived data — this is squarely inside "GPU is presentation only." It softens the perceptual jump D-166's amendment has to own honestly (red flag 1) without pretending to be continuous zoom. I'd implement it as an optional CanvasItem alpha/scale tween gated behind a toggle, not a hard requirement — if it turns out ugly or distracting at real step factors, dropping it costs nothing structurally because it never participates in the data path.

Client-side cache is what makes repeated step-crossing (the actual common case — players hunt around a region, not monotonically zoom in once) feel instant. Per premise 9: a canvas for a fixed seed never changes, so once fetched it is valid forever for that exact (body, step, center) key — the atlas_window_tile_set.gd LRU shape already assumes exactly this ("no freshness check, no TTL, no invalidation path — the only reason an entry leaves is capacity pressure"). The new cache needs the same discipline plus the sim-state carve-out premise 9 calls out (frozen/flooded needs a shorter TTL layered on top of the otherwise-permanent geometry entries) — see §4 for the store shape.

3. Overlay compositing under RTT — shader vs CPU (the c1 decision)

I'd ship CPU set_pixel coloring for the terrain layer first, with a concrete, named follow-up to shader-side compositing once the toggle set grows — not because shaders are wrong, but because the migration risk right now is elsewhere and CPU coloring is what's already proven in-tree.

Reasoning:

• Today's code already does this and it works. _build_tile_texture/ _rebuild_texture_if_needed build the Image cell-by-cell via set_pixel from typed field values (_cell_color/_base_cell_color/_temp_cell_color/ _moisture_cell_color/_veg_cell_color/_apply_glaciation — five toggle overlays already implemented this way). This is the temperature/moisture/ vegetation/glaciation toggle set the question asks about, already shipped on the CPU path. Moving the transform model (RTT-as-universal, no more scaled canvas) is already the workshop's biggest client-side change; I don't want to also change the coloring mechanism in the same pass without a measured reason to.
• The measured numbers don't force the shader answer. Nothing in ①–⑤ prices CPU set_pixel coloring cost at step-canvas scale (330K–8.3M cells) — that's a real gap, and I'd flag it as a follow-up measurement before committing either way at the deep end of the ladder. What ⑤ does show is that the upload step (which happens regardless of who colors the pixels) is cheap; the open question is purely "how long does building the Image take in GDScript at 330K+ cells," which is untested. Given that gap, defaulting to the known-working CPU path and measuring before the largest canvas sizes ship is the honest sequencing — not picking shaders on the strength of "should be faster" without a number.
• Where shaders clearly win, and where I'd schedule the follow-up: the moment T-1175's per-vertex river tapering/width-grammar work starts (source tapering, tributary-join width ramps), that work wants shader-side or at minimum Polygon2D-strip geometry regardless of what the terrain layer does — draw_polyline is single-width by construction and can't taper. That's a screen-space-annotation-layer concern (§1), not a terrain-raster concern, and it's already gated on "after the nature layer stands" per T-1175's own scheduling note. If shader-side terrain compositing is adopted later (multiple data textures — morphology/elev/temp/moisture/vegetation/ glaciation — sampled and colorized in a fragment shader), the toggle overlays and T-1175's tapering become the same mechanism for free, which is a genuine architectural win — I'm not against it, I'm against committing to it on zero cost data for the actual bottleneck (CPU set_pixel at 8.3M cells) when a known-good fallback exists.
• Recommendation for the ticket plan: ship CPU coloring behind the new RTT structure for the initial step-ladder cutover (lowest risk, matches proven code), file a measurement ticket for GDScript Image.set_pixel cost at 330K/2.07M/8.3M cells (the missing sixth measurement), and treat the shader migration as the natural landing spot for T-1175 rather than a precondition for the ladder itself.

4. The client cache store — in-memory vs disk-backed

Answering the three candidate shapes against the fact base (SQLite ships server-side only; client has gdUnit4 + messagepack, no SQLite addon today).

My answer: (iii) plain FileAccess cache dir + index, not (i) server-side SQLite and not (ii) godot-sqlite. In that order of preference, for these reasons:

Against (i) server-side SQLite cache DB. The "client-primary reads as local-machine-primary" argument is real — a warm local subprocess is fast — but it quietly relocates a client-side design decision onto the server's process boundary and turns every cache read into an IPC round-trip instead of an in-process Godot call. It also risks exactly the thing the asset-pipeline golden rule and D-227 both warn about: a second SQLite file living next to systems.db invites confusion about which one is canonical, even with a different filename, because the mental model "the server owns the DB" now has two meanings (canonical snapshot vs cache). D-227's discipline needs to be re-proven at a new file rather than reusing an already-well-understood boundary. Not fatal, but it's the shape with the most governance surface area for the least architectural gain — premise 9 explicitly frames this as a client-side cache question, and routing it through the server subprocess undercuts the "client-primary" framing it's supposed to answer.

Against (ii) godot-sqlite addon. A real client-side store, and if the cache needed relational queries (joins, filtered scans across many keyed records) I'd pick this without hesitation. It doesn't — the access pattern is point lookups by a composite key (body_id:step:center:granularity_v2, extending atlas_window_tile_set.gd's existing make_key() shape almost unchanged) plus a periodic TTL sweep over sim-state-tagged entries. That's a key-value store with expiry, not a relational workload. Pulling in a new compiled addon (build/platform surface, version-pin maintenance, another thing that can fail to load headless in CI) to do a job FileAccess + Time.get_unix_time_from_system() already does natively is the kind of dependency I'd only take if the simpler shape measurably couldn't do the job. It can.

For (iii) plain FileAccess cache dir + index — the shape:

• Directory layout: one file per cached step-canvas entry under user://atlas_cache/<body_id>/, named by a hash or the same key string atlas_window_tile_set.gd already builds (make_key() extended with the step index) — content is the already-decided wire encoding (PNG-per-field per measurement ④, the clear winner on size and speed), so the disk file IS the wire payload, no re-encoding for storage.
• Index: one small JSON or binary manifest (user://atlas_cache/index. <body_id>.dat or similar) mapping key → {written_at, last_read_at, kind: geometry|sim_state, size_bytes}. Loaded once per body-open, held in memory as a Dictionary — this is the same LRU-touch shape atlas_window_tile_set. gd already implements (erase+reinsert = move-to-MRU), just backed by files on disk instead of values in the dictionary, and the dictionary now stores metadata + a FileAccess path instead of the raw window Dictionary.
• Two-tier eviction, matching premise 9's split exactly:
  • Geometry entries (morphology/elev/moisture/vegetation/glaciation/ height, everything D-227's determinism guarantee covers): LRU-evict-only, no TTL, same as today's atlas_window_tile_set.gd — a canvas for a fixed seed never changes, so "stale" isn't a concept that applies. Global step (step 0) entries get a retention floor (never evicted by the LRU sweep, only by an explicit clear/uninstall path) — this is the concrete mechanism for "always keep the global level" from Jeroen's outline, sized by red flag 2's number (~1.6 MB/body at 5×5 sampling; even at all ~273 bodies resident that's ~440 MB on disk, which is a completely different budget conversation than 440 MB in process memory — disk is cheap, RAM/VRAM residency is the thing that needed the ceiling).
  • Sim-state-tagged fields (frozen/flooded, whatever the map-time-axis ruling lands on): explicit TTL sweep, a periodic (not per-frame — on body-open and on a coarse timer) pass over the index removing entries past their TTL regardless of LRU recency. This is the literal self-cleaning-records behavior Jeroen asked for ("on disk probably, but with self cleaning of cache records"), and it's the one place this store needs logic atlas_window_tile_set.gd doesn't have today.
• Never the source of truth, enforced structurally, not just by comment: if the cache directory is deleted, the client's only behavior change is re-fetching from the server — same guarantee D-227 gives server-side, now proven at the client tier too. Boot-time behavior: missing/corrupt index → treat as empty cache, don't crash, don't block first paint.
• Sizing from the wire table (④): at the PNG-per-field encoding (the clear winner — smallest and fastest at every size), a 330K-gridunit step canvas is ~638 KB; a full global-tier set across ~273 bodies at the 5×5 fallback resolution is the ~440 MB figure red flag 2 already computed. That number is disk-budget-safe on any target platform (modern discretionary disk cache budgets for a locally-installed game are routinely in the multi-GB range) in a way it is not RAM-safe — which is the strongest single argument for "disk-backed, not memory-only": premise 9's "always keep global" instruction is only affordable at all if it's a disk tier, not permanent process residency. An in-memory-only cache would have to either violate "always keep global" (evict it under memory pressure, defeating the snappy-navigation goal) or accept the ~440 MB RAM floor red flag 2 already calls infeasible. Disk removes that tension entirely.
• In-memory tier still exists, layered on top, not replaced. The atlas_window_tile_set.gd-style in-process Dictionary cache remains the hot path for "the step I'm looking at right now and its immediate neighbors" — a session-scoped, small (current DEFAULT_MAX_ENTRIES = 24 is a reasonable starting point, tunable) LRU exactly as it works today. The disk store is the tier below it: a miss in memory checks disk before going to the server. Three tiers total, cheapest-first: in-memory Dictionary → disk FileAccess store → server (which has its own tiers, Dudley's to answer). This layering is what makes "client-primary reads as local-machine-primary" actually true without needing the server-SQLite detour — the disk tier gets you nearly all of that latency win already, in-process, no IPC.

Net recommendation: (iii), layered under the existing in-memory LRU as a second tier, two eviction policies (retention-floor+LRU for geometry, TTL-swept for sim-state), sized directly from measurement ④'s table. No new Godot addon, no second SQLite file, no server round-trip for a client-local question.

Open items I'm carrying into round 2

• The missing sixth measurement: GDScript Image.set_pixel coloring cost at 330K/2.07M/8.3M cells — needed before the c1 shader-vs-CPU call can be made with the same rigor as everything else in this brief. I'd rather name this gap now than let CPU-coloring become an unexamined default at the largest canvas sizes.
• Step-count/canvas-size is Dudley's/Tyre's number to land, but it directly sizes my annotation-layer redraw frequency and cache key space — I'll adjust §1/§4 sizing once that lands in the lead interview.
• Phase-5 reuse question (Jeroen's #4): I'd scope the map-drawing component as Atlas-only for this pass. The RTT-terrain + screen-space-annotation split is a reasonable shape for a future in-world viewport too, but Phase-5 in-world rendering has different constraints ( per-frame redraw, character-relative camera, no step-cross discontinuity to design around) that I don't want to speculatively design against now — that would be exactly the kind of later-phase drag the cascade discipline warns against. Build it right for Atlas; revisit reuse when Phase 5 actually starts.