Skip to main content

Onboarding

Onboarding is a multi-step flow driven by the onboardingMachine (XState 5). It establishes the player's identity and generates their first creature.

Flow​

Steps​

1. Element Selection​

The player chooses their element affinity. This is an identity choice, not just a damage type:

  • Water - Adaptability, flow, healing
  • Earth - Stability, growth, endurance
  • Fire - Passion, transformation, energy
  • Air - Freedom, speed, exploration

Element choice determines:

  • Starter creature template pool
  • Stat growth patterns during nurture (Water -> +defense, Earth -> +health, Fire -> +power, Air -> +speed)
  • UI color theming for creature cards

2. Location Setup​

Player describes their home location/biome. Optional geolocation permission request.

The biome label is used for creature generation context and stored with the player profile. The system can infer biome from coordinates via a serverless Claude API call.

3. Creature Generation​

A creature is generated based on the selected element and environment. During the generation wait (Meshy 3D model takes 60-120s), the player sees a story interstitial with animated element lore pages rather than a blank loading screen.

Fallback: if generation fails at any stage, the system falls back to the seed pack (pre-generated creatures stored locally).

4. Creature Reveal​

The generated creature is shown in a 3D viewer (R3F Canvas with OrbitControls, or 2D sprite fallback). The player names their creature.

Resume Behavior​

The onboarding machine persists state to localStorage. If the player closes the app mid-onboarding, they resume at the exact step they left off.

State Machine​

  • Source: packages/app/src/machines/onboardingMachine.ts
  • Tests: Machine transition tests covering all steps and resume
  • View: packages/app/src/views/Onboard.tsx