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.