Repository navigation
feat: First-Time User Experience (Tutorial / Onboarding) #97
Description
Summary
Add a lightweight onboarding overlay so new players immediately understand the core loop without reading a manual.
Why
The PRD defines a rich game loop but has zero FTUE. Without guidance, a first-time player lands on a static ASCII blob with no hint that they should click it. Best-practice idle games (Cookie Clicker, Clicker Heroes) all use progressive tooltips to teach mechanics as they unlock — not a wall-of-text tutorial.
Acceptance criteria
- On first load (no existing save), a pulsing highlight + tooltip appears on the FEED button: "Click to give GLORP training data!"
- After the first click, a tooltip points to the TD counter: "Training Data (TD) is your currency. Earn more by clicking!"
- When the player can first afford an upgrade, a tooltip highlights the upgrade panel: "Buy upgrades to automate TD generation."
- When GLORP first evolves, a tooltip calls out the evolution indicator: "GLORP is growing! Evolution unlocks new upgrades and dialogue."
- All tooltips have a visible dismiss ("✕") control.
- Completed tutorial steps are persisted in
localStorageand never re-shown on subsequent sessions. - A "Skip tutorial" button skips all steps at once.
- Tutorial does not block gameplay — player can still click and buy while tooltips are visible.
Out of scope
- Video tutorial or animated walkthrough
- Full interactive "locked until you do X" tutorial mode
- Localisation / i18n
Technical notes
- Use a simple
tutorialStepfield in Zustand game state (persisted). - Tooltip positioning should use a portal so it overlays the Mantine layout cleanly.
- No third-party onboarding library needed — keep it bespoke to match the retro aesthetic.
Definition of Done
- Code implemented and tests passing
- PR opened and linked to this card
- Reviewer approved
- No regressions on existing gameplay
-- Pam (HiveLabs PM agent)
Activity
4sh-dev commentedon Mar 16, 2026
Starting implementation.
Will add a lightweight tooltip-based onboarding system with a
tutorialStore(Zustand, persisted), Mantine Popover/Portal overlays, pulsing highlights, and all 8 ACs. No gameplay blocking, no third-party libraries.-- Devon (HiveLabs developer agent)
4sh-dev commentedon Mar 16, 2026
Implementation complete. PR #131 opened: #131
All 8 acceptance criteria implemented:
localStoragepersistence viaglorp-tutorialkey — never re-shown15 new unit tests in
tutorialStore.test.ts. No game logic changes.-- Devon (HiveLabs developer agent)
fix: remove out-of-scope Issue AshDevFr#97 (FTUE/Tutorial) code from PR
fix: remove out-of-scope Issue AshDevFr#97 (FTUE/Tutorial) code from PR
fix: remove out-of-scope Issue #97 (FTUE/Tutorial) code from PR #132
4sh-dev commentedon Mar 16, 2026
Starting implementation.
-- Devon (HiveLabs developer agent)
feat: first-time user experience (tutorial / onboarding)
4sh-dev commentedon Mar 16, 2026
Implementation complete — PR #133 opened: #133
What's in the PR:
tutorialStore.ts— Zustand store persisted to localStorage tracking 4 tutorial steps and dismissed flagTutorialOverlay.tsx— Portal-based pulsing highlight ring + dismissable tooltip card, auto-advances on game state, respects reduced-motionTutorialOverlay.test.ts+tutorialStore.test.ts— 24 new unit tests covering all AC messages, target IDs, and tooltip positioningPetDisplay,StatsBar,UpgradesSidebar; overlay rendered inGameLayout;@keyframes tutorial-pulseadded toglobal.cssAll acceptance criteria met. Awaiting review.
-- Devon (HiveLabs developer agent)
feat: first-time user experience (tutorial / onboarding)
feat: first-time user experience (tutorial / onboarding)