# Cattopia: Hero, Parrot, Pirate Ship & Level 2

## Context
The refactoring to PixiJS/GSAP/Vite/ES6 modules is complete. Now we're adding new gameplay: a player-controlled Hero (auto-move + click-to-attack), a pet Parrot companion, both fighting alongside cats in all levels. After defeating the Blood Wolf (boss 5), a pirate ship transition leads to Level 2 where skeleton rats replace mice and the final boss — Lord of the Rat Dead — summons skeleton rats.

## Game Flow (Updated)

```
Intro → Creator (cats + hero + parrot) → Level 1 (hunt mice → 5 bosses)
  → Pirate Ship Transition → Level 2 (hunt skeleton rats → Lord of the Rat Dead)
  → Victory
```

## New Files

```
src/
  entities/
    Hero.js                 (auto-move AI + click-attack, stats, XP/leveling)
    Parrot.js               (follows hero, auto-attacks, stats)
    SkeletonRat.js          (Level 2 prey — tougher than Mouse, bone visual)
  renderers/
    HeroRenderer.js         (dark green hoodie, emerald knife, legs, attack anim)
    ParrotRenderer.js       (colorful bird body, flapping wings, color-customizable)
    SkeletonRatRenderer.js  (bone-colored rat with skeletal details)
    PirateShipRenderer.js   (ship hull, mast, sails, water — used by transition scene)
  scenes/
    PirateShipScene.js      (boarding animation: cats/hero/parrot walk onto ship, ship sails off, GSAP transition)
```

## Modified Files

| File | Changes |
|---|---|
| `src/constants.js` | Add `LEVEL_2_BOSS_DEF`, `SKELETON_RAT_GOAL`, new game phases (`SHIP_TRANSITION`) |
| `src/state/GameState.js` | Add `hero`, `parrot`, `skeletonRats[]`, `currentLevel` (1 or 2) |
| `src/scenes/CreatorScene.js` | Add hero creator section (name + color) and parrot creator section (name + color) |
| `src/scenes/GameScene.js` | Integrate hero + parrot into update/render loops, handle click-to-attack, Level 2 skeleton rat logic, Lord of the Rat Dead boss |
| `src/scenes/VictoryScene.js` | Include hero + parrot in final scoreboard |
| `src/main.js` | Register new PirateShipScene |
| `index.html` | Add hero + parrot creator DOM elements |
| `styles/style.css` | Styles for hero/parrot creator sections |

---

## Phase 1: Constants, State & Entity Classes

### 1a. Update `src/constants.js`
- Add `SHIP_TRANSITION` to `GAME_PHASES`
- Add Level 2 constants:
  ```js
  export const SKELETON_RAT_GOAL = 25;
  export const LEVEL_2_BOSS_DEF = {
    name: 'Lord of the Rat Dead',
    icon: '💀🐀',
    color: '#2a1a2a',
    loot: { name: "Necro Crown", icon: '💀👑', stats: { hunting: 12, speed: 8, agility: 8, stealth: 8 } },
    summonInterval: 300,   // frames between skeleton rat summons
    hpPerAlly: 250         // HP per cat+hero
  };
  ```

### 1b. Update `src/state/GameState.js`
- Add to `reset()`:
  ```js
  this.hero = null;
  this.parrot = null;
  this.skeletonRats = [];
  this.currentLevel = 1;
  ```

### 1c. Create `src/entities/Hero.js`
- Similar structure to `Cat.js` — has name, color, stats, level, xp, gear
- `updateHunt(targets, bounds)`: auto-move AI chases nearest mouse/skeleton rat (same pattern as Cat.updateHunt)
- `updateBossChase(boss)`: auto-move toward boss (same pattern as Cat.updateBossChase)
- `triggerAttack(enemies, boss)`: called on player click — finds nearest enemy within ~80px range and deals bonus damage burst. Returns `{ type: 'attackHit', target, damage }` or null
- `applyPhysics(bounds)`: identical to Cat
- Distinguishing stats: higher base hunting, lower stealth (knife fighter)

