85 lines
7.0 KiB
Markdown
85 lines
7.0 KiB
Markdown
# Feature Specification: Display Initiative
|
||
|
||
**Feature Branch**: `025-display-initiative`
|
||
**Created**: 2026-03-10
|
||
**Status**: Draft
|
||
**Input**: User description: "Display a creature's initiative modifier and passive initiative in the stat block panel. Calculate initiative as: DEX modifier + (proficiency multiplier × proficiency bonus), where the proficiency multiplier comes from the bestiary data's initiative.proficiency field (0 if absent, 1 for single, 2 for expertise). Show it in the stat block header area as Initiative +X (Y) matching the Monster Manual 2024 format, where Y = 10 + X. This is a display-only feature — no rolling or auto-applying initiative to encounter order yet. That will be a future feature. The initiative value should be derived purely from bestiary data in the domain layer."
|
||
|
||
## User Scenarios & Testing *(mandatory)*
|
||
|
||
### User Story 1 - View Initiative in Stat Block (Priority: P1)
|
||
|
||
As a DM viewing a creature's stat block, I want to see the creature's initiative modifier and passive initiative displayed prominently so I can quickly reference it when rolling initiative or setting encounter order.
|
||
|
||
**Why this priority**: This is the core and only feature — displaying the calculated initiative value in the stat block is the entire scope.
|
||
|
||
**Independent Test**: Can be fully tested by selecting any creature from the bestiary and verifying the initiative line appears in the stat block header area with the correct calculated value.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** a creature with bestiary data that includes an initiative proficiency multiplier (e.g., Aboleth with DEX 9, CR 10, initiative proficiency multiplier of 2), **When** the stat block is displayed, **Then** the initiative line shows "Initiative +7 (17)" calculated as DEX mod (−1) + (2 × proficiency bonus 4) = +7, passive = 10 + 7 = 17.
|
||
|
||
2. **Given** a creature with bestiary data that includes a single proficiency multiplier for initiative (proficiency = 1), **When** the stat block is displayed, **Then** the initiative modifier includes 1× the creature's proficiency bonus.
|
||
|
||
3. **Given** a creature whose bestiary data has no initiative field, **When** the stat block is displayed, **Then** the initiative line shows only the DEX modifier (e.g., a creature with DEX 14 shows "Initiative +2 (12)").
|
||
|
||
4. **Given** a creature with a negative initiative modifier (e.g., DEX 8 and no initiative proficiency), **When** the stat block is displayed, **Then** the initiative line shows the negative value (e.g., "Initiative −1 (9)") using a minus sign, not a plus sign.
|
||
|
||
---
|
||
|
||
### User Story 2 - Initiative Position Matches Monster Manual Layout (Priority: P2)
|
||
|
||
As a DM, I want the initiative display to appear in the same location as the 2024 Monster Manual stat block (next to AC in the header area) so the layout feels familiar.
|
||
|
||
**Why this priority**: Consistent placement with the official source material improves scanability and trust in the displayed values.
|
||
|
||
**Independent Test**: Can be verified by comparing the stat block layout to a Monster Manual 2024 stat block and confirming initiative appears on the same line or area as AC.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** any creature stat block is displayed, **When** the user looks at the header area, **Then** the initiative value appears adjacent to or on the same line as the AC value, before HP.
|
||
|
||
### Edge Cases
|
||
|
||
- What happens when a creature has a DEX score that produces a modifier of exactly 0 and no initiative proficiency? Display "Initiative +0 (10)".
|
||
- What happens when the proficiency multiplier combined with a negative DEX modifier still results in a negative total? Display with a minus sign (e.g., DEX 3 with proficiency 1 and CR 0 = −4 + 2 = −2 → "Initiative −2 (8)").
|
||
- What happens for creatures without any bestiary data (manually added combatants)? No initiative line is shown — initiative display requires bestiary-sourced creature data.
|
||
|
||
## Requirements *(mandatory)*
|
||
|
||
### Functional Requirements
|
||
|
||
- **FR-001**: System MUST parse the initiative proficiency multiplier from the bestiary data's `initiative.proficiency` field for each creature (0 if absent, 1 for single proficiency, 2 for expertise).
|
||
- **FR-002**: System MUST calculate the initiative modifier as: DEX modifier + (proficiency multiplier × proficiency bonus), where DEX modifier = floor((DEX score − 10) / 2) and proficiency bonus is derived from the creature's challenge rating.
|
||
- **FR-003**: System MUST calculate the passive initiative as: 10 + initiative modifier.
|
||
- **FR-004**: System MUST display initiative in the stat block header area in the format "Initiative +X (Y)" where X is the initiative modifier (with + or − sign) and Y is the passive initiative.
|
||
- **FR-005**: System MUST position the initiative display adjacent to the AC value in the stat block header, matching the Monster Manual 2024 layout.
|
||
- **FR-006**: System MUST NOT display an initiative line for combatants that lack bestiary creature data.
|
||
- **FR-007**: This feature is display-only. The system MUST NOT modify encounter turn order or roll initiative based on displayed values. MVP baseline does not include automatic initiative rolling or encounter order integration.
|
||
|
||
### Key Entities
|
||
|
||
- **Initiative**: A derived value computed from a creature's DEX score, challenge rating, and initiative proficiency multiplier. Not persisted — calculated on demand from bestiary data.
|
||
- **Initiative Proficiency Multiplier**: A value (0, 1, or 2) from the bestiary source data indicating how many times the creature's proficiency bonus is added to initiative. 0 = no proficiency, 1 = proficiency, 2 = expertise.
|
||
|
||
## Success Criteria *(mandatory)*
|
||
|
||
### Measurable Outcomes
|
||
|
||
- **SC-001**: Every creature from the bestiary displays an initiative value in its stat block that matches the value shown on D&D Beyond / Monster Manual 2024 for that creature.
|
||
- **SC-002**: The initiative line is visible without scrolling when the stat block first opens (positioned in the header area alongside AC).
|
||
- **SC-003**: Creatures added manually (without bestiary data) do not show a broken or placeholder initiative line.
|
||
- **SC-004**: The initiative calculation is implemented as a pure domain function with no UI or I/O dependencies, verified by the existing layer boundary checks.
|
||
|
||
## Clarifications
|
||
|
||
### Session 2026-03-10
|
||
|
||
- Q: When there is no initiative value present for a creature, the DEX modifier is used? → A: Yes. The proficiency multiplier defaults to 0 when the `initiative` field is absent, so the formula reduces to the raw DEX modifier. Already reflected in FR-001 (default 0) and Acceptance Scenario 3 (DEX-only fallback).
|
||
|
||
## Assumptions
|
||
|
||
- The initiative proficiency multiplier values in the bestiary data are limited to 0 (absent), 1, and 2. No higher multipliers exist in the current dataset.
|
||
- The "Initiative +X (Y)" format with explicit sign and parenthesized passive value is the standard display across all 2024 Monster Manual stat blocks.
|
||
- A minus sign (−) is used for negative modifiers rather than a hyphen (-), consistent with typographic conventions in official D&D materials.
|