Roadmap - xopherdeep/do-it-for-the-xp GitHub Wiki

🗺️ Do It For The XP - Project Roadmap

Mission: Transform mundane chores into epic quests, making productivity an adventure for families and individuals.

🏗️ Current Landscape

The application is currently divided into three main pillars:

1. 🛡️ The Game Master (Admin/Parent)

Located in src/app/SideMenu/XpGameMaster

Dashboard: High-level overview of the game state.
Compendium: Database management for the game world.
- Achievements: Quests and tasks.
- Bestiary: Enemies (represented by tasks/challenges).
- Abilities & specialized Magic: Rewards and tools for players.
- Accessories: Items to equip.
- Temples: Training grounds.
Do This, Not That: Habit tracking/correction system.
Chat: Communication Channel (likely for GM <-> Player messaging).

2. ⚔️ The Player (Bounty Hunter)

Located in src/app/Console/MyPortal

My Portal: The central hub for the player.
- My Home: Personal space (Calendar, Cooking, Posts, Growth).
- My Party: Team management.
- Hometown: Virtual town hub (Shop, Hospital, Bank, Temple).
- World Map: Navigation and exploration.
- My Profile: Stats and progress tracking.

3. ⚙️ Core Mechanics

Battle System: The "Gamified" task completion engine.
Currency System: GP (Gold), XP (Experience), AP (Ability Points).
Tech Foundation: Vue 3, Ionic 7, Capacitor, TailwindCSS.

🚧 Technical Roadmap (The "Under the Hood" Quests)

These items are critical for long-term stability and developer experience.

Phase 1: Standardization & Cleanup

Service Refactor: Organize src/lib/services into feature modules (e.g., features/battle, features/economy).
State Management Evolution: Migrated complex Vuex modules to Pinia for better TypeScript support and modularity. (Phase 1 Complete)
Component Architecture: Establish a clear atoms -> molecules -> organisms hierarchy to reduce code duplication in src/components. ✅
Legacy State Cleanup: Complete removal of all Vuex modules and dependencies in favor of Pinia. ✅
- ✅ Core components migrated (App.ts, Router, BattleService)
- ✅ Battle views migrated (BattleField.ts, useBattleEngine.ts)
- ✅ Dev tools & Test utilities migrated
- ✅ Vuex uninstalled and store files deleted
Dashboard UI Cleanup: Refactored XpDashboard to use reusable atoms (XpStatBox) and grid components (XpDashboardGrid), removing dead code.

Phase 2: Performance \u0026 Quality

Player Stats \u0026 Leveling System: Implemented proper HP/MP calculation based on level, job class, and special stats. See Player-Stats-Leveling.md
- ✅ Base stats per job class (Warrior, Mage, Thief, Monk)
- ✅ Level-based HP/MP growth formulas
- ✅ Special stats contribution (Endurance → HP, Intelligence/Wisdom → MP)
- ✅ XP requirements per level (quadratic scaling)
- ✅ PlayerStatsService for centralized calculations
- ✅ useBattlePlayer hook for battle HUD integration
[/] Page Standardization: Implement standardized page shells across the app. @[docs/Page-Architecture.md]
- Game Master Pages: Convert to XpRpgPage pattern (via XpPage).
- Tab Pages: Standardize XpTabPage usage in dashboards.
- Portal: Refactor My Portal to proper XpPortalPage shell. ✅
- Dungeon/Temple Grounds: Retired placeholder room action FAB in favor of interactive 3D voxel models (treasure chest, keys, springs, camps, gates, portals). ✅
Profile Persistence: Current user profile now persists to localStorage across page reloads
Unit Testing: Increase coverage for core logic (Battle System, GP calculations).
E2E Testing: Expand Cypress tests for critical flows (Login → Task Completion → Reward).
[/] Asset Optimization: Convert assets to WebP (Batches 1, 2, and 4 complete: about, midjourney, world backgrounds, hometown, beasts; saving over 85 MB total).
- Mobile Asset DLC & Modal Polish: In-app DLC downloader modal with theme-tokenized typography, high-contrast dark theme surfaces, and offline asset hydration. ✅
Family Overview Dashboard & Preferences Integration: Comprehensive family pulse dashboard (/family-overview and /xp-settings/family-overview), aggregating roster vitals, daily streak momentum, today's chore completion, and pending Game Master approvals with quick play and profile chooser shortcut. ✅

