Battle System - xopherdeep/do-it-for-the-xp GitHub Wiki

flowchart TB
  %% Initial Task Check
  A[Count Tasks] --> B{# of Tasks > 0?}
  B -- No --> C[Wait 60s]
  C --> A
  
  %% Battle Initialization
  B -- Yes --> D[Battle Start]
  D --> D1[Load Beast Background & Music]
  D1 --> D2[Initialize Beast with Subtasks]
  D2 --> E[Charging Turn Gauge]
  
  %% Turn System
  E --> F{Turn Gauge Full?}
  F -- No --> E
  F -- Yes --> G[Turn Ready]
  
  %% Beast Turn
  G --> G1{Whose Turn?}
  G1 -- Beast --> G2[Beast Attacks]
  G2 --> G3[Player Loses HP]
  G3 --> E

  %% Player Turn & Actions
  G1 -- Player --> H[Choose Action]
  H --> H1{Action Type?}
  
  %% Attack Option
  H1 -- Attack --> H2[Select Subtask to Complete]
  H2 --> I[Start Task Timer]
  I --> J{Task Completed?}
  J -- No --> J1[Continue Timer]
  J1 --> J
  J -- Yes --> K[Mark Subtask Complete]
  K --> K1{All Subtasks Done?}
  K1 -- No --> E
  K1 -- Yes --> M[Battle Won]
  
  %% Item Option
  H1 -- Use Item --> I1[Select Item]
  I1 --> I2[Apply Item Effect]
  I2 --> E
  
  %% Run Option
  H1 -- Run --> R1[Attempt Escape]
  R1 --> R2[Player Loses Some HP]
  R2 --> R3[Return to Task List]
  
  %% Battle End Conditions
  M --> N[Receive Rewards]
  N --> O[Return to Task List]
  
  G3 --> L{Player HP <= 0?}
  L -- Yes --> L1[Battle Lost]
  L1 --> L2[Recovery Period]
  L2 --> O
  L -- No --> E

Each beast represents a task list with multiple subtasks. For example, the "Socktopus" beast could have up to 8 subtasks representing different sock-related chores:

1. Collect dirty socks
2. Put socks in hamper
3. Sort socks by color
4. Wash socks
5. Dry socks
6. Match sock pairs
7. Fold clean socks
8. Put away clean socks

• When a user decides to tackle a task, they enter "Battle Mode"
• The app transitions to a battle screen with:
  • Custom background themed to the task/beast
  • Battle music to set the mood
  • Visual representation of the beast (e.g., Socktopus)
  • Player's character/avatar

• Both player and beast have HP (Health Points)
• A turn gauge fills up over time (similar to ATB system in Final Fantasy)
• When the turn gauge is full, it's either the player's or beast's turn

• When it's the beast's turn, it attacks the player automatically
• Player loses some HP (representing the mental/physical cost of procrastination)
• Different beasts could have different attack patterns and damage amounts
• If player HP reaches zero, they lose the battle (temporary timeout from tasks)

During the player's turn, they can choose from:

• Player selects which subtask to complete
• A timer starts to complete the real-world task
• Once the subtask is done, that "part" of the beast is damaged
• If all subtasks are completed, the beast is defeated
• Each completed subtask could visually change the beast (e.g., removing a tentacle from the Socktopus)

• Player can use consumable items gained through previous victories
• Items could provide effects such as:
  • Healing potions to restore HP
  • Power-ups to make tasks easier/faster
  • Time extensions
  • Special abilities

• Player can choose to flee the battle
• Running comes with a penalty (HP loss)
• Task remains incomplete and beast will be encountered again later

• Defeating beasts (completing task lists) gives rewards:
  • XP (Experience Points) for leveling up
  • GP (Gold Points) for buying items or customizations
  • AP (Ability Points) for accessing special abilities
  • Special items
  • Achievement badges

• Each "attack" (subtask) has a timer to encourage task completion
• Timer length could vary based on estimated task difficulty
• Optional: Time extensions could be awarded or purchased
• Timer acts as motivation to complete real-world tasks promptly

• If player loses all HP, they enter a "recovery period" in the Hospital
• All MP is also depleted when HP reaches zero
• This represents taking a break before tackling tasks again
• Recovery period could be shortened with items or by completing smaller tasks

• As player levels up, beast difficulty could increase
• Higher-level beasts could have:
  • More complex subtask lists
  • Higher HP/damage
  • Special abilities that make tasks more challenging

• Battle Screen Layout: Split between beast visualization, player character, action buttons, and subtask list
• Beast Visualization: Each beast should have multiple visual states representing damage as subtasks are completed
• Turn Gauge: Visual indicator of turn progress (similar to ATB bar in Final Fantasy)
• HP Bars: Visual representation of both player and beast health
• Subtask Selection: Interactive elements showing which parts of the beast can be "attacked" (which subtasks can be done)

interface Beast {
  id: string;
  name: string;
  description: string;
  type: string; // Category of task (cleaning, work, etc.)
  hp: number;
  attackPower: number;
  background: string; // Background image path
  music: string; // Battle music path
  visualStates: string[]; // Array of images showing beast in various damaged states
  subtasks: Subtask[];
}

interface Subtask {
  id: string;
  name: string;
  description: string;
  estimatedTimeMinutes: number;
  completed: boolean;
  targetBodyPart?: string; // Optional: which part of the beast this affects visually
}

• Allow character class abilities to affect battle mechanics
• For example:
  • Mage: Reduce timer requirements for certain task types
  • Warrior: Take less HP damage from beast attacks
  • Rogue: Higher chance of critical success on tasks (bonus rewards)
  • Healer: Faster HP recovery between battles

• Party Battles: Allow friends to join forces on particularly large tasks
• Beast Trading Cards: Collect cards of defeated beasts for your collection
• Leaderboards: Show who has defeated the most beasts in various categories

• Allow users to create custom beasts with their own tasks
• Auto-generate beast difficulty based on:
  • Number of subtasks
  • Estimated time for completion
  • User-defined priority level

• Ensure task difficulty matches appropriate in-game challenge
• Make HP loss meaningful but not punishing
• Create a rewarding gameplay loop that reinforces real-world task completion