zelda-dungeon/PLAN.md

Zelda Dungeon Expansion — Plan Document

Goal

Expand from 3-room prototype to 100 procedurally-generated dungeons, each with 20-100 rooms, 20+ enemy types, 12 weapons, 100 unique bosses, dungeon selection menu, save system, and sequential progression.

Target: Browser-First

• Runs in a standard web browser (no Electron dependency for testing)
• Electron wrapper added later via existing main.js / preload.js
• Playtesting via npx serve or simple HTTP server

---

Architecture

File Structure

zelda-dungeon/
├── index.html              ← Main entry point (browser), loads all scripts
├── main.js                 ← Electron main process (untouched for now)
├── preload.js              ← Electron IPC bridge (updated for save data)
├── package.json            ← Add "dev" script for browser testing
│
├── src/
│   ├── core/
│   │   ├── constants.js    ← TILE, COLS, ROWS, tile types, timing, COLORS
│   │   ├── rng.js          ← Seeded RNG (mulberry32) for reproducibility
│   │   └── utils.js        ← Helper functions (createBorderLayout, drawHeart, etc.)
│   │
│   ├── data/
│   │   ├── themes.js       ← Dungeon themes (Forest, Desert, Mountain, etc.) with colors
│   │   ├── dungeons.js     ← 100 dungeon definitions (name, theme, difficulty, seed, room count)
│   │   ├── enemies.js      ← 22 enemy type definitions (stats, AI, draw functions)
│   │   ├── bosses.js       ← 100 boss definitions (one per dungeon)
│   │   ├── weapons.js      ← 12 weapon definitions (damage, range, effects, draw functions)
│   │   └── items.js        ← Consumables (potions, heart pieces, arrows, bombs, keys)
│   │
│   ├── generator/
│   │   ├── dungeon.js      ← Generates full dungeon from definition (rooms + connections)
│   │   ├── rooms.js        ← Generates individual rooms (layout, enemies, items, puzzles)
│   │   ├── puzzles.js      ← Puzzle generation (rock-push, levers, keys, switches)
│   │   └── placement.js    ← Placement logic (enemy/item density by difficulty tier)
│   │
│   ├── game/
│   │   ├── state.js        ← Game state management (player, room, dungeon, menus)
│   │   ├── combat.js       ← Attack resolution, damage, effects
│   │   ├── movement.js     ← Player movement, rock pushing, exit handling
│   │   ├── ai.js           ← Enemy AI (chase, patrol, shoot, special behaviors)
│   │   ├── items.js        ← Item pickup, chest opening, inventory management
│   │   └── transitions.js  ← Room transitions, screen fades
│   │
│   ├── rendering/
│   │   ├── renderer.js     ← Canvas drawing (floor, walls, torches, entities)
│   │   ├── draw-enemies.js ← Per-enemy-type draw functions
│   │   ├── draw-bosses.js  ← Boss draw functions (larger, multi-phase visuals)
│   │   ├── draw-weapons.js ← Weapon draw functions
│   │   ├── hud.js          ← HUD rendering (hearts, weapon, ammo, room info)
│   │   └── effects.js      ← Particles, hit flashes, screen transitions
│   │
│   ├── input/
│   │   ├── keyboard.js     ← Key state tracking, action binding
│   │   └── actions.js      ← Action definitions (move, attack, use item, select)
│   │
│   ├── menu/
│   │   ├── title-screen.js ← Title screen rendering + interaction
│   │   ├── dungeon-select.js ← Dungeon grid, filtering, info panel
│   │   ├── hud-overlay.js  ← In-game menu (inventory, weapon switch)
│   │   └── screens.js      ← Death/win/completion screens
│   │
│   ├── save/
│   │   └── save.js         ← localStorage save/load, progress tracking
│   │
│   └── app.js              ← Main bootstrap (init, game loop, screen switching)

---

Implementation Phases

Phase 1: Core Infrastructure

• Create directory structure
• constants.js — All shared constants (TILE, COLS, ROWS, COLORS, timing)
• rng.js — Seeded PRNG (mulberry32)
• utils.js — Reusable helpers (createBorderLayout, drawHeart, DIRS, etc.)
• index.html — New HTML that loads all scripts, canvas, menu div
• app.js — Bootstrap: init → title screen → game loop
• Validate: Open in browser, see title screen

Phase 2: Data Definitions

• themes.js — 8 themes (Forest, Desert, Mountain, Underground, Ocean, Sky, Shadow, Final) with color palettes
• dungeons.js — 100 dungeon definitions (generated procedurally from themes)
• enemies.js — 22 enemy types with stats, behaviors, colors, draw functions
• weapons.js — 12 weapons with damage, range, cooldown, effects
• bosses.js — 100 bosses (one per dungeon), template-based with variations
• items.js — Consumables definitions
• Validate: Data files load without errors, can inspect in console

Phase 3: Procedural Generation

