2D6-Dungeon/Planning/PROJECT_PLAN.md

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