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

Battle System Engine

This document covers the game engine mechanics behind battles - enemy spawning, HP system, and dungeon raids. For UI/visual design, see Battleground Design.

Overview

The battle system transforms household chores into RPG-style combat encounters:

Real World	Game World
Chore task	Enemy (Beast)
Task checklist	Enemy HP / Damage
Completing tasks	"Attacking" the enemy
Ignoring chores	Taking damage (HP loss)
Deep cleaning session	Dungeon Raid

1. Enemy Spawning System

Beasts = Chores

Enemies are created by Game Masters (parents) via the Bestiary page. Each Beast has:

interface Beast {
  id: string;
  name: string;             // "Socktopus"
  checklist: string[];      // ["Sort socks", "Match pairs", "Put away"]
  element?: BeastElement;   // 'water' | 'fire' | 'earth' | 'wind'
  spawn: SpawnSchedule;
}

interface SpawnSchedule {
  frequency: 'daily' | 'weekly' | 'interval';
  times?: string[];         // ["08:00", "18:00"] - spawn times
  daysOfWeek?: number[];    // [1,3,5] for Mon/Wed/Fri
  intervalDays?: number;    // Every N days
}

Spawn Trigger

When the scheduled time arrives:

Beast becomes Active in player's portal
If player ignores → Beast attacks (HP loss)
If player engages → Battle begins

Running Away

Player can Run during battles
Next encounter: Beast attacks FIRST
Creates urgency to complete tasks

2. HP System

HP = Chore Health

HP represents how well you're keeping up with responsibilities:

Full HP: All chores complete, on schedule
Low HP: Tasks piling up, beasts attacking
0 HP: Game Over state (consequences TBD)

HP Drain

Condition	HP Effect
Beast attacks (overdue task)	-X HP per tick
Multiple active beasts	Faster HP drain
Running from battle	Beast attacks on next encounter
Completing beast	HP restored or maintained

Recovery

Potions: Purchased with GP
Hospital: Hometown recovery zone
Completing tasks: Primary HP maintenance

3. Combat Flow

Turn-Based Combat (Earthbound Style)

┌─────────────────────────────────────────┐
│  [Animated Parallax Background]         │
│                                         │
│     🐙 Socktopus                        │
│         HP ████████░░ 80%               │
│                                         │
│  ┌─────────────────────────────────┐    │
│  │ COUNTDOWN TIMER: 2:45           │    │
│  └─────────────────────────────────┘    │
│                                         │
│  [DEFEND] [RUN] [ATTACK] [ABILITIES]    │
└─────────────────────────────────────────┘

Actions

Action	Effect
Attack	Opens task checklist - completing items = dealing damage
Defend	Reduces incoming damage temporarily
Run	Escape, but beast attacks first next time
Abilities	Special moves (earned/purchased)

Defeating a Beast

Player selects Attack
Beast's checklist appears
Completing each item = dealing damage
All items complete = Beast defeated → XP + GP rewards

4. Dungeons = Raid Cleaning

Dungeons are hyper-focused cleaning sessions (1-2 hour deep cleans).

Concept

The House is the dungeon environment
Navigate through rooms, encountering beasts
Timed challenge with rewards

Element Themes

Theme	Associated Chores
🌊 Water	Dishes, laundry, mopping, bathrooms
🔥 Fire	Kitchen, cooking cleanup, oven cleaning
🌍 Earth	Yard work, gardening, sweeping
💨 Wind	Dusting, vacuuming, air freshening

Temple & Dungeon Engine

For deep dives into how dungeons are built using a DSL approach, see the Temple-System documentation.

Dungeon Flow

Enter Dungeon → Timer starts
Navigate Rooms → Explore, find loot
Encounter Beasts → Battle or flee
Reach Boss Room → Final challenge
Complete Dungeon → Major rewards

5. Engine Architecture

src/lib/engine/
├── battle/
│   ├── BattleEngine.ts      # Core turn-based logic
│   ├── BattleState.ts       # Reactive battle state
│   ├── EnemySpawner.ts      # Schedule-based spawning
│   └── CombatActions.ts     # Defend, Run, Attack handlers
├── dungeons/                # The Temple Engine (DSL based)
│   ├── roomFactory.ts       # Room instance hydration
│   ├── roomTypes.ts         # The Palette (4-character tokens)
│   └── windTemple.ts        # Static configuration
├── temples/                 # Existing temple definitions
└── systems/
    ├── HealthSystem.ts      # HP management
    ├── RewardSystem.ts      # XP, GP distribution
    └── ScheduleSystem.ts    # Chore → Beast spawn bridge