• generator/dungeon.js — BSP/DFS room layout generation from seed
• generator/rooms.js — Room type assignment, layout generation
• generator/puzzles.js — Puzzle generation (rock-push, levers, keys)
• generator/placement.js — Enemy/item placement by difficulty tier
• Validate: Generate dungeon #1, inspect rooms, verify connectivity

Phase 4: Game Engine

• game/state.js — Game state (player, current room, inventory, progress)
• game/movement.js — Player movement, rock pushing, collision
• game/combat.js — Attack resolution, weapon effects, damage
• game/ai.js — Enemy AI (chase, patrol, ranged, special)
• game/items.js — Chest opening, item pickup, inventory
• game/transitions.js — Room transitions, screen fades
• input/keyboard.js — Key tracking, action dispatch
• input/actions.js — Action definitions
• Validate: Play through generated dungeon #1 in browser

Phase 5: Rendering

• rendering/renderer.js — Floor, walls, torches (theme-colored)
• rendering/draw-enemies.js — All 22 enemy draw functions
• rendering/draw-bosses.js — Boss draw functions
• rendering/draw-weapons.js — Weapon visual indicators
• rendering/hud.js — Hearts, weapon icon, ammo, room counter
• rendering/effects.js — Particles, hit flash, screen transitions
• Validate: Visual rendering looks correct for all entity types

Phase 6: Menu System

• menu/title-screen.js — Title, start button, controls
• menu/dungeon-select.js — 10x10 grid, theme filter, difficulty, lock status
• menu/screens.js — Death, win, dungeon completion screens
• Validate: Navigate menus, select dungeon, enter game

Phase 7: Save System

• save/save.js — localStorage persistence
• Save format: { completedDungeons: [], weapons: [], heartPieces: N, totalRooms: N }
• Auto-save on dungeon completion
• Resume functionality
• Validate: Complete dungeon → close browser → reopen → progress saved

Phase 8: Integration & Polish

• Connect all systems end-to-end
• Playtest first 10 dungeons
• Balance difficulty curve
• Screen transition effects
• Error handling, edge cases
• Validate: Full playthrough dungeon #1 → #10

Phase 9: Electron Integration (Later)

• Update preload.js — expose save/load IPC
• Update main.js — if needed
• Validate: npm start works in Electron

---

Technical Decisions

Seeded RNG

• Mulberry32 algorithm: fast, deterministic, good quality for game generation
• Same seed → same dungeon every time
• Seeds stored in dungeons.js definitions

Room Generation Algorithm

• Randomized DFS (depth-first search) for organic-feeling dungeons
• Room sizes: 5x5 to 12x12 tiles
• Corridors connect rooms (1-tile wide, L-shaped)
• Room types assigned by dungeon phase (early/mid/late)

Difficulty Scaling

• Dungeon difficulty: 1-10 (based on index)
• Room count: 20 (difficulty 1-2) → 100 (difficulty 10)
• Enemy density: 0-1 per room (easy) → 2-4 per room (hard)
• Enemy types unlocked by difficulty tier
• Boss HP scales with dungeon difficulty

State Management

• Single game object with nested state
• Screen states: TITLE, DUNGEON_SELECT, PLAYING, DEAD, DUNGEON_COMPLETE, GAME_COMPLETE
• Room data regenerated from seed on entry (no permanent room state)
• Player state persists across rooms within a dungeon
• Inventory persists across dungeons

Combat System

• Weapon-based damage (varies by weapon type)
• Attack cooldowns per weapon
• Ranged weapons (bow, slingshot, rods) have projectile system
• Special effects: fire (AoE), ice (freeze), boomerang (return), bombs (destroy walls)
• Enemy HP, defense, attack damage, attack cooldown

Enemy AI Behaviors

• chase: Pathfind toward player (existing behavior)
• patrol: Wander predefined path
• ranged: Shoot projectiles at player
• stationary: Activate on proximity
• charge: Rush at player in straight line
• teleport: Random teleportation
• explode: Explode on contact or timer

---

Playtesting Hooks

Debug Mode

• ?debug=1 URL parameter enables debug overlay
• Shows: room grid, collision boxes, AI state, generation seed
• F1 toggles debug overlay during gameplay
• F2 forces next room (skip puzzles)
• F3 god mode (invincible)
• F4 spawn debug enemy at player position

Console API

• generateDungeon(id) — Generate and inspect any dungeon
• spawnEnemy(type) — Spawn enemy at player position
• giveWeapon(name) — Add weapon to inventory
• teleportToRoom(idx) — Jump to room by index
• dumpState() — Print full game state to console

Performance

• Room rendering only draws visible tiles + buffer
• Enemy AI updates throttled by type
• Particle system capped at 100 particles

---

Browser Testing

• npm run dev → npx serve . for local HTTP server
• Open http://localhost:3000 in browser
• npm start → Electron app (for later)