174 lines
7.4 KiB
Markdown
174 lines
7.4 KiB
Markdown
# Dice Rolling — Design Spec
|
|
|
|
## Overview
|
|
|
|
Add a complete dice rolling system: server-side roll engine, shared real-time roll log panel, character sheet roll buttons for ability checks and attacks, advantage/disadvantage support, and a general-purpose dice roller.
|
|
|
|
## 1. Roll Engine (Server-Side)
|
|
|
|
### Socket.IO Events
|
|
|
|
**Client → Server:**
|
|
|
|
- `roll:request` — `{ campaignId, characterId?, characterName?, type, dice, label, modifier?, advantage?, disadvantage? }`
|
|
- `type`: `'attack'` | `'ability-check'` | `'custom'`
|
|
- `dice`: string expression like `'1d20'`, `'2d6'`, `'1d8+1'`
|
|
- `label`: human-readable description (e.g. "SHORTSWORD attack", "DEX check", "2d6")
|
|
- `modifier`: optional numeric modifier already included in the expression for display purposes
|
|
- `advantage`/`disadvantage`: boolean, only meaningful for d20 rolls
|
|
|
|
**Server → Campaign Room:**
|
|
|
|
- `roll:result` — `{ id, campaignId, characterId, characterName, type, label, diceExpression, rolls, modifier, total, advantage, disadvantage, created_at }`
|
|
- `rolls`: array of individual die results (e.g. `[14]` or `[14, 8]` for advantage)
|
|
- `total`: final computed result
|
|
|
|
### Dice Expression Parser
|
|
|
|
Server-side parser that handles: `NdX`, `NdX+M`, `NdX-M`
|
|
|
|
- `N` = number of dice (default 1 if omitted, e.g. "d20" = "1d20")
|
|
- `X` = die size (4, 6, 8, 10, 12, 20, 100)
|
|
- `M` = optional flat modifier
|
|
|
|
Examples: `1d20`, `2d6`, `1d8+1`, `d20-1`, `4d6`, `1d100`
|
|
|
|
Invalid expressions return an error result with `{ error: "Couldn't parse: xyz" }`.
|
|
|
|
### Advantage / Disadvantage
|
|
|
|
For any roll where `advantage` or `disadvantage` is true:
|
|
|
|
- Roll the primary die (d20) twice instead of once
|
|
- `rolls` array contains both results: `[14, 8]`
|
|
- `total` uses the higher (advantage) or lower (disadvantage) of the two, plus modifier
|
|
- Display shows both dice with the chosen one highlighted
|
|
|
|
### roll_log Table
|
|
|
|
| Column | Type | Notes |
|
|
| --------------- | ------- | ----------------------------------- |
|
|
| id | INTEGER | Primary key, autoincrement |
|
|
| campaign_id | INTEGER | FK to campaigns |
|
|
| character_id | INTEGER | Nullable (null for anonymous rolls) |
|
|
| character_name | TEXT | Display name (or "Roll") |
|
|
| type | TEXT | attack / ability-check / custom |
|
|
| label | TEXT | Human-readable description |
|
|
| dice_expression | TEXT | Original expression (e.g. "1d20") |
|
|
| rolls | TEXT | JSON array of die results |
|
|
| modifier | INTEGER | Flat modifier applied |
|
|
| total | INTEGER | Final result |
|
|
| advantage | INTEGER | 0 or 1 |
|
|
| disadvantage | INTEGER | 0 or 1 |
|
|
| created_at | TEXT | ISO timestamp |
|
|
|
|
## 2. Roll Log Panel
|
|
|
|
### Layout
|
|
|
|
Collapsible side panel on the right of the campaign view (outside the character modal).
|
|
|
|
- **Width:** ~300px on desktop
|
|
- **Mobile:** full-width bottom drawer
|
|
- **Collapsed state:** thin strip (~40px) with a dice icon and the last roll result visible. Click to expand.
|
|
- **Expanded state:** full panel with header, input, and scrollable log
|
|
|
|
### Panel Contents (top to bottom)
|
|
|
|
1. **Header:** "Roll Log" title + collapse button
|
|
2. **General roller input:** text input accepting dice expressions. Placeholder: "Roll dice... (e.g. 2d6+1)". Enter to roll. Rolls are anonymous (characterName = "Roll").
|
|
3. **Roll entries:** scrollable list, newest at top. Last ~50 loaded from DB on campaign entry.
|
|
|
|
### Roll Entry Card
|
|
|
|
Each roll displays as a small styled card:
|
|
|
|
- **Top line:** character name (bold, colored) + relative timestamp ("just now", "2m ago")
|
|
- **Label:** what was rolled ("SHORTSWORD attack", "DEX check", "2d6+1")
|
|
- **Dice breakdown:**
|
|
- Normal: `d20: [14]`
|
|
- With advantage: `d20: [14, 8] → 14` (higher highlighted)
|
|
- With disadvantage: `d20: [14, 8] → 8` (lower highlighted)
|
|
- Multiple dice: `2d6: [3, 5] = 8`
|
|
- **Modifier line** (if any): `+ STR (+0)`
|
|
- **Total:** large, bold, highlighted number
|
|
- **Pop-in animation:** new cards slide in and briefly highlight when they arrive
|
|
|
|
### Persistence
|
|
|
|
- Rolls saved to `roll_log` table
|
|
- On entering a campaign, load last 50 rolls via `GET /api/campaigns/:id/rolls`
|
|
- New rolls arrive in real-time via Socket.IO
|
|
|
|
## 3. Roll Buttons on Character Sheet
|
|
|
|
Roll buttons appear in **view mode only** (not edit mode).
|
|
|
|
### Ability Score Rolls
|
|
|
|
Each stat row in the StatsPanel gets a small dice button (🎲 or a styled button) on the right side (in the reserved rollSpace area).
|
|
|
|
- Click: rolls `1d20 + stat modifier`
|
|
- Label: "STR check", "DEX check", etc.
|
|
- Shift+click: advantage (rolls 2d20, takes higher)
|
|
- Ctrl/Cmd+click: disadvantage (rolls 2d20, takes lower)
|
|
|
|
### Attack Rolls
|
|
|
|
Each attack line in AttackBlock gets a dice button on the right side.
|
|
|
|
- Click: rolls `1d20 + attack modifier` for the hit, then rolls the weapon's damage die. Two entries appear in the log: attack roll, then damage roll.
|
|
- Label: "SHORTSWORD attack" for the d20, "SHORTSWORD damage" for the damage die
|
|
- Shift+click: advantage on the attack roll (damage is always normal)
|
|
- Ctrl/Cmd+click: disadvantage on the attack roll
|
|
|
|
### Keyboard Modifier Hint
|
|
|
|
A small hint text at the bottom of the StatsPanel or in the roll log panel header: "Shift: advantage · Ctrl: disadvantage"
|
|
|
|
## 4. Data Flow
|
|
|
|
1. Player clicks a roll button or types in the general roller
|
|
2. Client emits `roll:request` via Socket.IO with campaign ID, character info (if from sheet), dice expression, and advantage/disadvantage flags
|
|
3. Server parses the expression, generates random results, computes total
|
|
4. Server saves to `roll_log` table
|
|
5. Server broadcasts `roll:result` to the campaign room
|
|
6. All clients in the room receive the result and prepend it to their roll log
|
|
7. The new entry animates in with a pop-in effect
|
|
|
|
## 5. API Endpoints
|
|
|
|
- `GET /api/campaigns/:id/rolls` — returns last 50 rolls for a campaign, newest first
|
|
- Socket.IO handles all roll creation (no REST POST needed)
|
|
|
|
## 6. New/Modified Files
|
|
|
|
**Server:**
|
|
|
|
- `server/src/dice.ts` — dice expression parser + roller
|
|
- `server/src/routes/rolls.ts` — GET endpoint for roll history
|
|
- `server/src/db.ts` — add roll_log table
|
|
- `server/src/socket.ts` — handle roll:request, generate result, broadcast
|
|
- `server/src/index.ts` — register rolls route
|
|
|
|
**Client:**
|
|
|
|
- `client/src/components/RollLog.tsx` — the side panel component
|
|
- `client/src/components/RollLog.module.css` — panel styling
|
|
- `client/src/components/RollEntry.tsx` — individual roll result card
|
|
- `client/src/components/RollEntry.module.css` — card styling + animation
|
|
- `client/src/components/DiceButton.tsx` — small reusable dice roll button
|
|
- `client/src/components/DiceButton.module.css` — button styling
|
|
- `client/src/components/StatsPanel.tsx` — add DiceButton to each stat row
|
|
- `client/src/components/AttackBlock.tsx` — add DiceButton to each attack line
|
|
- `client/src/pages/CampaignView.tsx` — add RollLog panel, handle roll socket events
|
|
- `client/src/pages/CampaignView.module.css` — adjust layout for side panel
|
|
- `client/src/types.ts` — add RollResult type
|
|
|
|
## Out of Scope
|
|
|
|
- Animated 3D dice (future enhancement)
|
|
- "Roll as" character/NPC selector for general roller (future)
|
|
- "Drop lowest" or complex dice expressions
|
|
- Talent effects modifying rolls automatically
|
|
- Sound effects
|