2D6-Dungeon/Planning/GAME_SPEC.md

# 2D6 Dungeon Game Spec

## Purpose
This document translates the rulebooks into a software-oriented specification for a web-based version of **2D6 Dungeon**.

It is based on:

- `2D6 Dungeon - Core Rules.pdf`
- `2D6 Dungeon - Tables Codex.pdf`

The goal is not to reproduce the books page-for-page. The goal is to define:

- the gameplay loop
- the rules engine responsibilities
- the data/content model
- the app state model
- the MVP boundaries
- the places where digital adaptation decisions are required

## Product Definition
2D6 Dungeon is a **solo dungeon-crawling campaign game** with:

- procedural room generation
- table-driven events
- deterministic combat resolution around dice combinations
- long-term character progression
- repeated dungeon delves separated by town phases

The web version should act as:

- rules engine
- campaign tracker
- character sheet
- dungeon map sheet
- combat assistant
- table resolver

## Design Goals

1. Preserve the core paper-game rules where practical.
2. Remove manual bookkeeping and repeated table lookups.
3. Make game state transparent through logs and visible calculations.
4. Support long-running campaigns with reliable save/resume.
5. Keep rules logic separate from content data.

## Non-Goals For MVP

- full content parity across all 10 levels
- expansion support
- multiplayer
- realtime action gameplay
- heavy audiovisual presentation

## Canonical Gameplay Loop

The top-level loop is:

1. Create or continue an adventurer.
2. Enter a dungeon level.
3. Generate and reveal rooms as exploration advances.
4. Resolve room encounters, creatures, objects, and events.
5. Fight creatures through manoeuvre-based combat.
6. Gain loot, XP, items, conditions, and favour.
7. Continue deeper, or leave the dungeon through an exit shaft.
8. Return to town for selling, buying, services, and preparation.
9. Re-enter the dungeon and continue campaign progress.
10. Complete all 10 levels and claim legendary reward.

## Core Systems

### 1. Dice System

Supported roll types:

- `D3`
- `D6`
- `2D6`
- `D66`

Important rules:

- `D66` uses two distinguishable dice.
- Primary die is the tens digit.
- Secondary die is the ones digit.
- Some systems require preserving both values individually, not just the combined number.
- The **Modified Ranges Rule** clamps modified values to the nearest valid table result when a modifier pushes the result out of range.

Software requirement:

- represent raw dice, modified dice, and combined result separately
- keep roll history for audit/logging

### 2. Adventurer Model

The player controls a single adventurer with:

- name
- level
- XP
- HP
- baseline HP
- Shift
- Discipline
- Precision
- weapon
- manoeuvres
- worn armour
- inventory
- potions
- scrolls
- quest items
- favour points
- temporary statuses
- town storage / loot lockup

Key creation rules from Core Rules:

- starts at Level 1
- starts with 10 HP baseline
- starts with `+2 Shift`, `+1 Discipline`, `0 Precision`
- chooses one main weapon
- chooses starting manoeuvres tied to weapon
- chooses one starting armour piece
- starts with flint and steel, lantern, 3 rations, pouch, wax sealing kit, backpack
- starts with one starting scroll
- starts with one healing potion

### 3. Progression System

The game is a long-form campaign, not a single roguelike run.

Progression includes:

- XP from kills and special actions
- level ups during dungeon exploration
- immediate HP gain on level-up
- unlocking stronger manoeuvres
- accumulating wealth and equipment
- clearing dungeon levels over multiple visits
- completing side quests
- earning legendary status after completing all 10 levels

Software requirement:

- campaign progress and run progress must be stored separately

### 4. Dungeon Structure

The main dungeon consists of 10 levels.

From the Core Rules and Tables Codex:

- Level 1: The Entry
- Level 2: The Domain
- Level 3: The Crypt
- Level 4: The Haunted
- Level 5: The Infernal
- Level 6: The Cultist Den
- Level 7: The Menagerie
- Level 8: The Monster Maze
- Level 9: The Cursed
- Level 10: The Dungeon Lords

Each level has:

- its own room tables
- its own small room table
- its own large room table
- its own exit type table
- level-specific encounter tables
- level-specific thematic content

### 5. Room Generation

Exploration is driven by generating rooms as encountered.

Rules to support:

- dungeon level has an outer boundary
- entrance room is generated with special rules
- other rooms use `D66` dimensions
- doubles may expand room size
- exits are added based on rules and/or exit tables
- small rooms are handled by dedicated small room tables
- large room tables are separate
- the final reachable room gets stairs to next level
- secret door fallback is used if forward progress stalls before enough map reveal
- no erasing map; room state becomes permanent once generated

Digital adaptation requirement:

- store both logical connectivity and rendered geometry
- do not rely on user drawing

### 6. Room Resolution

Once a room is generated, the app resolves:

- room identity from the level room table
- room description / flavor
- encounter instructions
- exits and exit types
- uniqueness constraints
- special unique room percentage gating

Room resolution may trigger:

- combat
- loot tables
- item discovery
- prisoner encounters
- side quests
- environment interactions
- dungeon events

