tgame/docs/12-onboarding.md

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) — 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.