docs/PRD.md

# Devil's Dozen - Product Requirements Document

## 1. Executive Summary

**Devil's Dozen** is a medieval-themed multiplayer dice game supporting 2-4 players across two distinct game modes. The game combines risk-reward mechanics with real-time multiplayer synchronization, wrapped in an immersive tavern aesthetic.

### Vision Statement
Create an engaging, free-to-host multiplayer dice game that captures the tension of push-your-luck gameplay while providing a polished, thematic experience.

---

## 2. Game Modes

### 2.1 The Peasant's Gamble (D6 Mode)

A 6-dice game inspired by Kingdom Come: Deliverance's dice minigame.

**Objective**: First player to reach the target score wins (configurable: 3000/5000/10000 points).

**Core Mechanics**:
- Roll 6 dice, must set aside at least one scoring die
- Can continue rolling remaining dice to accumulate points
- **Bust**: Rolling no scoring dice loses all accumulated turn points
- **Hot Dice**: Scoring all 6 dice allows rolling all dice again

**Scoring Table**:
| Roll | Points |
|------|--------|
| Single 1 | 100 |
| Single 5 | 50 |
| Three 1s | 1,000 |
| Three of X | X × 100 |
| Four+ of X | Previous tier × 2 |
| 1-2-3-4-5 | 500 (Low Straight) |
| 2-3-4-5-6 | 750 (High Straight) |
| 1-2-3-4-5-6 | 1,500 (Full Straight) |

### 2.2 The Alchemist's Ascent (D20 Mode)

A tiered progression game using D20 dice with escalating risk.

**Objective**: First player to reach 250 points wins.

**Tier System**:

| Tier | Score Range | Dice | Special Rules |
|------|-------------|------|---------------|
| Red (1) | 0-100 | 8 D20s | Standard scoring |
| Green (2) | 101-200 | 3 D20s | 5× multiplier, reroll risk |
| Blue (3) | 201-250 | 1 D20 | High risk/reward finale |

**Tier 1 Scoring** (Red):
- Single 1 = 1 pt, Single 5 = 5 pts
- Pair = face value (pair of 1s = 10, pair of 5s = 20)
- Three+ of kind = sum of dice
- Sequence of 3 = 10 pts (+10 per additional)

**Tier 2 Scoring** (Green):
- Same as Tier 1 but **5× multiplier**
- Can reroll individual dice, but if new < old = BUST

**Tier 3 Scoring** (Blue):
- Roll 1 = Reset to 0 points (devastating)
- Roll 20 = Gift 20 points to last-place player
- Roll 2-19 = Face value as points

---

## 3. Multiplayer Requirements

### 3.1 Lobby System
- **Create Lobby**: Generate 6-character shareable code
- **Join Lobby**: Enter code to join existing game
- **Player Capacity**: 2-4 players
- **Player Names**: 30 character max, unique within lobby

### 3.2 Turn Flow
1. Active player's UI is enabled, others observe
2. All players see dice rolls in real-time
3. Turn ends on: Bank, Bust, or Win
4. Automatic turn progression to next player

### 3.3 Reconnection
- Players can rejoin via lobby code
- Game state persists through disconnection
- 5-minute timeout before player is marked inactive

---

## 4. User Interface Requirements

### 4.1 Core Components

**Dice Tray**
- Visual representation of all dice in current roll
- Click-to-hold interaction for setting aside dice
- Animation on roll (1-2 seconds)
- Visual distinction between held/unheld dice

**Scoreboard**
- All player names with total scores
- Current turn indicator (highlighted player)
- Score needed to win
- Current turn score (for active player)

**Controls**
- Roll button (starts turn / continues roll)
- Bank button (end turn, keep points)
- Hold selection (click dice to toggle)
- Clear visual feedback for button states

### 4.2 Theme Requirements (Medieval Tavern)
- Dark color palette (browns, golds, deep reds)
- Parchment/aged paper textures
- Gothic or medieval-style typography
- Candlelit ambiance effects

### 4.3 Animation & Audio
- Dice roll animation with physics feel
- Bust: skull icon, groan sound
- Victory: celebration, fanfare
- Audio mute toggle (persisted)

---

## 5. Technical Requirements

### 5.1 Performance
- Initial load < 5 seconds
- Dice roll animation < 2 seconds
- Turn sync latency < 500ms
- Support 4 concurrent players per lobby

### 5.2 Browser Support
- Chrome, Firefox, Safari, Edge (latest 2 versions)
- Mobile browsers (iOS Safari, Chrome Android)
- Responsive layout for mobile play

### 5.3 Accessibility
- Keyboard navigation for controls
- Sufficient color contrast (WCAG AA)
- Screen reader labels for key actions

---

## 6. Future Considerations

These features are **out of scope** for MVP but documented for future development:

- Additional game modes
- Player avatars / customization
- Persistent accounts and statistics
- Tournament mode
- Spectator mode
- Private/password lobbies
- Chat system
- Achievement system

---

## 7. Success Metrics

### Launch Criteria
- [ ] Both game modes fully playable
- [ ] 2-4 player multiplayer functional
- [ ] Medieval theme applied throughout
- [ ] Audio with mute toggle
- [ ] Mobile-responsive layout
- [ ] Deployed on Hugging Face Spaces

### Quality Targets
- Zero critical bugs in core gameplay
- All scoring calculations verified by tests
- Successful 4-player game session with 0 sync errors