Skip to content

2026 11 04 setup wizard design

Xopher edited this page Nov 4, 2026 · 1 revision

Setup wizard: preload the game with the family's own chores

Status: draft 1, 2026-11-04. Owner: "the game starts with no enemies in the system; shouldn't an in-game wizard ask the questions needed to preload the game with the right content?" Decisions below were taken in chat the same day.

1. Goal

A new family finishes the wizard with a playable world: heroes (the parent is a hero too), chores already tied to beasts and assigned to the right hero, and, unless they opt out, the starter shops, powers and rewards. Nobody has to author anything first.

Out of scope: the scripted kid prologue (Bed Basilisk ambush, one-element-at-a-time unlocks; see the 2026-10-12 onboarding notes), and the "uncover chores like Pokemon" idea (dropped by the owner for now).

2. Decisions taken

  1. A separate first-launch wizard, not a change to Quick Start (SwitchProfile/QuickStart, runQuickStart). Quick Start stays as the one-tap fixed pack.
  2. Chores are chosen per hero by age band and per room of the house; the parent confirms on a review step.
  3. Extras step on by default: the StarterWorld shops, abilities and rewards load unless switched off.
  4. Nothing is written until the final button; quitting mid-way leaves the game untouched.

3. When it runs

  • First launch: when the bestiary and the quest list are both empty, the wizard is offered. The offer can be skipped; skipping must not nag again in the same session.
  • Again later: a Settings row "Run setup again". Re-runs only add or replace records the plan owns by id (merge restore); they never wipe the family's own beasts, quests or art (original beast art is family art).
  • Open to confirm in the plan: the exact guard or screen that offers it (SwitchProfile is where Quick Start lives; XpFirstRunTour must not start over the wizard).

4. Steps (one decision each, thumb-reach footer, Back / Next)

Built on XpWizardShell (src/components/organisms/WizardShell/), which exists, with its step logic (useWizardSteps) and one guide line per step.

# Step Decision Valid when
1 Your family Each hero's name and age; the parent is a hero too. If profiles already exist they are listed and only the age is asked. at least one hero named, every age set
2 Your house Tick the rooms the house has (from libraryRooms()), plus "yard" / "pets" if they apply. at least one room
3 Haunting review Per hero: the chores for that age band and those rooms, pre-ticked, shown as their beasts. Untick, or add more with type-ahead (suggestBeasts). each hero has at least one chore
4 Extras Starter shops, powers and rewards: one switch, on by default. always
5 Summary Everything that will be created; a tap on a line jumps to its step. Final verb: Begin. always

Age bands follow the library's age field: little (7 and under), kid (8 to 12), teen (13 and up; adults use teen). A hero sees their own band's chores, plus the band below when the parent adds them by hand.

5. Design

  • Pure planner setupPlan(answers) in src/lib/services/setup/setupPlan.ts. Input: heroes with age bands, rooms, the ticked chore beasts per hero, the extras flag. Output: a BackupFile plan like quickStartPlan. It uses browseLibrary({ room, age, exclude }) for the pre-ticks, adoptLibraryBeast for the beasts, and questFromSeed for the quests (each quest assigned to its hero). Ids are the library's own, so a re-run updates instead of duplicating.
  • Applying: restoreBackup(plan, { mode: "merge" }), the same path StarterWorld and Quick Start use. No new storage code. Extras come from StarterWorld's shops, abilities and rewards, merged in only when the flag is on. Categories come from STARTER_CATEGORIES.
  • Screen: thin. src/app/SideMenu/SetupWizard/ (a page or a modal on the shell) holds the answers in a reactive draft, calls setupPlan for the review and summary, and applies on Begin. The .ts / .scss pair follows the page convention; sounds via play$fx, no Ionic alerts.
  • Hero profiles: new heroes use quickStartHero and the Game Master profile quickStartGameMaster (exported from quickStart.ts). Where a profile already exists, no profile is created or changed.
  • Hero age storage: the age only picks the band; it is not stored on the profile unless the profile type already has a field for it (confirm in the plan).
  • Empty pre-tick: if a room and band have no library chores, the review step shows "nothing common here, add your own" rather than an empty list.

6. Errors and edge cases

  • Duplicate or blank hero names: Next is disabled with the one-line reason (the shell's blockedBy).
  • Apply fails (storage error): nothing partial is claimed; the summary shows the error and Begin stays available. The merge restore is idempotent, so a retry is safe.
  • A family that skips the wizard still has Quick Start and the Compendium; the empty-bestiary state shows a "Run setup" prompt instead of a blank page.

7. Testing

  • setupPlan jest spec: band and room filtering, per-hero assignment, id stability on re-run, extras on/off, empty room, unknown room ignored.
  • Wizard step validity spec on the shell's step logic; a Cypress smoke (390x844) walking all five steps against a fresh store and landing in a populated game.
  • Run only the touched specs locally (chemx test <spec>); the full suite runs on the PR.

8. Open items for the plan

  1. The guard or screen that offers the wizard at first launch, and its interplay with XpFirstRunTour.
  2. Whether a hero profile can store an age or band.
  3. How the parent hero is entered when a Game Master profile already exists.

Table of Contents


Home - See Pages

Developer Docs

Start Screen

User Management

My Portal

My Home

The City (Hometown)

The World Map

The Dungeon

Game Master

Settings

Support & Glossary

About XP

Clone this wiki locally