Repository navigation
2026 11 04 setup wizard design
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.
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).
- A separate first-launch wizard, not a change to Quick Start (
SwitchProfile/QuickStart,runQuickStart). Quick Start stays as the one-tap fixed pack. - Chores are chosen per hero by age band and per room of the house; the parent confirms on a review step.
-
Extras step on by default: the
StarterWorldshops, abilities and rewards load unless switched off. - Nothing is written until the final button; quitting mid-way leaves the game untouched.
- 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;
XpFirstRunTourmust not start over the wizard).
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.
-
Pure planner
setupPlan(answers)insrc/lib/services/setup/setupPlan.ts. Input: heroes with age bands, rooms, the ticked chore beasts per hero, the extras flag. Output: aBackupFileplan likequickStartPlan. It usesbrowseLibrary({ room, age, exclude })for the pre-ticks,adoptLibraryBeastfor the beasts, andquestFromSeedfor 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 pathStarterWorldand Quick Start use. No new storage code. Extras come fromStarterWorld's shops, abilities and rewards, merged in only when the flag is on. Categories come fromSTARTER_CATEGORIES. -
Screen: thin.
src/app/SideMenu/SetupWizard/(a page or a modal on the shell) holds the answers in a reactive draft, callssetupPlanfor the review and summary, and applies on Begin. The.ts/.scsspair follows the page convention; sounds viaplay$fx, no Ionic alerts. -
Hero profiles: new heroes use
quickStartHeroand the Game Master profilequickStartGameMaster(exported fromquickStart.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.
- 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.
-
setupPlanjest 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.
- The guard or screen that offers the wizard at first launch, and its interplay with
XpFirstRunTour. - Whether a hero profile can store an age or band.
- How the parent hero is entered when a Game Master profile already exists.
- Architecture
- Component-Library
- Hooks-Reference
- Temple-System
- Battle-Field-Architecture
- current_context - For AI/Human Handoff
- User Menu
- General Settings
- Family Settings
- Sound Settings
- Notification Settings
- Reward Settings
- Party Settings
- Theme Settings
- Chore Settings