Phase 3: Code Quality & Refactoring

Goal: Split large files, extract reusable hooks, atomize components. SFCs should be <500 lines.

🧹 Standardization (New)

Global Linting Cleanup: Resolved 18+ ESLint errors and warnings across core files. ✅
Document Standards: Create docs/CodingStandards.md ✅
Mobile Navigation Fix: Resolved Compendium tab issues on mobile devices.
Compendium Tab Root Navigation: Fixed bug where clicking active tabs didn't return to root index. ✅
Compendium App Bar Menu Button: Added menu button with select audio feedback to the Compendium dashboard app bar. ✅
Bottom Nav MMO Overhaul & Reactive Area Sync: Replaced hardcoded black bottom bar with translucent MMO action dock, removed harsh bordered boxes, and converted area tracking to a reactive computed property. ✅
[/] Mixin Migration: Migrate all legacy Mixins to Composables (src/hooks/).
- useTravelingMerchant
- useItemFetcher
- useUserActions
View Restructuring:
- Move src/views/Console → src/app/Console
- Elevate XpGameMaster → src/app/GameMaster
- Group System/Settings pages into src/app/SideMenu
Router Refactoring: Split monolithic router files and guards.
- router/guards/ - Extracted individual guards (Auth, Battle, etc.)
- game-master.routes.ts - Split child routes into modular files
Ability System Refactor: Separated types vs runtime constants.
- Created types/abilities.ts for pure type definitions
- Moved runtime logic to hooks/abilities/abilityConstants.ts

🪝 Hooks Restructure

New organized hooks structure with domain subdirectories:

src/hooks/
├── battle/                    # Battle-related composables
│   ├── index.ts              # Barrel export
│   ├── useBattleDialogs.ts   # ✅ Dialog queue, typing, advance
│   ├── useBattleAnimations.ts # ✅ Attack, hit, victory anims
│   ├── useBattleRewards.ts   # XP/GP calculation (pending)
│   └── useBattleEngine.ts    # Core state (move from views)
├── temple/
│   └── useTemple.ts          # Gameplay navigation (move here)
│   # NOTE: useTempleCreator.ts stays in views/XpTempleCreator/hooks/
├── abilities/
│   ├── useAbilities.ts       # (move here)
│   └── useAbilitySystem.ts   # (move here)
└── ... (useAudio.ts, useDialog.ts, etc.)

Completed:

Created hooks/battle/ directory structure
Extracted useBattleAnimations from BattleGround.ts
Extracted useBattleDialogs from BattleField.ts

Pending:

Audit BattleGround.ts unique features before deprecation ✅ (deleted 2026-10-08)
Extract useBattleRewards hook ✅ (battle/battleRewards.ts + composables/useBattleOutcome.ts)
Move useTemple.ts to hooks/temples/ ✅
Move ability hooks to hooks/abilities/

🔴 Large Vue Files (>800 lines) - Need Code Split

File	Lines	Action
`BattleroomDevTools.vue`	1610	✅ Deleted 2026-10-08 (unreachable dev harness)
`XpTempleSettings.vue`	1154	Split into .vue/.ts/.scss
`XpConfigAchievement.vue`	1429	✅ Split Completed (.vue/.ts/.scss separation)
`XpAbilities.vue`	978	✅ Split Completed (.vue/.ts/.scss separation)
`XpAbilityManager.vue`	977	Split into .vue/.ts/.scss
`XpBackgroundSelector.vue`	906	Split into .vue/.ts/.scss
`JobClassSelector.vue`	877	Split into .vue/.ts/.scss
`SwitchProfile.vue`	851	Split into .vue/.ts/.scss
`MyParty.vue`	845	Split into .vue/.ts/.scss

🟠 Large TypeScript Files - Need Modularization

File	Lines	Action
`BattleField.ts`	1532	✅ Rebuilt 2026-10-08 as a ~250-line page over `battle/` + `composables/` (see Battle-Field-Architecture)
`BattleGround.ts`	1315	✅ Deleted 2026-10-08 (orphan; its animations live on in `_BattleField.scss`)
`useBattleEngine.ts`	974	✅ Deleted 2026-10-08 (never wired; replaced by `BattleService` + composables)
`useTempleCreator.ts`	929	Split into sub-hooks

