ef76b9c90b
Live 3-bar difficulty indicator in the top bar showing encounter difficulty (Trivial/Low/Moderate/High) based on the 2024 5.5e XP budget system. Automatically derived from PC levels and bestiary creature CRs. - Add optional level field (1-20) to PlayerCharacter - Add CR-to-XP and XP Budget per Character lookup tables in domain - Add calculateEncounterDifficulty pure function - Add DifficultyIndicator component with color-coded bars and tooltip - Add useDifficulty hook composing encounter, PC, and bestiary contexts - Indicator hidden when no PCs with levels or no bestiary-linked monsters - Level field in PC create/edit forms, persisted in storage Closes #18 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
206 lines
14 KiB
Markdown
206 lines
14 KiB
Markdown
# Feature Specification: Encounter Difficulty Indicator
|
|
|
|
**Feature Branch**: `008-encounter-difficulty`
|
|
**Created**: 2026-03-27
|
|
**Status**: Draft
|
|
**Input**: Gitea issue #18 — "Encounter difficulty indicator (5.5e XP budget)"
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### Difficulty Calculation
|
|
|
|
**Story ED-1 — See encounter difficulty at a glance (Priority: P1)**
|
|
|
|
A game master is building an encounter by adding monsters and player characters. As they add bestiary-linked creatures alongside PC combatants that have levels assigned, a compact 3-bar difficulty indicator appears in the top bar next to the active combatant name. The bars fill and change color to reflect the current difficulty tier: one green bar for Low, two yellow bars for Moderate, three red bars for High. Hovering over the indicator shows a tooltip with the difficulty label (e.g., "Moderate encounter difficulty").
|
|
|
|
**Why this priority**: This is the entire feature — without the indicator there is nothing to show.
|
|
|
|
**Independent Test**: Can be fully tested by adding PC combatants (with levels) and bestiary-linked monsters to an encounter and verifying the indicator appears with the correct difficulty tier.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** an encounter with at least one PC combatant whose player character has a level and at least one bestiary-linked combatant, **When** the total monster XP is below the Low threshold, **Then** the indicator shows three empty bars (trivial difficulty).
|
|
|
|
2. **Given** an encounter where total monster XP meets or exceeds the Low threshold but is below Moderate, **When** the indicator renders, **Then** it shows one filled green bar and the tooltip reads "Low encounter difficulty".
|
|
|
|
3. **Given** an encounter where total monster XP meets or exceeds the Moderate threshold but is below High, **When** the indicator renders, **Then** it shows two filled yellow bars and the tooltip reads "Moderate encounter difficulty".
|
|
|
|
4. **Given** an encounter where total monster XP meets or exceeds the High threshold, **When** the indicator renders, **Then** it shows three filled red bars and the tooltip reads "High encounter difficulty".
|
|
|
|
5. **Given** an encounter where total monster XP exceeds the High threshold by a large margin, **When** the indicator renders, **Then** it still shows three filled red bars (High is the cap — there is no "above High" tier).
|
|
|
|
6. **Given** the difficulty indicator is visible, **When** a bestiary-linked combatant is added or removed, **Then** the indicator updates immediately to reflect the new difficulty tier.
|
|
|
|
7. **Given** the difficulty indicator is visible, **When** a PC combatant is added or removed, **Then** the indicator updates immediately to reflect the new party budget.
|
|
|
|
---
|
|
|
|
### Indicator Visibility
|
|
|
|
**Story ED-2 — Indicator hidden when data is insufficient (Priority: P1)**
|
|
|
|
The difficulty indicator only appears when meaningful calculation is possible. If the encounter lacks PC combatants with levels or lacks bestiary-linked monsters, the indicator is hidden entirely rather than showing a confusing empty or zero state.
|
|
|
|
**Why this priority**: Showing an indicator when it can't calculate anything is worse than showing nothing — it would confuse users who don't use bestiary creatures or don't assign levels.
|
|
|
|
**Independent Test**: Can be tested by creating encounters with various combatant combinations and verifying the indicator appears or hides correctly.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** an encounter with only custom combatants (no `creatureId`), **When** the top bar renders, **Then** no difficulty indicator is shown.
|
|
|
|
2. **Given** an encounter with bestiary-linked monsters but no PC combatants, **When** the top bar renders, **Then** no difficulty indicator is shown.
|
|
|
|
3. **Given** an encounter with PC combatants whose player characters have no level assigned, **When** the top bar renders, **Then** no difficulty indicator is shown (even if bestiary-linked monsters are present).
|
|
|
|
4. **Given** an encounter with one leveled PC combatant and one bestiary-linked monster, **When** the last leveled PC is removed, **Then** the indicator disappears.
|
|
|
|
5. **Given** an encounter with one leveled PC combatant and one bestiary-linked monster, **When** the last bestiary-linked monster is removed (only custom combatants remain), **Then** the indicator disappears.
|
|
|
|
---
|
|
|
|
### Player Character Level
|
|
|
|
**Story ED-3 — Assign a level to a player character (Priority: P1)**
|
|
|
|
The game master can set an optional level (1-20) when creating or editing a player character. This level is used to determine the party's XP budget for the difficulty calculation. Player characters without a level are silently excluded from the budget.
|
|
|
|
**Why this priority**: Without levels on PCs, the XP budget cannot be calculated and the indicator cannot function.
|
|
|
|
**Independent Test**: Can be tested by creating a player character with a level, adding it to an encounter with a bestiary creature, and verifying the difficulty indicator appears.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the create player character form is open, **When** the user sets level to 5, **Then** the player character is created with level 5.
|
|
|
|
2. **Given** the create player character form is open, **When** the user leaves the level field empty, **Then** the player character is created without a level.
|
|
|
|
3. **Given** a player character with no level, **When** the user edits the player character and sets level to 10, **Then** the level is saved and used in future difficulty calculations.
|
|
|
|
4. **Given** the level field is shown, **When** the user enters a value outside 1-20 (e.g., 0, 21, -1), **Then** a validation error is shown and the value is not accepted.
|
|
|
|
5. **Given** a player character with level 5 exists, **When** the page is reloaded, **Then** the level is restored as part of the player character data.
|
|
|
|
---
|
|
|
|
### XP Budget Calculation
|
|
|
|
**Story ED-4 — Correct XP budget from 5.5e rules (Priority: P1)**
|
|
|
|
The difficulty calculation uses the 2024 5.5e XP Budget per Character table and a standard CR-to-XP mapping. The party's XP budget is the sum of per-character budgets for each PC combatant that has a level. The total monster XP is the sum of XP values for each bestiary-linked combatant's CR. The difficulty tier is determined by comparing total monster XP against the Low, Moderate, and High budget thresholds.
|
|
|
|
**Why this priority**: Incorrect calculation would make the feature misleading — the math must match the published rules.
|
|
|
|
**Independent Test**: Can be tested with pure domain function unit tests using known party/monster combinations from the 2024 DMG examples.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a party of four level 1 PCs (Low budget: 50 each = 200 total), **When** facing a single Bugbear (CR 1, 200 XP), **Then** the difficulty is Low (200 XP meets the Low threshold of 200 but is below Moderate at 300).
|
|
|
|
2. **Given** a party of five level 3 PCs (Moderate budget: 225 each = 1,125 total), **When** facing monsters totaling 1,125 XP, **Then** the difficulty is Moderate.
|
|
|
|
3. **Given** a party with PCs at different levels (e.g., three level 3 and one level 2), **When** the budget is calculated, **Then** each PC's budget is looked up individually by level and summed (not averaged).
|
|
|
|
4. **Given** an encounter with both bestiary-linked and custom combatants, **When** the XP total is calculated, **Then** only bestiary-linked combatants contribute XP (custom combatants are excluded).
|
|
|
|
5. **Given** a PC combatant whose player character has no level, **When** the budget is calculated, **Then** that PC is excluded from the budget (as if they are not in the party).
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- **All bars empty (trivial)**: When total monster XP is greater than 0 but below the Low threshold, the indicator shows three empty bars. This communicates "we can calculate, but it's trivial."
|
|
- **Zero monster XP**: If all combatants with `creatureId` have CR 0 (0 XP), the indicator shows three empty bars (trivial).
|
|
- **Mixed party levels**: PCs at different levels each contribute their own budget — the system handles heterogeneous parties correctly.
|
|
- **Duplicate PC combatants**: If the same player character is added to the encounter multiple times, each copy contributes to the party budget independently (each counts as a party member).
|
|
- **CR fractions**: Bestiary creatures can have fractional CRs (e.g., "1/4", "1/2"). The CR-to-XP lookup must handle these string formats.
|
|
- **Custom combatants silently excluded**: Custom combatants without `creatureId` do not appear in the XP total and are not flagged as warnings or errors.
|
|
- **PCs without level silently excluded**: PC combatants whose player character has no level do not contribute to the budget and are not flagged.
|
|
- **Indicator with empty encounter**: When the encounter has no combatants, the indicator is hidden (the top bar may not even render per existing behavior).
|
|
- **Level field on existing player characters**: Existing player characters created before this feature will have no level. They are treated as "no level assigned" — no migration or default is needed.
|
|
|
|
---
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
### Functional Requirements
|
|
|
|
#### FR-001 — XP Budget per Character table
|
|
The system MUST contain the 2024 5.5e XP Budget per Character lookup table mapping character levels 1-20 to Low, Moderate, and High XP thresholds.
|
|
|
|
#### FR-002 — CR-to-XP lookup table
|
|
The system MUST contain a CR-to-XP lookup table mapping all standard 5e challenge ratings (0, 1/8, 1/4, 1/2, 1-30) to their XP values.
|
|
|
|
#### FR-003 — Party XP budget calculation
|
|
The system MUST calculate the party's XP budget by summing the per-character budget for each PC combatant whose player character has a level assigned. PCs without a level are excluded from the sum.
|
|
|
|
#### FR-004 — Monster XP total calculation
|
|
The system MUST calculate the total monster XP by summing the XP value (derived from CR) for each combatant that has a `creatureId`. Combatants without `creatureId` are excluded.
|
|
|
|
#### FR-005 — Difficulty tier determination
|
|
The system MUST determine the encounter difficulty tier by comparing total monster XP against the party's Low, Moderate, and High thresholds. The tier is the highest threshold that the total XP meets or exceeds. If below Low, the encounter is trivial (no tier label).
|
|
|
|
#### FR-006 — Difficulty indicator in top bar
|
|
The system MUST display a 3-bar difficulty indicator in the top bar, positioned to the right of the active combatant name.
|
|
|
|
#### FR-007 — Bar visual states
|
|
The indicator MUST display: three empty bars for trivial, one green filled bar for Low, two yellow filled bars for Moderate, three red filled bars for High.
|
|
|
|
#### FR-008 — Tooltip on hover
|
|
The indicator MUST show a tooltip on hover displaying the difficulty label (e.g., "Moderate encounter difficulty"). For the trivial state, the tooltip MUST read "Trivial encounter difficulty".
|
|
|
|
#### FR-009 — Live updates
|
|
The indicator MUST update immediately when combatants are added to or removed from the encounter.
|
|
|
|
#### FR-010 — Hidden when data insufficient
|
|
The indicator MUST be hidden when the encounter has no PC combatants with levels OR no bestiary-linked combatants.
|
|
|
|
#### FR-011 — Optional level field on PlayerCharacter
|
|
The `PlayerCharacter` entity MUST support an optional `level` field accepting integer values 1-20.
|
|
|
|
#### FR-012 — Level in create/edit forms
|
|
The player character create and edit forms MUST include an optional level field with validation constraining values to the 1-20 range.
|
|
|
|
#### FR-013 — Level persistence
|
|
The player character level MUST be persisted and restored across sessions, consistent with existing player character persistence behavior.
|
|
|
|
#### FR-014 — High is the cap
|
|
When total monster XP exceeds the High threshold, the indicator MUST display the High state (three red bars). There is no tier above High.
|
|
|
|
### Key Entities
|
|
|
|
- **XP Budget Table**: A lookup mapping character level (1-20) to three XP thresholds (Low, Moderate, High), sourced from the 2024 5.5e DMG.
|
|
- **CR-to-XP Table**: A lookup mapping challenge rating strings ("0", "1/8", "1/4", "1/2", "1"-"30") to XP integer values.
|
|
- **DifficultyTier**: An enumeration of difficulty categories: Trivial, Low, Moderate, High.
|
|
- **DifficultyResult**: The output of the calculation containing the tier, total monster XP, and per-tier budget thresholds.
|
|
- **PlayerCharacter.level**: An optional integer (1-20) added to the existing `PlayerCharacter` entity defined in spec 005.
|
|
|
|
---
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: The difficulty indicator correctly reflects the 2024 5.5e XP budget rules for all party level and monster CR combinations in the published tables.
|
|
- **SC-002**: The indicator updates within the same render cycle as combatant additions/removals — no perceptible delay.
|
|
- **SC-003**: Users can identify the encounter difficulty tier at a glance from the top bar without opening any modal or menu.
|
|
- **SC-004**: The indicator is completely hidden when the encounter lacks sufficient data for calculation, avoiding user confusion.
|
|
- **SC-005**: The difficulty calculation is a pure domain function with no I/O, consistent with the project's deterministic domain core.
|
|
- **SC-006**: The domain module for difficulty calculation has zero imports from application, adapter, or UI layers.
|
|
- **SC-007**: The optional level field integrates seamlessly into the existing player character create/edit workflow without disrupting existing functionality.
|
|
|
|
---
|
|
|
|
## Assumptions
|
|
|
|
- The 2024 5.5e XP Budget per Character table and CR-to-XP table are static data that do not change at runtime.
|
|
- The CR-to-XP mapping uses the standard 5e values (0 XP for CR 0, 25 XP for CR 1/8, 50 XP for CR 1/4, 100 XP for CR 1/2, 200 XP for CR 1, up to 155,000 XP for CR 30).
|
|
- Monster XP is derived solely from CR — no encounter multipliers are applied (the 5.5e system dropped the 2014 multiplier mechanic).
|
|
- The `level` field is added to the existing `PlayerCharacter` type from spec 005. No new entity or storage mechanism is needed.
|
|
- Existing player characters without a level are treated as "no level assigned" with no migration.
|
|
- The difficulty indicator occupies minimal horizontal space in the top bar and does not interfere with the combatant name truncation or other controls.
|
|
- MVP baseline does not include CR assignment for custom (non-bestiary) combatants.
|
|
- MVP baseline does not include the 2014 DMG encounter multiplier mechanic or the four-tier (Easy/Medium/Hard/Deadly) system.
|
|
- MVP baseline does not include showing XP totals or budget numbers in the indicator — only the visual bars and tooltip label.
|
|
- MVP baseline does not include per-combatant level overrides — level is always derived from the player character template.
|