### 7. Combat System

Combat is the most mechanics-heavy system in the game.

Core concepts:

- all encountered enemies are typically hostile
- player generally attacks first
- manoeuvres correspond to exact 2-die combinations
- Shift Points can move dice values up or down
- successful exact strike gives damage bonus
- creatures may have interrupt stats that reduce or alter damage
- armour can deflect damage if dice sets match
- fatigue alters combat over time
- combat supports multiple enemies
- thrown weapons can be used and later recovered or lost
- potion bombs can be used before attacks

Combat must support:

- player attack resolution
- enemy attack resolution
- damage calculation
- interrupt matching
- armour deflection
- fatigue die progression
- prime attack and mishap cases
- special attacks
- death and unconsciousness rules

### 8. Magic System

There are three major magical subsystems:

- scrolls
- potions
- favour of the gods

Scrolls:

- used at the start of combat or outside combat
- require a successful double on `D66`
- Discipline can shift toward a double
- may have dispel doubles
- may invoke failure tables when cast incorrectly

Potions:

- can be used at any point, including combat
- occupy potion capacity
- include healing and other magical effects

Favour:

- tied to specific subterranean gods
- earned through offerings and game events
- spent through a favour roll
- usable in and out of combat
- governed by per-level usage restrictions

### 9. Inventory and Item Systems

The app must track:

- coins by denomination
- gems by type and quality
- armour
- large/heavy items
- regular items
- potions
- scrolls
- herbs
- runes
- quest items
- containers
- worship items

Important capacity rules:

- no hard limit on treasure and small items
- max 10 large/heavy items
- max 5 potions
- max 3 magic scrolls

### 10. Status and Condition Systems

At minimum the engine must support:

- Bloodied
- Soaked
- fever / HP loss from unresolved conditions
- damaged armour
- destroyed armour
- temporary stat bonuses
- temporary effects from town or magic

### 11. Town Phase

When the player exits the dungeon, they can return to town.

Town systems include:

- market buying
- market selling and bartering
- engraver for runes
- herbalist
- tavern
- temple
- town hall arm wrestle
- loot lockup storage
- prisoner liberation rewards

Town is a rules-heavy phase, not just a menu.

### 12. Narrative / Judgment Systems

Some rules rely on interpretation rather than strict table lookup.

Examples:

- inventive usage
- making common-sense map decisions
- deciding the last room in a level
- contextual interactions with room objects

Digital adaptation strategy:

- make the default outcome deterministic where possible
- allow developer-configured override hooks
- keep an action log explaining why a result was chosen

## Content Structure From The Tables Codex

The Tables Codex divides content into major categories.

### Generic Tables

These include:

- armour
- enchanted armour
- failed casting
- gem combinations
- magic items
- magic potions
- magic scrolls
- portcullis levers
- recovery from unconsciousness
- stolen items
- starting armour
- starting scrolls
- gem values
- miscellaneous item values
- weapon manoeuvres

### Random Lists Tables

These include:

- random armour
- empty containers
- gems
- gods
- half ornate items
- herbs
- metal items
- potion lists
- amulets
- magical items
- rings
- wands
- scroll lists
- symbol selection
- worship items
- wrecked items

### Loot Tables

These include:

- bags
- body search
- chests
- pouches
- religious pouches
- religious artifacts
- rubbish piles
- runes
- secret hatches
- sarcophagi
- tables
- tea chests
- urns

### Level Table Groups

The codex is grouped by pairs of dungeon levels:

- Levels 1 and 2
- Levels 3 and 4
- Levels 5 and 6
- Levels 7 and 8
- Levels 9 and 10

Each group includes some combination of:

- prisoner encounter tables
- exit type tables
- interruptions/unexpected tables
- patrol or creature tables
- trap tables
- large room tables
- small room tables
- level room tables
- special level-only tables

### Creature Cards

Creature content begins in the bestiary section and is used continuously by the combat engine.

Each creature card contains at least:

- name
- level
- type
- HP
- XP reward
- Shift
- treasure references
- interrupt stats
- manoeuvres
- mishap/prime attack results
- special attacks
- description

### Optional Tables

Optional tables exist and should be modeled as disabled-by-default modules.

## Proposed Digital Domain Model

### Core Entities

Suggested first-pass entities:

- `Campaign`
- `RunState`
- `Adventurer`
- `DungeonLevelState`
- `RoomState`
- `ExitState`
- `Encounter`
- `CombatState`
- `CreatureInstance`
- `Weapon`
- `Manoeuvre`
- `Armour`
- `Item`
- `Potion`
- `Scroll`
- `Rune`
- `Herb`
- `Quest`
- `God`
- `TownVisit`
- `RollRecord`
- `TableReference`

### Table Data Model

Every table entry should be machine-readable.

Recommended shape:

- `id`
- `tableId`
- `rollMin`
- `rollMax`
- `conditions`
- `resultType`
- `payload`
- `rulesText`

This allows:

- lookup by dice result
- modifier application
- rule-driven dispatch
- UI display using original wording where needed