🟢 Components to Atomize

Atoms (single-purpose, primitive):

CurrencyBadge - GP/XP/AP display with icon
HealthBar - Reusable progress bar with color
LevelBadge - Simple level number display
ElementIcon - Temple element type with icon/color

Molecules (atom combinations):

BeastCard - Beast preview with stats
RoomTypeSelector - Room type picker
QuestPreview - Quest info card
UserChip - User avatar + name badge

Organisms (complex UI sections):

TempleMap - Full dungeon map display
AbilityGrid - FFX-style grid view
BattleHUD - Complete battle UI

📐 File Splitting Template

When splitting a large SFC:

ComponentName/
├── ComponentName.vue    # Template only + imports
├── ComponentName.ts     # All script logic (defineComponent)
├── _ComponentName.scss  # All styles
└── index.ts             # Export barrel

🚀 Feature Roadmap (The "New Frontiers")

Quarter 1: Deepening the Gameplay

Enhanced Battle System: ✅ Core system complete
- ✅ Battle intro dialog with Earthbound-style typing
- ✅ Integrated action menu within dialog box (replaced FAB)
- ✅ Player HUD with animated HP/MP bars
- ✅ Battle music integration
- ✅ UI Polish: Synchronized Area FAB blur, optimized Avatar presentation, standardized Ref-based modal dismissal, implemented global tab-bar highlighting, added a premium splash page for temple discovery, fixed the retro User HUD menu toggle, and matched the "Attack" task menu styles to the main RPG dialog menu (removed headers and updated icons to claw-marks).
- ✅ Temple Navigation: Implemented state-based smooth scrolling, formalized /splash default routing, and tiered background strategy (parent-hosted vs child-transparent).
- ✅ Setup Slideshow Polish: Transformed the onboarding flow with premium glassmorphic UI, dynamic bg-slide color variations per system, and vue3-autocounter stat reveal animations.
- ✅ Quest Type Refactor: Replaced standard radio groups in XpConfigAchievement with iconic, dialpad-grid selection modals. Implemented generic XpTypeSelectorModal for streamlined Quest and Party type definition.
- Battle Timer Bar Pulsation: Accelerating heartbeat pulsation and border glow across the attack timer bar that speeds up as time counts down. ✅
- Add "Boss Battles" for major milestones (pending)
- Visual polish for battle animations (ongoing)
Unique Equipment System: Implement consumable and active items to manipulate the task queue. See Equipment-Mechanics.md
- Documentation: Defined mechanics and MP costs for all 16 distinct items. ✅
- Core Logic: Create EquipmentService to handle item effects (MP deduction, task manipulation).
- UI Integration: Connect EquipmentItems.ts actions to the new service.
[/] Hometown Expansion:
- Shops Basic Consumable Stock: Stock basic items (Health Potion, Mana Potion, Ether, Elixir) across shops with immediate backpack delivery. ✅
- Hotels in Every World: Mounted 3D voxel hotel landmarks across all 9 regional worlds backed by hotelRegistry, world-parameterized routing, and origin-world parent resolution. ✅
- Bank: Implement interest/investment mechanics for GP.
- Hospital: Add "Wellness" checks and HP recovery mechanics.

[/] Temple Creator: Finish the XpTempleCreator to allow GMs to build custom training regimens.

🏰 Room Editor Roadmap (Dungeon Maker Style)

Inspired by Link's Awakening dungeon maker - each room is fully configurable by the Game Master.

✅ Completed:

Room type selection modal with categories (Combat, Resources, Recovery, Navigation, Structure)
Cardinal door system (N/E/S/W) with lock toggle
Adjacent room detection for wall limiting
Monster room beast selector integration
Lock-on-enter toggle for combat rooms
Room navigation (prev/next) within editor
Battle dialog integration with card menu actions
RPG-styled menus (XpRpgMenu atomized component)
Area FAB (Page Menu) centered on screen with backdrop + close button
Wall icon consistency (using temple element icons)
Floor grid size configuration (custom X/Y dimensions)
Floor deletion with 1F protection
Clear cell action in floor editor context menu
Room data save/reload with toaster confirmation
Standardized Coordinate Display (+1 Offset) ✅
Monster Room Config Token Visibility ✅
Raw JSON Temple Editor ✅
Wall Token Logic Fix: Resolved adjacency bugs and readability issues (____ tokens)
Room Editor Toggles Fix: Resolved double-triggering bug on "It's a Trap" and Mimic toggles where clicking the switch itself failed to toggle. ✅

