✨feature: Initial commit

Planning/PROJECT_PLAN.md

@@ -0,0 +1,424 @@
+# 2D6 Dungeon Web Adaptation Plan
+
+## Goal
+Build a web-based version of **2D6 Dungeon** that preserves the solo dungeon-crawl loop from the core rules while removing paper bookkeeping and table lookups.
+
+This plan is based on the core systems described in:
+
+- `2D6 Dungeon - Core Rules.pdf`, especially:
+  - character creation and stats
+  - dungeon room generation
+  - encounters and combat
+  - treasure, XP, levelling, and town visits
+
+## Important Constraint
+The Core Rules repeatedly depend on a separate **Tables Codex** for room tables, creature data, item tables, scrolls, treasures, and many event outcomes. That means the project should be split into:
+
+1. **Rules engine and UI**
+2. **Game content/data entry**
+
+Do not block the app build on full content entry. Use placeholder data for development, then swap in the real tables.
+
+## Product Vision
+The web version should feel like:
+
+- a guided solo campaign tracker
+- a map-and-journal interface
+- a fast combat assistant
+- a persistent progression game with saves between dungeon runs
+
+The app should handle:
+
+- dice rolling and modifiers
+- map generation and room state
+- combat flow
+- inventory and item usage
+- XP, levelling, HP, conditions, and favour
+- leaving the dungeon and returning to town
+- saving and resuming long campaigns
+
+## Suggested MVP Scope
+Build the first playable version around **Level 1 only** plus **town return/save flow**.
+
+MVP includes:
+
+- one adventurer
+- character creation
+- map generation
+- room reveal flow
+- encounters
+- combat with manoeuvres, shift, fatigue, interrupts, armour deflection
+- inventory, potions, scrolls, rations
+- XP and levelling
+- leave dungeon and visit town
+- save/load run
+
+MVP excludes:
+
+- all 10 levels
+- full item catalog
+- full god/favour content
+- every special room and narrative edge case
+- expansions and alternate dungeon ancestries
+
+## Recommended Build Order
+
+### Phase 1: Nail down the source material
+Outcome: a usable design spec instead of rulebook ambiguity.
+
+Steps:
+
+1. Extract the game systems from the Core Rules into a structured design doc.
+2. List every referenced external table that lives in the Tables Codex.
+3. Build a spreadsheet or JSON checklist for:
+   - room tables
+   - small room tables
+   - creature cards
+   - armour
+   - manoeuvres
+   - scrolls
+   - potions
+   - treasures
+   - market tables
+   - tavern and temple tables
+4. Mark each rule as one of:
+   - required for MVP
+   - defer until post-MVP
+   - content only
+5. Decide where the web version will intentionally streamline play without changing balance.
+
+Definition of done:
+
+- one concise design spec exists
+- one content inventory exists
+- MVP rule boundaries are agreed
+
+### Phase 2: Choose the technical foundation
+Outcome: a stack that supports a state-heavy single-player game.
+
+Recommended stack:
+
+- Frontend: React + TypeScript
+- App framework: Next.js or Vite
+- Styling: Tailwind or CSS modules
+- State: Zustand or Redux Toolkit
+- Data validation: Zod
+- Persistence: browser local storage first, optional cloud saves later
+- Testing: Vitest + React Testing Library
+
+Suggested architecture:
+
+- `rules/` for pure game logic
+- `data/` for encoded tables and cards
+- `state/` for campaign/run state
+- `ui/` for screens and panels
+
+Definition of done:
+
+- repo created
+- TypeScript configured
+- state and data folder structure in place
+
+### Phase 3: Model the game data
+Outcome: rules can run against structured content instead of ad hoc text.
+
+Create schemas for:
+
+- adventurer
+- weapon
+- manoeuvre
+- armour
+- room template
+- creature
+- item
+- potion
+- scroll
+- rune
+- herb
+- god favour
+- town action
+- dungeon level state
+- room state
+- combat state
+
+Key rule-specific fields to support:
+
+- D6, 2D6, and D66 rolls
+- primary vs secondary die
+- modified ranges rule
+- exact strike
+- shift points
+- discipline and precision modifiers
+- interrupt matches
+- fatigue die
+- unique room rules
+- room reveal percentage rules
+
+Definition of done:
+
+- all MVP entities have typed schemas
+- sample Level 1 data can be loaded without UI
+
+### Phase 4: Build the rules engine
+Outcome: the game can run in code before the interface is polished.
+
+Implement in this order:
+
+1. Dice utilities
+   - D3
+   - D6
+   - 2D6
+   - D66
+   - modifier clamping
+2. Character creation
+   - starting stats
+   - starting weapon/manoeuvres
+   - starting armour
+   - starting scroll/potion/items
+3. Dungeon generation
+   - outer boundary
+   - entrance room
+   - room dimensions
+   - exits
+   - small room detection
+   - last room / stairs logic
+   - secret door fallback
+4. Room encounter resolution
+   - identify room
+   - mark unique rooms
+   - resolve exits
+   - queue encounters and interactables
+5. Combat engine
+   - initiative flow
+   - manoeuvre matching
+   - shifting
+   - exact strike
+   - interrupt reduction
+   - armour deflection
+   - fatigue die progression
+   - multiple enemies
+   - thrown weapons and potion bombs
+6. Rewards and progression
+   - XP gain
+   - levelling
+   - treasure
+   - inventory capacity
+   - HP rules
+7. Dungeon traversal rules
+   - backtracking
+   - rations between levels
+   - leaving the dungeon
+8. Town loop
+   - market
+   - engraver
+   - herbalist
+   - tavern
+   - temple
+   - town hall
+
+Definition of done:
+
+- a text-mode test harness can complete a small mock dungeon
+- the engine supports save/load state
+
+### Phase 5: Build the first playable UI
+Outcome: a user can complete a short run entirely in the browser.
+
+Recommended screens:
+
+1. Start screen
+   - new run
+   - continue run
+2. Character creation
+   - choose name, weapon, armour, starting manoeuvres, starting scroll
+3. Main dungeon screen
+   - map panel
+   - room log
+   - current encounter panel
+   - character sheet sidebar
+4. Combat modal or panel
+   - dice rolled
+   - available shifts
+   - selected manoeuvre
+   - damage calculation
+   - enemy response
+5. Town screen
+   - sell/buy
+   - services
+   - evening choice
+6. Save summary/history
+   - current level
+   - completed levels
+   - inventory and stats
+
+UI priority:
+
+- clarity over visual flourish at first
+- remove manual arithmetic wherever possible
+- keep a visible action log so players can verify the rules
+
+Definition of done:
+
+- one full Level 1 run is playable without touching code
+
+### Phase 6: Add persistence and campaign progression
+Outcome: the app supports the real long-form game structure.
+
+Steps:
+
+1. Save campaign state automatically after each action.
+2. Keep separate records for:
+   - current run
+   - completed dungeon levels
+   - town inventory/storage
+   - discovered permanent upgrades
+3. Add import/export save support as JSON.
+4. Add a run history log for debugging and player trust.
+
+Definition of done:
+
+- browser refresh does not lose progress
+- campaign can resume from town or dungeon
+
+### Phase 7: Expand content safely
+Outcome: the app grows without turning brittle.
+
+Steps:
+
+1. Add the remaining dungeon levels one at a time.
+2. Add full creature card coverage.
+3. Add gods, herbs, runes, potion bombs, and optional rules.
+4. Add side quests and unique room edge cases.
+5. Add tool-assisted content validation to catch broken table links.
+
+Definition of done:
+
+- all core rulebook content used by the web app is encoded and reachable
+
+## Concrete Task List
+
+### Week 1: Pre-production
+
+- Read the Core Rules and produce a short rules summary.
+- Create a missing-content list for the Tables Codex.
+- Decide MVP scope.
+- Choose framework and state library.
+- Set up repo and base TypeScript app.
+
+### Week 2: Data model and utilities
+
+- Create TypeScript types and Zod schemas.
+- Build dice helpers.
+- Build rule helper functions for modifiers and D66 handling.
+- Create sample JSON for one weapon set, a few enemies, and a few rooms.
+
+### Week 3: Dungeon and room flow
+
+- Implement dungeon grid state.
+- Implement room generation.
+- Implement room reveal and exit resolution.
+- Render a simple map view and room log.
+
+### Week 4: Combat
+
+- Implement manoeuvre matching and shift logic.
+- Implement enemy attacks, interrupts, armour deflection, and fatigue.
+- Build the combat UI panel.
+- Add tests for combat edge cases.
+
+### Week 5: Inventory and progression
+
+- Add items, rations, potions, scrolls, and capacity rules.
+- Add XP, levelling, HP updates, and conditions.
+- Add treasure and post-combat rewards.
+
+### Week 6: Town and persistence
+
+- Build leave-dungeon flow.
+- Build market and service screens.
+- Add save/load and autosave.
+- Add campaign summary UI.
+
+### Week 7+: Content expansion
+
+- Enter full Level 1 data.
+- Playtest and fix rule mismatches.
+- Add Level 2 and beyond incrementally.
+
+## Risks To Handle Early
+
+### 1. Missing data source
+The Core Rules alone are not enough for a full digital implementation because they reference the Tables Codex for many outcomes.
+
+Mitigation:
+
+- treat content entry as its own track
+- start with stub tables
+- add a validation layer that checks every table reference exists
+
+### 2. Rules ambiguity
+Some paper-game rules rely on human judgment, especially:
+
+- inventive usage
+- identifying the “last room”
+- map common-sense decisions
+- narrative interpretation of room text
+
+Mitigation:
+
+- make subjective rulings explicit in a digital design doc
+- keep a manual override or “GM ruling” option during development
+
+### 3. Overbuilding too early
+Trying to implement all ten levels and all tables before a playable loop exists will slow the project down.
+
+Mitigation:
+
+- ship Level 1 first
+- use placeholder content where needed
+- prioritize end-to-end playability over completeness
+
+## Testing Strategy
+
+Test the project at three levels:
+
+1. Unit tests
+   - dice logic
+   - modifiers
+   - combat resolution
+   - room generation constraints
+2. Integration tests
+   - create character -> enter dungeon -> resolve room -> fight -> gain loot
+3. Manual playtests
+   - compare digital outcomes against the rulebook
+   - record every mismatch in a balance/rules log
+
+Important test cases:
+
+- D66 primary/secondary ordering
+- exact strike bonus
+- shift usage limits
+- fatigue die progression after round 6
+- multiple enemies
+- levelling during combat
+- leaving and re-entering a level
+- secret door generation when stuck early
+
+## Nice-To-Have Features After MVP
+
+- animated dice
+- mobile-friendly layout
+- codex viewer for room/creature reference
+- optional “assist mode” that explains why a rule fired
+- seeded runs
+- cloud saves
+- campaign analytics
+
+## Best Next Step
+If starting today, do these three things first:
+
+1. Create a `GAME_SPEC.md` summarizing the rules from the PDF.
+2. Create a `content-checklist.json` listing every table/card/data dependency from the Tables Codex.
+3. Scaffold a TypeScript frontend with a pure `rules/` module and implement dice utilities plus a minimal character state.
+
+That gets the project moving quickly without waiting for all game content to be entered.