ai_ops2/.app_factory/claude_home/.claude/plans/snug-tumbling-sun.md

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:

  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():

  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.