# 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](./battleground-design.md).

---

## 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:

```typescript
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:
1. Beast becomes **Active** in player's portal
2. If player ignores → Beast attacks (HP loss)
3. 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

1. Player selects **Attack**
2. Beast's checklist appears
3. Completing each item = dealing damage
4. 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

1. **Enter Dungeon** → Timer starts
2. **Navigate Rooms** → Explore, find loot
3. **Encounter Beasts** → Battle or flee
4. **Reach Boss Room** → Final challenge
5. **Complete Dungeon** → Major rewards

---

## 5. Engine Architecture

The battle engine is not under `src/lib/engine/`. The battle service is in `src/lib/services/battle/` (`BattleService.ts`, `BestiaryService.ts`), and the battle screen is mapped in [Battle Field Architecture](./Battle-Field-Architecture.md).

---

## Related Documentation

- [Battleground Design](./battleground-design.md) - UI/Visual design
- [Battle Field Architecture](./Battle-Field-Architecture.md) - Implementation map of the battle screen
- [Hometown](./Hometown.md) - Hospital, Shop, etc.
- [Roadmap](./Roadmap.md) - Project progress