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

Sprint 34: Pulse — Client Tasks

Goal: Close Phase 2 — wire the economics simulation into the live game, expose price history and trade flows in the implant, and make the economy observable and tweakable at runtime.

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

New Tickets

#	Title	Blocked by
#785	Add system population and GDP to star map info panel	—
#824	Economics insert panel — price history charts and GDP display	#822 (server)
#825	Economics debug console commands — event triggers and param sliders	#823 (server)

Key Decisions

• decisions/economics.md — D-181 (7-signal vocabulary — signals 1-2 are Phase 2: price_current, price_trend), D-180 (event port — the commands #825 fires)
• decisions/architecture.md — D-169 (implant UI component library — compose from client/ui/implant/), D-170 (HUD visibility groups — economics panel lives in INSERT mode), D-020 (IPC — EconomySnapshot arrives in ObserverSnapshot)

Notes

#785 — System population and GDP to star map info panel

When a system is selected in the star map (client/ui/star_map.gd, client/ui/star_map.tscn), the popup built with ImplantPanel components shows: name, star type, hop distance, corridor, GTTR excerpt, bodies, adjacents. Add two new ImplantDataRow entries: POPULATION and GDP. Data is already in res://data/star_map_data.json (regenerated by tooling/generate-star-map-data.py from systems.db). Check whether population and GDP fields are present in the JSON; if not, update the generation script as part of this ticket. This is standalone — no server dependency. Good warmup ticket; complete it first.

#824 — Economics insert panel

New implant panel: Economics Monitor. Lives in INSERT mode (D-170), accessible via implant navigation alongside the star map.

Scene: client/ui/implant/economics_panel.tscn + client/ui/implant/economics_panel.gd

Compose strictly from the existing component library (client/ui/implant/):

• ImplantPanel — root container
• ImplantHeader — "ECONOMICS MONITOR" title + selected system subtitle
• ImplantSeparator — section dividers
• ImplantDataRow — key/value rows for price and GDP data
• ImplantTextBlock — top commodity summary text

Layout (three sections):

1. System selector — searchable/scrollable list of systems (can reuse star map system data). Selecting a system triggers an EconStateQuery PlayerAction to the server.
2. Price table — top 6 commodities for selected system, each as an ImplantDataRow with price_current and a directional trend indicator (▲ / ▼ / —) derived from price_trend.
3. GDP strip — total economic activity for the system displayed as a single row. Update each time a new EconomySnapshot arrives.

Data flow: snapshot_handler.gd receives ObserverSnapshot v21. When economy_snapshot is present, forward to economics_panel.gd via a signal or direct call. The panel caches the last 20 ticks of price data per system for trend display (ring buffer in GDScript Dictionary).

Do NOT draw custom canvas sparklines unless time allows — ImplantDataRow with a trend arrow is the MVP. The price chart can be a follow-on.

Register the panel in client/scripts/autoloads/hud_groups.gd under path implant/economics. Add a keyboard shortcut (e.g. E in implant mode) and an entry in the implant navigation menu.

Blocked by #822 (server must expose EconomySnapshot before the panel has real data). Build the panel with placeholder data first; wire live data once #822 ships.

#825 — Economics debug console commands

The debug console exists at client/ui/debug_console.gd + client/ui/debug_console.tscn. The console already dispatches DebugCommandKind variants via PlayerAction::DebugCommand through the IPC bridge.

Add three new command parsers in _parse_command() / _dispatch_command():

econ inject <system_id> [commodity_id] <shock|boost> <magnitude> [ticks]
  → InjectEconEvent { system_id, commodity_id, effect, magnitude, duration_ticks }

econ param <alpha|beta|friction> <value> [system_a] [system_b]
  → SetEconParam { param, value }

econ inspect <system_id>
  → GetEconState { system_id }

econ inspect returns all 7 D-181 signals for the system; display in console output log as a multi-line block. econ inject and econ param print a confirmation + the server's DebugResponsePayload.text.

Update _print_help() to include the econ command family. Blocked by #823 (server must handle the variants before the client can send them meaningfully, though client-side parsing can be built in parallel).

Dependency Chain

#785 (star map GDP) — standalone, start here

#822 (server IPC, Sprint 34/server) → #824 (economics insert panel)
#823 (server debug handler, Sprint 34/server) → #825 (debug console commands)

#824 and #825 are parallel after their respective server blockers clear.

PR Workflow

tea pr create --repo jpmschweitzer/settled-reach --login schweitz \
  --title "feat(ui): economics insert panel and debug console econ commands" \
  --description "Sprint 34 client work" \
  --base main --head sprint-34/client