Starship Survivors Wiki

PrologueScreen

3 min read

PURPOSE

Guided first-time experience flow that renders the current prologue beat with a title, description, progress indicator, and CTA button. Currently a click-through placeholder that advances beats via progress counters; tutorial run integration is deferred to a follow-up pass. Beat 4 is intended to surface mission and pull flows once wired.

OWNS

  • The PrologueScreen React component (named export).
  • Local visual structure: title block, progress dots, step counter, beat name heading, description paragraph, and CTA button — all inline-styled.
  • The handleAdvance callback that grants the current beat’s reward, advances the beat, and routes to the hub on completion.
  • Redirect-to-hub logic when the prologue is already complete or no current beat is available.

READS FROM

  • useOnboardingStore — selects prologueComplete, currentBeatIndex, completeBeat, and getCurrentBeat.
  • PROLOGUE_BEATS from @starship-survivors/data/prologue-config — used for total count and rendering the progress dots.
  • beat.reward (gems, tickets), beat.id, beat.name, beat.description, and beat.ctaText from the current beat returned by getCurrentBeat().
  • useNavigate from react-router-dom for hub redirects.

PUSHES TO

  • useWalletStore.getState().earnGems(...) and earnPullTickets(...) when the current beat’s reward has gems or tickets.
  • useRewardQueueStore.getState().enqueue(...) with reward items built via makeRewardItem using REWARD_PRIORITY.gems and REWARD_PRIORITY.tickets, source label 'Prologue', and icons 💎 / 🎫.
  • completeBeat(beat.id) on the onboarding store to advance the prologue.
  • navigate('/') to return to the hub when the prologue is already complete, no beat is current, or the final beat has just been completed.

DOES NOT

  • Does not launch a tutorial run or any gameplay session — the placeholder only counts beats forward.
  • Does not show mission selection or pull flows on beat 4 (deferred).
  • Does not read or write any persistence layer directly; all state changes go through the onboarding, wallet, and reward queue stores.
  • Does not gate advancement on any condition — every CTA press completes the current beat unconditionally.
  • Does not render any layout chrome beyond what OnboardingShell provides.

Signals

  • Renders null after triggering a redirect when prologueComplete is true or getCurrentBeat() returns falsy.
  • progress is computed as currentBeatIndex + 1; total is PROLOGUE_BEATS.length.
  • Progress dot color: green (#34d399) for completed beats, orange (#f97316) for the current beat, faint white for upcoming.
  • Final-beat detection uses currentBeatIndex >= PROLOGUE_BEATS.length - 1 after completeBeat is called.

Entry points

  • Mounted by the metagame router as the prologue screen.
  • The single user interaction is the CTA button, which invokes handleAdvance.

Pattern notes

  • All store reads use individual Zustand selectors; mutations use getState() inside the event handler rather than subscribing.
  • Reward grant and enqueue happens before completeBeat, so the reward queue is populated against the current beat state.
  • The component composes OnboardingShell for the outer frame and supplies all inner content as children with inline styles. Fonts are 'Cal Sans' throughout.
  • Both early-return paths call navigate('/') synchronously inside the render body, which schedules navigation as a side effect during render.

Graph View