### 1d. Create `src/entities/Parrot.js`
- Has name, color, stats (auto-generated like cats), level, xp
- `update(hero, targets, boss, bounds)`: follows hero loosely (offset position), periodically attacks nearest enemy within range (every ~90 frames). Returns action: `{ type: 'peck', target, damage }` or null
- `applyPhysics(bounds)`: same clamping pattern
- Smaller hitbox, faster movement, lower damage than hero

### 1e. Create `src/entities/SkeletonRat.js`
- Based on `Mouse.js` but tougher: `hp` field (takes 2-3 hits to kill), slightly faster
- `update(hunters, bounds)`: flee AI like Mouse but with more erratic movement
- `alive` flag set to false when hp <= 0

## Phase 2: Renderers

### 2a. Create `src/renderers/HeroRenderer.js`
- Follow `CatRenderer.js` pooling pattern (single hero, but consistent API)
- Draw: human-ish figure (slightly taller than cats), dark green hoodie body, hood, legs (animated walk cycle), arms
- Emerald knife: green-tinted blade held in right hand, glows on attack
- Attack animation: knife slash arc (brief GSAP or frame-based flash)
- Name tag above head like cats

### 2b. Create `src/renderers/ParrotRenderer.js`
- Colorful bird body using user-selected color as base
- Flapping wings (oscillating wing angle per frame)
- Small beak, tail feathers, beady eyes
- Name tag (smaller than hero/cat)

### 2c. Create `src/renderers/SkeletonRatRenderer.js`
- Based on `MouseRenderer.js` but bone-white/gray color palette
- Visible ribs/bones on body, hollow eye sockets
- HP bar above (since they take multiple hits)
- Scared state: bones rattle (slight shake)

### 2d. Create `src/renderers/PirateShipRenderer.js`
- Ship hull (brown, curved), mast with sails, jolly roger flag
- Water beneath (blue waves, animated)
- Used by PirateShipScene for the transition

## Phase 3: Creator Scene Updates

### 3a. Update `index.html`
- Inside `#creator-screen > .creator-panel`, add after cat creation form:
  - Hero section: name input + color picker (dark green hoodie preview + alternate colors)
  - Parrot section: name input + color picker (red/blue/green/yellow parrot previews)
  - Reorder: cats first, then hero, then parrot, then "Start the Hunt!" button

### 3b. Update `src/scenes/CreatorScene.js`
- Add hero creation logic: name + color → `new Hero({...})` → `gameState.hero = hero`
- Add parrot creation logic: name + color → `new Parrot({...})` → `gameState.parrot = parrot`
- Stats reveal for hero and parrot (same animated bar pattern as cats)
- Require at least 1 cat + hero + parrot before "Start the Hunt!" enables
- Add hero/parrot to roster display

### 3c. Update `styles/style.css`
- Styles for hero/parrot creator sections, color picker buttons, preview icons

## Phase 4: GameScene Integration (Level 1 + Level 2)

### 4a. Add hero to update loop (`GameScene.js`)
- Hunt phase: `hero.updateHunt(currentTargets, bounds)` where `currentTargets` = mice (L1) or skeletonRats (L2)
- Boss phase: `hero.updateBossChase(boss)`
- Catch/damage checks same pattern as cats but with hero's stats
- Click handler on PixiJS container: `this.container.on('pointerdown', (e) => this._onHeroAttack(e))`
- `_onHeroAttack(e)`: call `hero.triggerAttack()` to find and damage nearest enemy

### 4b. Add parrot to update loop
- Every frame: `parrot.update(hero, targets, boss, bounds)`
- Process returned peck actions: apply damage, spawn hit particles, award XP to parrot

