galaxy-game/ui/docs/game-state.md

Per-game state store

This document describes the per-game state owned by the in-game shell layout. Phase 11 introduces the store and uses it for two consumers (the header turn counter and the map view); later phases plug inspector tabs, the order composer, and the calculator on top of the same instance.

Lifecycle

routes/games/[id]/+layout.svelte instantiates one GameStateStore per game (the layout remounts when the user navigates to a different game id, so each game gets a fresh store). The layout exposes the instance through Svelte context under GAME_STATE_CONTEXT_KEY; descendants read it via getContext(GAME_STATE_CONTEXT_KEY).

The layout's onMount builds the GalaxyClient, loads Cache through loadStore(), then calls gameState.init({ client, cache, gameId }). init:

1. installs a visibilitychange listener on document so the report is refreshed when the tab regains focus;
2. calls setGame(gameId), which:
   • reads the per-game wrap-mode preference from Cache (game-prefs / <gameId>/wrap-mode, default torus);
   • calls lobby.my.games.list and finds the game record (the Phase 11 wire schema extension on GameSummary adds current_turn); if the user is not a member, the store flips to error;
   • calls user.games.report for the discovered turn and decodes the FlatBuffers response into a TS-friendly GameReport shape.

The store exposes:

field	type	meaning
gameId	string	active game id
status	idle / loading / ready / error	current lifecycle state
report	GameReport | null	latest decoded report, null until first fetch
currentTurn	number	server's authoritative current turn (live snapshot)
viewedTurn	number	turn whose snapshot is in report; equals currentTurn in live mode
historyMode	boolean (derived)	true while status === "ready" and viewedTurn < currentTurn
pendingTurn	number | null	latest server turn the user has not yet opened
wrapMode	torus / no-wrap	per-game preference, persisted via Cache
error	string | null	localised error message when status === "error"

Phase boundaries

• Phase 11 surfaces only the planet subset of the report. Later phases extend GameReport and decodeReport as their slice of the wire lands (ships, fleets, sciences, routes, battles, mail).
• Phase 26 splits currentTurn from the turn whose snapshot is displayed (viewedTurn) and adds viewTurn(turn) / returnToCurrent() for history navigation. The derived historyMode rune flips automatically when viewedTurn < currentTurn; the layout passes it to Phase 12's sidebar / bottom-tabs wiring (which hides the order tab) and to OrderDraftStore.bindClient (which gates add / remove / move). See "History mode" below for the cache and refresh rules.
• Phase 24 replaces the tab-focus refresh with push-event-driven refreshes; the visibility listener stays as a fallback for background tabs that miss a push.
• Phase 29 wires the wrap-mode toggle UI on top of setWrapMode.

Why current_turn lives on GameSummary

The user-facing surface needs the current turn number to know which report to fetch. Two alternatives were rejected:

• a brand-new user.games.state message — adds a full wire-flow (fbs schema, transcoder, gateway routing, backend handler) for a one-field response;
• hard-coding turn=0 for all games — works for the dev sandbox (which never advances past turn zero) but renders the initial state for any real game past turn zero.

Extending GameSummary reuses the existing lobby pipeline; the backend already tracks current_turn in its runtime projection (backend/internal/server/handlers_user_lobby_helpers.go gameSummaryToWire reads it from g.RuntimeSnapshot.CurrentTurn).

The wire change touches Phase 8's already-shipped catalogue, but the current_turn field defaults to zero on the FB side, so existing tests and the dev sandbox flow continue to work unchanged.

State binding

map/state-binding.ts::reportToWorld(report) translates a GameReport into a renderer-ready World. Phase 11 emits one Point primitive per planet across all four kinds (local / other / uninhabited / unidentified). Each kind gets a distinct fill colour, fill alpha, and point radius so the four classes are visually-distinguishable at a glance; later phases will refine the colour palette as the visual language stabilises (Phase 35 polish).

The planet engine number is reused as the primitive id so a hit-test result can resolve back to a planet without an extra lookup table.

Refresh discipline

refresh() re-fetches the current-turn snapshot. It is called by the visibilitychange handler when document.visibilityState === "visible" and the store is already in ready state. The map view's mount effect skips a re-render when the new snapshot's turn matches the previously-mounted turn (and the wrap mode is unchanged), so a no-op refresh does not flicker the canvas.

In history mode refresh() is a no-op — forcing a reload would silently bump the user back onto the current turn while they are intentionally viewing a past one. Push events (Phase 24) still deliver new-turn notifications asynchronously while the user explores history, so the pending-turn toast continues to work.

setWrapMode(mode) writes to Cache and updates the rune; the map view's effect picks the change up and re-mounts the renderer with the new mode.

History mode

Phase 26 lets the user step backward through the report timeline without losing the live snapshot. The store keeps two turn runes:

• currentTurn — the server's authoritative latest. Only setGame and advanceToPending write to it.
• viewedTurn — the turn currently rendered. viewTurn(N) flips this rune and the underlying report to N without touching currentTurn. returnToCurrent() is a one-line wrapper that navigates back to live.

The derived historyMode rune (status === "ready" && viewedTurn < currentTurn) drives every history-aware consumer:

• the layout passes it to Sidebar / BottomTabs so the order tab vanishes (Phase 12 prop wiring);
• the layout passes a getHistoryMode getter to OrderDraftStore.bindClient so add / remove / move are no-ops while the user is looking at a past turn;
• RenderedReportSource returns the raw report (no order overlay) because the draft is composed against the current turn;
• the new HistoryBanner component renders the sticky "Viewing turn N · read-only" strip when the flag is true.

last-viewed-turn semantics keep their Phase 11 meaning: "the latest turn the user was caught up on". loadTurn only writes the cache row when called with isCurrent === true (i.e. when the load matches currentTurn). Historical excursions are therefore ephemeral: closing the tab and reopening the game resumes on the last caught-up turn, not on the last clicked one.

Past-turn reports are cached in the game-history namespace ({gameId}/turn/{N} → GameReport). The cache is written by loadTurn on every successful historical fetch and read first by viewTurn(N) before falling back to the network. Past turns are immutable, so the cache has no TTL and no eviction in Phase 26. The current-turn snapshot is deliberately not cached — it is mutable until the next engine tick.