# Onboarding (First 10 Minutes)

A 5-minute walkthrough that exposes every system in the order it actually flows, ending with the player released into the live game with anticipation cooking. Built around two design principles: **skip the wait** (pre-completed first expedition so the player doesn't hit a 30-min timer in beat 1) and **forced critical success** (a designed wow-moment on the player's first craft so the dopamine hook is set).

## The five beats

### Beat 0 — Drop-in (~30s)

- Player loads into the Guild Hall first-person view
- Short framing line: *"Welcome, Master. The guild is yours."*
- One starter minion already on the roster — authored character, name + portrait + decent traits. Working name: **Caewin the Steady**. He stays a real minion after the tutorial.
- Two notification badges glowing in the scene: the **front door** (returning expedition) and the **patron board** (waiting bounty)
- Bottom tab bar visible but no popups yet — let the badges pull

### Beat 1 — The returning expedition (~1 min)

Tap the front door → expedition return screen.

- Caewin returns with a hand-tuned starter haul: iron ore, hardwood, oil, glass, leather, flint
- Brief procedural event log: *"Caewin scouted the lower hills and brought back what he could carry."*
- Drop is exactly enough for a Crude Pickaxe + Trusty Lantern, plus a couple of low-value extras so the inventory looks real

Teaches: expeditions exist, return with loot, minions have identity.

### Beat 2 — The patron board (~1 min)

Tap the patron board → first patron unlocks.

- **The village foreman** — friendly, unintimidating, becomes a recurring low-tier patron later
- Ask: *"Bring me a Trusty Lantern, Fine quality or better. Pay: 50 gold, reputation, and a scroll for the Foreman's Tally."*

Frames the *why* of the next craft — the player has a goal, not "click around and see."

Teaches: patrons exist, bounties are specific, rewards include recipe unlocks.

### Beat 3 — The first crafts (~2 min)

Soft-guide to the workshops. Two crafts in sequence:

**Crude Pickaxe** — quick, two ingredients, zero ceremony. Teaches drag-to-station, hit craft, get item. Common quality, lands in the vault.

**Trusty Lantern** — four ingredients (iron, glass, oil, leather). The player encounters their **first Master's Touch meter** ([16-engagement-layers.md](16-engagement-layers.md)) — two slow, wide-green meters that are essentially impossible to miss at this difficulty. Both lock in green. **Forced critical success.** Shader sweep, particles, "Masterwork" ribbon, sound flourish, card lifts and rotates. The +resource bonus from the crit drops a **Foreman's Tally** — a gather-yield-boosting tool.

**Critical:** never tell the player it's a tutorial crit. The result panel shows plausible math: *"Caewin's steady hand + Lucky trait + perfect timing on both meters."* The player feels they nailed it. The hook is set — every craft from now on has a chance at this feeling, and the meter mechanic is taught.

(The earlier Crude Pickaxe craft introduces the Master's Touch meter on its slowest, easiest setting — so the mechanic is taught with no stakes before it matters.)

Teaches: crafting interface, quality bands, the critical-success moment, equipment items.

### Beat 4 — Equip and send (~1 min)

Soft-prompt: open the roster, tap Caewin, drag lantern + Tally into equipment slots.

- Caewin's portrait visibly updates (lantern at the belt, Tally tucked in pack) — paper-doll showcase
- Soft-prompt: open the World Map
- Two zones unlocked in starting region — player picks one
- Expedition sets off, tutorial timer ~2–5 minutes (short by design — second payoff if they keep playing, satisfying completion if they put the phone down)

Teaches: equipment changes portrait visibly, world map navigation, expedition planning, second-loop priming.

### Beat 5 — Release (~30s)

Brief outro: *"The guild is yours, Master. There's always something to do."*

- Tutorial overlay closes
- All tabs unlocked
- Patron screen shows patron 1 completed (green check, rewards paid)
- Patron 2 populates with a slightly meatier ask
- Player is dropped into the live game with sense of completion + sandbox + expedition cooking

## Design rules

- **Soft, not modal.** No forced arrows. Badges glow in priority order. Contextual one-liners surface on first-open of each screen. Player can tap around freely — tutorial just biases toward an order. Crafting the pickaxe before checking the patron board is fine.
- **Authored, not procgen.** Caewin, the foreman, the starter haul, the recipes — all hand-tuned. Procgen kicks in for the *next* of everything.
- **Forced crit hidden as a real roll.** Result panel must show plausible math. Player attributes the win to themselves.
- **Skip-friendly.** Returning players / repeat installs can skip after Beat 1.
- **Save-resume at every beat.** Closing app mid-tutorial picks up exactly where left.
- **No second tutorial.** After this 5 minutes, contextual hints only. New systems unlock with one-line tooltips on first encounter, never multi-step popups. Treat the player as an adult after the door closes.

## State after the tutorial

- 1 starter minion (Caewin) equipped with Masterwork Trusty Lantern + Foreman's Tally
- 2 expedition zones unlocked, 1 expedition in progress
- 1 workshop tier unlocked (Forge + Tinker's Bench, whatever crafts pickaxe + lantern)
- 2 recipes known (pickaxe, lantern), 1 recipe scroll in vault (Foreman's Tally upgrade path)
- 50 gold + initial reputation
- Patron 2 populated and waiting

A complete first-session arc: receive → craft → crit-magic → equip → send → exit with anticipation.

## Open questions

- Onboarding skip threshold — Beat 1 (after the returning expedition) feels right, but worth testing.
- Push notification opt-in — when do we ask? Right after the first expedition is sent (so they get notified when it returns), or wait until session 2?
- Tone of the framing voice — terse and atmospheric (matches the tone doc) vs. warmer and more guiding for onboarding only?
- Authored characters' continuity — does Caewin show up in the starting roster every game, or do we vary him?
- What if the player crafts the pickaxe twice (because it's quick) and skips the lantern? Forced crit might want to fire on whatever first-Fine-eligible craft they make, not specifically the lantern.