# Onboarding > Design a game's first minute: invisible tutorials, difficulty curves, failure and retry loops, assist modes. Use when players quit early or don't get it. - Skill: `kyh/onboarding` (Agent Skill) - Install (CLI): `npx skillmds@latest add kyh/onboarding` - Raw SKILL.md: https://api.skillmd.com/api/skills/kyh/onboarding/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: kyh (https://skillmd.com/u/kyh) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/kyh/onboarding --- # Onboarding & difficulty A vibedgames player arrives cold from a link, mid-conversation, with seconds of patience. The first session is the whole funnel. Fun is learning: the game lives while there's a pattern left to master, and difficulty must rise with skill to stay in the flow channel. ## The first 30 seconds - **Time-to-first-input < 5s.** No splash chain, no settings, no mode select. - **Time-to-core-verb < 30s.** The player performs the signature verb (jump, shoot, plant) for real, with consequences, in the first half-minute. - **One input to start** — "press any key / tap" over a live game scene. Show the actual game behind the title (attract mode), not a static logo. - **First input produces a juicy result**: sound + motion + particles. The brain needs proof inputs matter before it will learn the pattern. - **Goal in one sentence or zero**: "Survive." "Reach the flag." - **Detect input device**: show touch hints to touch users, key hints to keyboard users — never a scheme the device can't use. If the core input is exotic (webcam, gamepad, mic), hint it explicitly and ship a plain mouse/keyboard fallback that's announced, not silent. Gimmick inputs (webcam/face/pose/hand, 3D presentation) are the product's identity — never drop them in a rebuild; standard inputs are fallbacks alongside. Hand tracking is undiscoverable on touch — hint it. - **Browser permission prompts are modals.** Camera/mic/motion requests are the most common cold-open modal in browser games — make them opt-in behind a button, or defer until after first play. Never fire `getUserMedia` on mount, and don't fetch the model before consent: the MediaPipe bundle pulled pre-consent from CDN is the biggest per-game load lever (6.1 MB → 0.15 MB and 2.5 MB → 0.14 MB on two games once deferred). ## Teaching without a tutorial (George Fan's PvZ rules) - **Doing > reading.** Never explain in text what a situation can force the player to discover once. Gate progress behind doing it once — done = taught. - **≤ 8 words on screen at a time.** If an instruction needs more, redesign the situation, not the sentence. - **Safe first exposure** (Half-Life 2 pattern): observe the hazard eat a barrel before dodging it yourself. - **Ramp: teach → repeat with one twist → combine.** Never two new ideas at once; roughly one new element per level. - **Objects self-describe**: appearance telegraphs function; piggyback on real-world knowledge (red = damage, coins = money, arrows = direction). - **Hints are adaptive, not up-front**: "Try planting further left!" only after the relevant failure. No modal popups that pause play. - **Bias the first decision**: make the correct opening move the cheap, shiny, obvious one (Fan made sunflowers cheap and sparkly). - **Never label anything "Tutorial".** - **Control hints live on the start screen only** — never persistent chrome during play (allowed exceptions in `game-ui`). ## Difficulty curve - **Start below the floor**: the first challenge is nearly unfailable — it teaches the verb and pays out a win. - **Sawtooth, not ramp**: spikes then recovery valleys; mastery registers in the valleys. (Shape details in `level-design`.) - **Re-test old skills while teaching new ones** — that combination is where the fun lives (Koster). - **Embed difficulty choice in play** (Chen's flOw): risk/reward verbs — dive deeper, take the shortcut, bank or gamble — beat an Easy/Normal/Hard menu. Optional hard routes + collectibles let novice and expert share one build. - **Hidden mercy after repeated failure** (Crash Bandicoot pattern): after 3–5 consecutive deaths at one spot, silently soften — extra checkpoint, slower hazard. Never announce it. ## Failure & retry "Death" means any failure event — a conceded point, a wiped wave, a failed puzzle attempt all follow the same rules. - **Death → retry: one input, < 2 seconds.** No confirmation dialogs, no unskippable death animations, no score screens between the player and the retry (Celeste/Super Meat Boy convention). - **Failure must be legible** (Juul): the player answers "what killed me?" instantly, and the counter-move is visible in the death itself. Fair failure motivates; opaque failure is a broken promise. - **Lose little while learning**: early deaths cost seconds. Punishment can scale after investment. - **Keep something across failure**: best-score deltas, unlock progress — a failed run becomes a deposit ("one more run"). - **Celebrate near-misses**: "Best: 412 — you got 398" reframes failure as approach. ## Assist mode (Celeste model) For any skill-gated game, ship granular, judgment-free assists: game speed 50–100%, extra HP/invulnerability, skip-section. Available from the start, reversible mid-game, named neutrally ("Assist Mode", never "Easy/Cheat Mode"), no "intended experience" framing, no score asterisks unless competitive integrity truly demands it (Thorson). Baseline accessibility is onboarding too: readable text, never color alone as a signal, remappable or multiple input schemes, pause anywhere. ## Session shape - **First full loop ≤ 60–90s** — a complete win-or-lose cycle with a score in the first minute. - **Result screen = 1 glance, 1 button**: score, best, delta, play-again. - **End every session with an open loop**: next unlock, almost-beaten score, teased content — adjacent to the retry button. ## Audit checklist (every "no" is a defect) 1. Meaningful input within 5s of load? 2. Core verb performed in real play within 30s? 3. Every instruction ≤ 8 words; first-minute total < ~25 words? 4. Mute all text — still discoverable through doing? 5. Each mechanic introduced alone, failure cheap or impossible? 6. First failure shows what killed you + hints the counter? 7. Death-to-retry one input, < 2s? 8. Session ends with a visible reason to replay (delta, unlock, tease)? 9. Every object's function readable from its appearance? 10. Difficulty has recovery valleys after spikes? 11. Zero modal popups/cutscenes/settings before first play? 12. Native input works immediately (touch on mobile, keys on desktop)? 13. Skill-gated game has a neutral, mid-game-reachable assist option? 14. Something softens after 3–5 failures at the same spot? 15. Score/goal visible at all times? Related skills: `design-lenses` (finds the problems this skill fixes), `level-design` (teaching through geometry), `game-feel` (the juicy first input), `game-playbook` (build order).