🎯 In Progress:

Loot Room Configuration ✅
- Treasure chest reward selector (items, gold, XP)
- Mimic chance toggle (trap chest) with beast selector
- Gold amount slider, consumable items grid
Shop Room Configuration ✅
- Shop selector linking to existing shops from ShopsDb
Navigation & Focus ✅
- Formalized /splash default routing for temple entry
- State-based smooth scroll and highlight on return navigation
- Tier-isolated accordion focus for beast management
- Tiered background strategy (parent-level bg-slide)

📋 Pending Room Configurations:

Room Type	Config Options	Priority
Health/Mana	Restoration %, cooldown	Medium
Key/Master Key	Key ID, door targets	High
Trap	Damage type, amount, visibility	Medium
Puzzle	Puzzle type, reward	Low
Teleport	Destination room link	Medium
Secret	Unlock condition (bomb, key, etc.)	Low
Boss/Miniboss	Boss selection, loot table	High

🔧 Technical Improvements:

Temple Engine Architecture (The DSL Approach)
- Establish the Spatial Palette: 4-character tokens (e.g., ____, _XX_, $__$ ) for monospaced grid design.
- Implement the Hydrator: A loader that converts static blueprints (Flyweight) into mutable room instances (Instance).
- Develop the Interaction Controller: Handles movement, reciprocal door locking logic, and state synchronization.
- Create the Core Game Loop: Integration of Load -> Render -> Input -> Update.
Room data persistence to temple save
Room preview in grid view
Room validation (must have entrance, boss for temples)
Template rooms (pre-configured room types)

Quarter 2: Social & Connectivity

Multiplayer Parties: Allow multiple "Bounty Hunters" to join a party and tackle quests together.
Cloud Sync: Robust offline-first data sync (if not already fully implemented via PouchDB/etc).
Push Notifications: "Quest Available" or "Battle Started" alerts via Capacitor.

Quarter 3: Player Customization

Avatar Builder: Expand the character customization options.
Housing System: Allow players to spend GP to decorate "My Home".

🏁 v1 Completion Plan (added 2026-10-08)

Definition of done (proposed): a parent installs the app on one phone, creates a GM profile and kid profiles, authors quests/beasts, and a kid can see today's quests, complete them (claim or battle), have XP/GP/AP land on their persisted profile, get GM approval where required, and spend GP on real-world rewards the parent can see. Temples, abilities and the world map stay as bonus content; multiplayer, cloud sync, push and housing are out of v1.

