New-Player Onboarding Flow
The first ~10-15 minutes of a new player’s experience is a tightly scripted funnel from a magic-link account claim, through a 4-beat prologue tunnel, into a progressively revealed hub. Hub UI is gated by reveal level; chapter completions unlock more of the metagame surface.
Flow overview
Welcome modal -> Prologue tunnel (beats 1-4) -> Hub lite -> Ch.1 done -> Hub mid -> Ch.2 done -> Hub full
- Welcome modal — fires once after a guest account is claimed via magic link. Prompts the pilot to set a callsign (1-24 chars). Skipping keeps the default name
Pilot. - Prologue tunnel — 4 beats, ~10-15 minutes total. Beats 1-3 happen inside a single continuous tutorial run; beat 4 is on the metagame surface (mission deploy + first pull + first hub view).
- First hub reveal — finishing all 4 beats sets
prologueComplete=true, jumpshubRevealtohub_lite, and stampsrookieBoostStartedAt. - Chapter unlocks — finishing Chapter 1 advances reveal to
hub_mid; finishing Chapter 2 advances tohub_full.
Welcome modal
Source: src/metagame/components/WelcomeModal.tsx.
- Rendered at the
Applevel whenplayerStore.showWelcomeis true (set after a successful magic-link claim). - Header:
ACCOUNT LINKEDwith the linked email shown beneath. - Calls
updateDisplayName(trimmed)on submit, thendismissWelcome(). - Skip button keeps the existing display name (falls back to
Pilot). - Visual style: white-panel medical UI (
<MedPanelModal>+<MedPanel variant="doors">) with pneumatic door-reveal animation, cyan accents, hairline borders.
Prologue beats
Source: src/starship-survivors/data/prologue-config.ts (PROLOGUE_BEATS).
Each beat has an id, a progress key it tracks (ProgressKey), a target value, a reward, and a CTA string shown to the player.
| # | ID | Name | Tracking key | Target | Reward | CTA |
|---|---|---|---|---|---|---|
| 0 | movement_combat | First Flight | total_kills | 5 | 10 gems | Destroy the enemies! |
| 1 | level_up | Getting Stronger | max_run_level | 2 | 15 gems | Choose an upgrade! |
| 2 | weapon_event | New Weapon | events_completed | 1 | 1 ticket + 20 gems | Complete the event! |
| 3 | mission_pull_hub | Welcome Home | pulls_made | 1 | 50 gems | Make your first pull! |
Total prologue reward: 95 gems + 1 ticket.
Beats 0-2 are all completed inside the same continuous tutorial run (kills, then a level-up, then an event). Beat 3 happens after the run lands the player on the hub for the first time: deploy a mission, pull from the gacha. The store’s completeBeat(beatId) advances currentBeatIndex; once the last beat is marked done it flips prologueComplete=true, sets hubReveal='hub_lite', and stamps rookieBoostStartedAt (if not already set).
Hub reveal levels
Source: prologue-config.ts (HubRevealLevel, HUB_REVEAL_RULES).
The hub UI is progressively unlocked across 4 reveal levels. Each level is a flag set controlling which top-level UI elements render.
| Level | Currency bar | Bottom nav | Shop tab | Collection tab | Missions btn | Systems btn |
|---|---|---|---|---|---|---|
locked | no | no | no | no | no | no |
hub_lite | no | no | no | no | no | no |
hub_mid | yes | yes | yes | yes | yes | no |
hub_full | yes | yes | yes | yes | yes | yes |
Transitions:
locked -> hub_lite— prologue complete (auto, incompleteBeatwhen last beat resolves).hub_lite -> hub_mid— Chapter 1 complete.hub_mid -> hub_full— Chapter 2 complete.
locked and hub_lite currently share the same visibility flag set; hub_lite is the post-prologue holding state before any chapter has been cleared. The hub stays visually minimal until hub_mid flips the currency bar, bottom nav, shop tab, collection tab, and missions button on at once. hub_full adds the systems button (the only difference between hub_mid and hub_full).
Onboarding shell
Source: src/metagame/components/OnboardingShell.tsx.
Stripped-down layout used only during prologue beats — no bottom nav, no currency bar, no hamburger. Dark background, centered content, single guided CTA button per beat. Used in place of the full hub shell until prologueComplete flips.
Persistence
Source: src/starship-survivors/stores/onboardingStore.ts (useOnboardingStore).
State shape:
prologueComplete: boolean— defaultstruefor existing players (pre-onboarding-system); new players hydrate tofalse.currentBeatIndex: number— 0-3 during prologue, 4 once all beats complete.completedBeats: Set<PrologueBeatId>— set of finished beat IDs.hubReveal: HubRevealLevel— current reveal level. Default for existing players:hub_full. Default for new players:locked.rookieBoostStartedAt: number— epoch ms when prologue completed; 0 if not yet started.
Methods:
completeBeat(beatId)— marks a beat done, advancescurrentBeatIndex, and on the last beat flipsprologueComplete=true, setshubReveal='hub_lite', and stampsrookieBoostStartedAtif unset.completePrologue()— force-completes prologue and jumps straight tohub_full(used for existing players or a skip path).setHubReveal(level)— manual override (used by chapter-completion handlers).getCurrentBeat()— returns thePrologueBeatdef forcurrentBeatIndex, ornullif prologue complete.loadFromBootstrap(data)— hydrates state from the bootstrap response on app start.reset()— fresh-player state (testing only).
The prologue screen reads getCurrentBeat() to drive its CTA. The hub shell (HubScreen / V32Shell) reads hubReveal and looks up the corresponding HUB_REVEAL_RULES entry to control which UI elements render.
Source files
src/starship-survivors/data/prologue-config.ts— beat definitions and hub reveal rules.src/starship-survivors/stores/onboardingStore.ts— Zustand store, persistence contract.src/metagame/components/OnboardingShell.tsx— prologue-tunnel layout.src/metagame/components/WelcomeModal.tsx— post-magic-link callsign prompt.