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: Formalize XpDungeonCrawlerPage or XpTempleGroundsPage.
  • 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: Review assets folder size and implement lazy loading for images/audio.

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. βœ…

  • [/] 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
  • Extract useBattleRewards hook
  • Move useTemple.ts to hooks/temple/
  • Move ability hooks to hooks/abilities/

πŸ”΄ Large Vue Files (>800 lines) - Need Code Split

File Lines Action
BattleroomDevTools.vue 1610 Split into .vue/.ts/.scss
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 Extract into battle hooks
BattleGround.ts 1315 Orphaned - audit & deprecate
useBattleEngine.ts 974 Split into sub-hooks
useTempleCreator.ts 929 Split into sub-hooks

[!IMPORTANT] BattleGround.ts is orphaned (no .vue, not imported) but contains unique animation work. Do NOT delete without full audit. Toast methods deprecated for battles - use useBattleDialogs instead.

🟒 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.
    • 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:

    • 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".