settled-reach/docs/sprints/sprint-35/client.md

Sprint 35: Atlas — Client Tasks

Goal: Launch Phase 3 — open the Atlas implant panel so a player can navigate from the Reach map down to any planetary body and see a heightmap with generated city markers, overlays, and a city data panel linking to the economics monitor.

Branch: sprint-35/client Agents: Stig (UI), Tyre (architecture)

New Tickets

#	Title	Blocked by
#834	Atlas implant panel — system picker, orbital diagram, body navigation	—
#835	Atlas heightmap viewer — pan/zoom, marker overlay, city data panel	#834
#836	Atlas overlay system — 9 MVP overlays with visibility tiers	#835

Key Decisions

• decisions/architecture.md — D-191 (Atlas Phase 3 scope — full UI spec: zoom hierarchy, navigation levels, city data panel, overlay system, MVP completion criteria), D-169 (implant UI component library — compose from client/ui/implant/), D-170 (HUD visibility groups — Atlas registers as implant/map/atlas, FULLSCREEN mode z=20)
• decisions/economics.md — D-181 (signal visibility ladder — maps to which overlays are always-on vs. toggleable vs. locked in #836)

Notes

#834 — Atlas implant panel: system picker + orbital diagram + body navigation

New implant app. Register with HudGroups as implant/map/atlas in FULLSCREEN mode (z=20). The atlas is an extension of implant/map, not a separate app — the existing star_map.gd registers at implant/map/starchart. The atlas adds the next zoom levels downward.

Three navigation levels:

1. System picker — reuse the system list from client/ui/implant/economics_panel.gd. Searchable scroll list. Selecting a system advances to level 2. client/ui/star_map.gd already has a system selection signal; check if it can be reused or if the atlas needs its own.
2. Orbital diagram — star at center, bodies arranged by orbit_index from systems.db. Click a body → level 3. Click a station → mini data panel (name, operator, currency_zone — no drill-down; stations have no heightmap). Back navigation returns to system picker.
3. Body entry point — tile/button that opens the heightmap viewer (#835). Can be a simple "VIEW ATLAS" button in this ticket; the actual viewer is built in #835.

Use implant component library throughout: ImplantPanel, ImplantHeader, ImplantSeparator, ImplantDataRow, ImplantTextBlock. Theme from client/ui/implant/default_implant.tres.

This ticket delivers navigation skeleton only — the heightmap viewer content comes from #835. Build with stub data (empty orbital diagram with system name and body count) so the panel can be tested independently. Data for the orbital diagram lives in res://data/star_map_data.json (the same source used by the star map). Check whether orbit_index and body type are already in the JSON; extend the generation script (tooling/generate-star-map-data.py) if not.

Add keyboard shortcut and implant nav entry (consistent with how economics_panel.gd registers its shortcut).

#835 — Atlas heightmap viewer: pan/zoom, marker overlay, city data panel

Body atlas level. Loaded when a body is selected in #834.

Heightmap display: Load the heightmap PNG as Texture2D in a SubViewportContainer with pan/zoom. The heightmap path comes from terrain_reference in bodies data (the star_map_data.json should include this after #839 runs on server; if the JSON was generated before #839, re-run make atlas-generate to pick up the column). Pan/zoom: mouse drag + scroll wheel, pinch gesture on touchscreen. Clamp to image bounds.

MarkerOverlay: A Node2D drawn via _draw() on top of the viewport. Renders from markers.json per body (path: same directory as the heightmap PNG):

• Cities: filled circles, radius scaled by population_tier
• Roads: polylines (solid, thin)
• Railroads: polylines (dashed)
• POIs: diamond shapes
• Named features (rivers, oceans, mountains): labels at centroid

markers.json will be initially empty for most bodies until server's #832 and #833 complete. The overlay must handle empty arrays gracefully — display the bare heightmap if cities is empty.

City data panel sidebar: Clicking a city opens a right-side panel (ImplantPanel components) showing:

• City name, population tier, primary function
• Currency zone, Commission presence flag
• Shadow economy zone (broad band from shadow_economy_intensity)
• Gate distance (hop count to nearest gate terminal)
• Economics panel link — button that calls HudGroups.open_app("implant/economics") and triggers an EconStateQuery pre-filtered to this body's system node. This is the cross-panel integration point from D-191 criterion 5.

Blocked by #834 (needs the navigation frame). Can start before #832/#833 complete — build against the empty markers.json state; the overlay will auto-populate once the server pipeline runs.

#836 — Atlas overlay system: 9 MVP overlays with visibility tiers

Overlay toggle bar at top-right of the regional view (inside the heightmap viewer scene from #835).

Always-on (5): terrain, infrastructure (roads + rail), named features, gate/spaceport markers, political zones (currency zone color bands)

Toggleable (4): population density heatmap, production zones, shadow economy zones (broad bands from shadow_economy_intensity), corporate presence Tier 1 (dots where Tier 1 corps operate)

Deferred (visible but locked): overlays requiring D-181 semi-private or private signals (signals 5–6: stockpile_weeks, production_vs_baseline). Show these as greyed toggle buttons with a tooltip explaining the unlock requirement ("Requires corporate contact" / "Requires insider access").

The deferred overlays are present in the UI per D-191 — they communicate to the player that deeper information exists and is gated. Do not omit them.

Implementation: each overlay is a separate Node2D child of the MarkerOverlay container, toggled visible/invisible. The toggle bar is an HBoxContainer of ImplantTabRow-style buttons. State persists per session (not saved to disk).

Maps to D-181 signal visibility ladder — always-on overlays use public signals (1–2), toggleable overlays use observable signals (3–4), locked overlays use semi-private/private signals (5–6).

Blocked by #835 (needs the heightmap viewer and marker overlay infrastructure).

Dependency Chain

#834 (atlas panel — system picker + orbital diagram + body nav) — start here, standalone
  → #835 (heightmap viewer — pan/zoom, marker overlay, city data panel)
     → #836 (overlay system — 9 MVP overlays)

#834 can begin immediately (no server dependency for skeleton). #835 builds on #834's navigation frame. #836 builds on #835's MarkerOverlay infrastructure.

The heightmap viewer (#835) can be built against empty markers.json and will auto-populate when the server atlas pipeline (#832, #833) completes — no hard sequencing dependency between server and client work, only a data-availability dependency at test time.

PR Workflow

tea pr create --repo jpmschweitzer/settled-reach --login schweitz \
  --title "feat(ui): Atlas implant panel — Phase 3 planetary viewer" \
  --description "Sprint 35 client work: atlas navigation panel, heightmap viewer, 9-overlay system" \
  --base main --head sprint-35/client