### Table Reference Model

Many rules point to other tables rather than producing direct outcomes.

Use a normalized reference such as:

- `tableId`
- `rollType`
- `modifierSource`
- `notes`

Examples:

- room directs engine to creature encounter table
- scroll failure points to failed-cast table
- defeated creature points to treasure table

### Roll Record Model

The app should preserve a history of important rolls:

- roll type
- raw dice
- modified dice
- modifiers applied
- final result
- source action
- downstream table used

This is important for trust, debugging, and rules verification.

## State Model

### Campaign State

Persistent across sessions:

- adventurer identity and long-term stats
- completed dungeon levels
- loot lockup contents
- permanent favour or unlocked states
- campaign history

### Run State

Specific to the current active delve:

- current dungeon level
- generated rooms
- current position / current room
- discovered exits
- unresolved encounters
- active inventory carried on run
- temporary effects
- current HP
- active combat

### Room State

Each room needs:

- coordinates / geometry
- room table result
- room type
- room description
- exits
- discovered status
- cleared status
- uniqueness flags
- generated encounters
- placed objects / interactables
- notes and markers

### Combat State

Combat requires:

- combatants
- turn / round number
- fatigue die value
- current attack actor
- current dice roll
- available shift
- selected manoeuvre
- damage breakdown
- interrupt events
- armour deflection events
- pending special effects

## Rules Engine Boundaries

The rules engine should be pure and UI-agnostic where possible.

Good engine responsibilities:

- roll dice
- validate actions
- resolve table lookups
- generate rooms
- resolve combat
- apply rewards and penalties
- advance campaign state

UI responsibilities:

- collect player choices
- show map and character sheet
- show logs and calculations
- present available actions
- render table results nicely

## MVP Definition

The first playable version should cover:

- new game
- character creation
- one active adventurer
- Level 1 only
- room generation
- room identification
- encounter resolution
- creature combat
- loot and XP
- levelling
- inventory tracking
- potions and scrolls
- leave dungeon flow
- town visit flow
- save/load

MVP content can use:

- Level 1 room tables
- a subset of creature cards
- a subset of armour, potions, scrolls, and loot

## Recommended Build Sequence

### Step 1: Encode rules constants and enums

Start with:

- roll types
- item categories
- damage modifiers
- statuses
- level themes
- room sizes
- exit types
- creature types

### Step 2: Encode foundational tables

Before level-specific content, encode:

- starting armour
- starting scrolls
- weapon manoeuvres
- armour table
- magic potion table
- magic scroll table
- failed-to-cast table
- gem values
- miscellaneous item values

### Step 3: Build dice and modifier engine

This is the base for:

- combat
- room generation
- table lookups
- town actions

### Step 4: Build character creation and sheet logic

This allows the app to:

- create legal starting characters
- compute carrying limits
- track stats and loadout

### Step 5: Build Level 1 room generation and resolution

Use these content families:

- `EXT1`
- `L1LR`
- `Level 1 Rooms`
- `L1SR`
- Level 1 encounter tables

### Step 6: Build combat against a controlled subset of creature cards

Use a small but varied subset first:

- one humanoid
- one animal
- one patrol/multi-enemy case
- one creature with interrupts

### Step 7: Build post-room rewards and town return

Support:

- treasure
- XP
- inventory updates
- exit shaft search
- market
- temple or tavern

## Implementation Decisions To Make

These are not fully dictated by the books and should be decided explicitly.

### 1. How literal should map generation be?

Options:

- simulate full geometric placement
- simplify to node-and-edge rooms while preserving rules

Recommendation:

- use full geometry internally for rules fidelity
- render a simplified clean map visually

### 2. How should inventive usage work?

Options:

- fully manual freeform input
- fixed list of context-sensitive actions

Recommendation:

- use context-sensitive actions for MVP
- keep a future manual override/admin action

### 3. How should ambiguous “common sense” rules be handled?

Recommendation:

- codify deterministic heuristics
- log them clearly
- document all heuristics in a separate implementation notes file

## Open Questions

These should be resolved before a full production implementation:

1. Will the digital version aim for strict parity with every table text outcome, or allow some streamlining?
2. Should room descriptions be reproduced verbatim in-game, or summarized into structured effects plus flavor text?
3. Should the app keep the original D66-first tactile feel with visible primary/secondary dice, even when automation could hide it?
4. Should optional tables be available as campaign settings at world creation?

## Immediate Next Deliverables

After this spec, the most useful follow-up files are:

1. `content-checklist.json`
2. `DATA_MODEL.md`
3. `IMPLEMENTATION_NOTES.md`

Suggested order:

1. create the content checklist from the Tables Codex
2. define exact TypeScript interfaces and schemas
3. record digital-only rules decisions and heuristics

## Summary

The web version should be built as a **rules engine plus structured content system**.

The Core Rules define:

- flow
- player rules
- combat rules
- progression rules
- town rules

The Tables Codex defines:

- lookup content
- room content
- item content
- creature content
- level content

That separation should be reflected directly in the codebase and content pipeline.