### 4c. Add renderers to GameScene
- Create `HeroRenderer`, `ParrotRenderer`, `SkeletonRatRenderer` instances
- Add containers in render order (hero between cats and giga dog, parrot near hero)
- Sync in `render()`: `this.heroRenderer.sync(gameState.hero)`, `this.parrotRenderer.sync(gameState.parrot)`, `this.skeletonRatRenderer.sync(gameState.skeletonRats)`

### 4d. Level 2 hunt logic
- When `gameState.currentLevel === 2`:
  - "Add Mouse" buttons become "Add Skeleton Rat" buttons
  - Mice array unused; skeleton rats array used instead
  - Catch = skeleton rat HP reduced; when HP <= 0, award XP + increment totalCaught
  - Goal: `SKELETON_RAT_GOAL` skeleton rats killed triggers Lord of the Rat Dead

### 4e. Lord of the Rat Dead boss
- Reuse `Boss.js` entity with a new defIndex (6) or create specialized subclass
- **Approach**: extend `BOSS_DEFS` array with the Lord entry at index 5 (only used in Level 2)
- Boss mechanics: standard movement + periodically summons skeleton rats (using `summonInterval` from def)
- On defeat: transition to victory (`sceneManager.switchTo('victory')`)

### 4f. Update `_defeatBoss()` flow
- After Blood Wolf defeat (boss index 4, Level 1): instead of victory, set `gameState.currentLevel = 2` and `sceneManager.switchTo('ship')`
- After Lord of the Rat Dead defeat (Level 2): go to victory

## Phase 5: Pirate Ship Transition Scene

### 5a. Create `src/scenes/PirateShipScene.js`
- PixiJS scene with PirateShipRenderer for the ship + water background
- GSAP timeline:
  1. Show "The seas await..." text overlay (fade in)
  2. Cats, hero, and parrot walk/fly from left toward ship (small sprites moving right)
  3. Board the ship (sprites move onto deck)
  4. Ship sails right, screen fades to black
  5. Switch to GameScene with Level 2 state
- Duration: ~4-5 seconds total

### 5b. Update `src/main.js`
- Import and register PirateShipScene: `sceneManager.register('ship', pirateShipScene)`

### 5c. Update GameScene.enter()
- Check `gameState.currentLevel`:
  - Level 1: current behavior (forest, mice)
  - Level 2: reset totalCaught, update HUD text ("Skeleton Rats" instead of "Mice"), different forest theme (darker/undead aesthetic via ForestRenderer flag), spawn skeleton rats

### 5d. Optional: ForestRenderer Level 2 theme
- When `currentLevel === 2`: darker sky gradient, dead/gray trees, eerie green ground glow
- Reuse blood moon infrastructure but with green/purple tint instead of red

## Phase 6: Victory Scene Updates

### 6a. Update `VictoryScene.js`
- Include hero and parrot in final scoreboard alongside cats
- Hero gets a special "Hero" badge, parrot gets "Companion" badge
- MVP calculation includes hero (hero.catches or boss damage dealt)

## Phase 7: Polish & Cleanup

- Update SpawnSystem with `spawnSkeletonRats()` method
- Update `_updateHUD()` to show level indicator ("Level 1" / "Level 2")
- Update `_updateScoreboard()` to include hero + parrot entries
- Ensure Giga Dog works in both levels
- Update README with new features

---

## Verification

After each phase, verify with `npm run dev`:
1. **Creator**: Can create cats, hero (name + color), and parrot (name + color). All show in roster with stats.
2. **Level 1**: Hero auto-moves and chases mice. Click near hero attacks. Parrot follows hero and pecks enemies. All 5 bosses work.
3. **Ship Transition**: After Blood Wolf defeat, pirate ship scene plays, transitions to Level 2.
4. **Level 2**: Skeleton rats spawn instead of mice. Hunt → Lord of the Rat Dead boss. Boss summons skeleton rats. Defeating boss triggers victory.
5. **Victory**: Scoreboard shows cats, hero, and parrot. MVP includes all.
6. **Full build**: `npm run build` succeeds, Docker still works.