Persistence backbone: every user-store stat mutation writes to ProfileDb (persistUser). ✅
Quest Log + schedule engine: QuestLogDb, QuestSchedule (once/daily/weekly/custom windows, unit-tested), QuestEngine.getQuestBoardForUser. ✅
Completion service: claim → log → pay now or hold for approval; GM approve/reject. ✅
Hero UI: Quest Log shows open / pending / done, MyTask Claim is real, beast quests show "Fight!". ✅
GM UI: /game-master/approvals, real Approvals page (quests + purchases + history), live dashboard tile. ✅
Battle v2 (2026-10-10): the fight looks and feels like a game: beast stage with entrance/idle/hit/strobe, chore pips, deadline clock with a critical pulse, checklist bottom sheet with Done! confirmation, hero card with rolling HP, shake/flash/haptics, victory card counting the loot; engine retuned (12% strikes, 3 min/chore, Defend trade, Run confirm, approval hold, full HP after every fight, AP-only free fights); 6 jest suites + Cypress walk-through. See Battle-Field-Architecture. ✅
Quest battles: rebuilt battle page; /battle/:userId/quest/:questId loads the quest's beast and victory records the completion. ✅ (see Battle-Field-Architecture)
GM gating: Game Master toggle (GM-only, PIN required), /game-master guard, masquerade clean-up. ✅ (family-settings gating still open: board #24)
Shop loop: shop sells GM-stocked accessories for real GP; purchases logged; GM fulfils/refunds in Approvals. ✅
Asset diet (Part 2 - WebP conversion): converted 418 images across all 4 batches (saved 120.9 MB, 165 MB -> 45 MB payload reduction). ✅
Dead code sweep: ~50 orphan files removed across two sweeps. ✅
[/] Release checklist: dev routes gated ✅; Cloudflare Pages deployed ✅; still open: .env for the Gemini key, native file export (board #22), Capacitor sync, store listing.
Web Hosting & Edge Deployment: Cloudflare Pages configured and live at https://do-it-for-the-xp.pages.dev with SPA routing and asset cache headers. ✅
Temple progress persisted per hero (position, keys, map, cleared rooms); chests/doors persistence is board #23.
Backup everything (Settings → General) across all 13 local stores. ✅
World map 3D voxel models: 9 custom voxel stages inspired by map icons wired to XpStageModel organism with performance throttling and center FAB clearance. ✅
Android Widget Suite & Voxel Hero Figurine: Expanded to 12 native widgets with homescreen previews, 3D voxel diorama figurine (Slot 12), companion voxel avatar, and live RPG Box style sync. ✅
Internationalization (i18n) Foundation & Language Settings: Reactive localization engine (i18n.ts, useI18n), language selector in Settings > General, persistent xp.language preference, and initial Japanese (ja) translation dictionary. ✅
Remove the dead WordPress API path and the pages still reading it (board #21).
Browser walk-through / e2e suite (board #13): first rendered verification of the whole loop.

🌏 Internationalization (added 2026-10-29)

Multi-language support to bring Do It For The XP to international families and regions across the world's top languages (English, Chinese, Hindi, Spanish, French, Arabic, Bengali, Portuguese, Russian, Japanese, German).

i18n Core Engine: Reactive locale service (src/lib/services/i18n/i18n.ts), useI18n composable, fallback to English, parameter interpolation, and persistent device storage (xp.language). ✅
General Settings Language Control: Removed "App language" from Coming Soon, added active language dropdown with native labels in Settings > General, and translated General Settings across the top 10 languages. ✅
Navigation & Shell Translation: Localize Title Screen, MyPortal tabs, HUD, and bottom dock.
Battle & Quests Translation: Localize battle dialogs, action menus, Quest Log, and victory screens.
Game Compendium & Hometown: Localize Bestiary, Abilities, Shops, Bank, and Hotel.

🌐 Multiplayer (in progress, added 2026-10-13)

The app as a gamified virtual body double: Families and Parties, joined by QR, heroes on their own phones. Part 1 of 3, the shared base, is being built; part 2 (A, the party and body double) and part 3 (B, Family Sync, XP Pro) need specs. The work is tracked on the chemx boards, not here: app epics #1299 (part 1) and #1333 (what comes next) on the do-it-for-the-xp board (chemx team task list --sprint=mp-base --all, --sprint=mp-next), server epic #6080 on the xophz-compass-xp board. Spec: superpowers/specs/2026-10-13-multiplayer-shared-base-design.md; plan: superpowers/plans/2026-10-13-multiplayer-shared-base.md; idea backlog: #1159.

Server (xophz-compass-xp, xp-family/v1): families, heroes, link codes, hero keys, the event stream, server rewards (MP1–MP6). Batch review open: #6087.
App foundations: the flag, age groups, hero cards, event kinds, the family routes client, game signals, the send queue, family binding (MP7–MP11).
Family store sending (MP12 #1305) and the family card in Family Settings (MP13 #1306).
Kid phones: link codes and phone key (MP14 #1307), Link a phone (MP15 #1308), /link claiming (MP16 #1309), kid mode (MP17 #1310).
Rewards paid once (MP18 #1311), review #1331, Cypress screens (MP19 #1312).
[/] Rehearsal & review: the rehearsal run (MP20 #1313 queued), final review #1332.
[/] Party tab: replace the mock data with real data (done, #1334), family data from the event stream (#1335).
Specs: part 2, the party and body double (#1336).
[/] Part 3, Family Sync (the hero follows the player): spec superpowers/specs/2026-10-22-family-sync-design.md, plan superpowers/plans/2026-10-22-family-sync.md (23 tasks). Server side merged and released (xophz-compass-xp PR #1, v26.10.22-634: records, the hero's turn, the Pro gate; PR #2, v26.10.22-987: any-writer quests and beasts). App side on branch feat/family-sync (board epic #1508, #1509-#1525), PR #164: built (the sync core, the hero's turn, verdicts, kid phones as the full portal), rehearsed on the rehearsal network and covered by Cypress; awaiting the final review and the merge. Owner: confirm the plugin releases reached doit.forthexp.com, then the APK rebuild and upload.
Owner: the Founder's Lifetime decision (#1338); install the plugin update on doit.forthexp.com (#1339).

👤 Account (added 2026-10-15)

The family's account is the Game Master's Town Hall link: one WordPress account on doit.forthexp.com, stored on the device as an Application Password. Settings, Account is parked as Coming soon (the develop branch's page is kept at tools/reference/develop/AccountSettings.vue).

Account page from the Town Hall link: the menu's way to link and unlink (the Town Hall page keeps its prompt); show the login, display name and email from wp/v2/users/me; the plan from the XP Pro store; email and password changes open the site's profile page.
Google and Apple sign-in: the site offers them on its sign-in and authorize pages (an owner-installed social login plugin on the network; Apple needs a developer account and Sign in with Apple set up), then the Account page lists them as linked accounts. No app-side OAuth.

Kid Creations (added 2026-10-27)

A Maker kid (a hero a Game Master checked under Settings > Party) draws a beast, names it, lists the chores that beat it and suggests quests for the family; nothing is live until a Game Master approves it from Approvals > Creations. The maker is credited ("Drawn by", "Made by", "Suggested by") and paid a little AP, never GP. A proposal is a block on the beast or quest record, so Family Sync carries it with no new store. The work is tracked on the board: epic #1568 (KC1-KC10, #1572-#1581). Spec: superpowers/specs/2026-10-27-kid-creations-design.md; plan: superpowers/plans/2026-10-27-kid-creations.md.

Proposal model and rules (KC1 #1572): creations.ts (propose, approve, send back, resend, the per-maker cap, credit lines, creationAp), proposal on Beast and Achievement, and isLiveBeast through every family-beast list so a waiting beast is never fought.
The Maker setting (KC2 #1573): FamilySettings.makers, canMake, and a toggle per kid in Settings > Party.
A photo of a drawing (KC3 #1574): BeastPhotoPicker turns a camera or file picture into a square 512px portrait under 150 KB; the Game Master's beast form offers it too.
The Beast Maker (KC4 #1575): Look (photo or library), Name, Chores, Ready, in three voices; "Draw a Beast" in the quests and calendar FAB; "Make a quest with it" opens the Quest Wizard on the new beast.
Quest Wizard for a maker (KC5 #1576): a Who step (Me, each sibling, Everyone, a parent); a quest for anyone but the maker, or on a waiting beast, is saved as a proposal. Today's self-made quests stay live.
Approvals > Creations (KC6 #1577): rows with the picture, the credit and the paired quest; Approve (with a target chooser), Send back with a note, Edit in the Game Master's own form; AP paid once; History lines.
Notifications and reminders (KC7 #1578): creation-waiting, creation-approved and creation-returned, the approval watch and reminders, the dashboard tile.
My creations (KC8 #1579): the kid's list with Waiting, Came back and In the game chips; Fix it, Send again, delete.
Credit everywhere (KC9 #1580): the Bestiary's Creations segment and credit chip, the Beast Card, "Suggested by" on quest rows and the calendar.
Cypress walk (KC10 #1581): tests/e2e/specs/kid-creations.spec.js on tests/e2e/fixtures/kid-creations-backup.json. A maker draws a beast from the library, adds two chores, sends it and makes a quest for everyone; the Game Master approves the pair in Approvals > Creations; the beast stands in the Bestiary as "Made by Max", the kid is paid 5 AP and a sibling finds the quest on their board. A second test sends a photographed drawing (drawing.png) through the file input and the crop and ends with "Drawn by Max" and 4 AP.
[/] Merge: branch feat/kid-creations, PR with auto-merge once the owner has read the spec; owner tasks #1569-#1571 (confirm D2-D5, the AP amounts or a look unlock, where the Maker lives).
Follow-ups (spec section 1, Out): an in-app pixel pad (#1582), cutting the paper out of a photographed drawing (#1583), a HomeTown building for the Maker, the Scriptorium (#1584), proposals from a free kid phone (#1585), the maker's nick kept on the record so the credit survives a deleted profile (#1586).