132 lines
12 KiB
Markdown
132 lines
12 KiB
Markdown
# Feature Specification: Bestiary Search & Stat Block Display
|
|
|
|
**Feature Branch**: `021-bestiary-statblock`
|
|
**Created**: 2026-03-06
|
|
**Status**: Draft
|
|
**Input**: User description: "Bestiary creature library with search, stat block display, and combatant prefill from bundled D&D 5e monster data."
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### User Story 1 - Search and Add a Creature from the Bestiary (Priority: P1)
|
|
|
|
As a DM running an encounter, I want to search for a creature by name in the bestiary so that I can quickly add it as a combatant with its stats pre-filled (name, HP, AC), saving me from manually entering data.
|
|
|
|
The action bar gains a search icon (magnifying glass). Clicking it opens a search input with autocomplete suggestions filtered from the bundled bestiary. Selecting a creature adds it as a combatant with name, max HP, current HP, and AC pre-filled from the creature's stat block data.
|
|
|
|
**Why this priority**: This is the core value proposition — reducing manual data entry when setting up encounters. Without this, the bestiary data has no way to reach the encounter tracker.
|
|
|
|
**Independent Test**: Can be fully tested by searching for "Goblin", selecting it, and verifying a combatant appears with the correct name, HP, and AC values from the 2024 Monster Manual.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the action bar is visible, **When** the user clicks the search icon, **Then** a search input appears with focus.
|
|
2. **Given** the search input is open, **When** the user types "gob", **Then** a dropdown shows matching creatures (e.g., "Goblin", "Goblin Boss", "Goblin Shaman") filtered from the bestiary.
|
|
3. **Given** search results are showing, **When** the user selects "Goblin", **Then** a new combatant is added with name "Goblin", max HP, current HP, and AC matching the Goblin's bestiary entry.
|
|
4. **Given** a combatant named "Goblin" already exists, **When** the user adds another Goblin from the bestiary, **Then** the existing combatant is renamed to "Goblin 1" and the new combatant is named "Goblin 2" (auto-numbered).
|
|
5. **Given** an auto-numbered combatant "Goblin 2" exists, **When** the user edits its name, **Then** the name updates as usual (renaming is not blocked by auto-numbering).
|
|
6. **Given** the search input is open, **When** the user types a query with no matches (e.g., "zzzzz"), **Then** the dropdown shows a "No creatures found" message.
|
|
7. **Given** the search input is open, **When** the user presses Escape or clicks outside, **Then** the search closes without adding a combatant.
|
|
|
|
---
|
|
|
|
### User Story 2 - View Creature Stat Block (Priority: P2)
|
|
|
|
As a DM, I want to see the full stat block of a creature displayed in a side panel so that I can reference its abilities, actions, and traits during combat without switching to another tool.
|
|
|
|
When a creature is selected from the bestiary search or when clicking a bestiary-linked combatant in the tracker, a stat block panel appears beside the encounter tracker showing the creature's full information in the classic D&D stat block layout.
|
|
|
|
**Why this priority**: The stat block display is the primary reference tool during combat. It transforms the app from just an initiative tracker into a combat management tool.
|
|
|
|
**Independent Test**: Can be tested by selecting any creature and verifying all stat block sections render correctly with accurate data from the bestiary.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a creature is selected from the bestiary search, **When** the stat block panel opens, **Then** it displays: name, size, type, alignment, AC, HP (average and formula), speed, ability scores with modifiers, saving throws, skills, damage resistances/immunities, condition immunities, senses, languages, challenge rating, traits, actions, and legendary actions (if applicable).
|
|
2. **Given** the stat block panel is open on desktop (wide viewport), **Then** the layout is side-by-side: encounter tracker on the left, stat block panel on the right.
|
|
3. **Given** the stat block panel is open on mobile (narrow viewport), **Then** the stat block appears as a slide-over drawer that can be dismissed.
|
|
4. **Given** a stat block is displayed, **When** the user clicks a different bestiary-linked combatant in the tracker, **Then** the stat block panel updates to show that creature's data.
|
|
5. **Given** a stat block is displayed, **When** the user closes the panel (via close button or gesture), **Then** the layout returns to the single-column tracker view.
|
|
6. **Given** a creature entry contains markup tags (e.g., spell references, dice notation), **Then** they render as plain text (e.g., "{@spell fireball|XPHB}" renders as "fireball", "{@dice 3d6}" renders as "3d6").
|
|
|
|
---
|
|
|
|
### User Story 3 - Quick-Add by Name with Bestiary Suggestions (Priority: P3)
|
|
|
|
As a DM, I want to see bestiary suggestions while typing a combatant name in the regular add flow, so that I can seamlessly switch between adding a custom-named combatant and pulling stats from the bestiary.
|
|
|
|
When typing in the existing combatant name input, matching bestiary creatures appear as suggestions. The user can either ignore them and add a plain-named combatant (current behavior) or select a suggestion to get the stat pre-fill.
|
|
|
|
**Why this priority**: This enhances the existing add flow without disrupting it. It's a convenience layer on top of P1 and P2.
|
|
|
|
**Independent Test**: Can be tested by typing "Dragon" in the name input and verifying suggestions appear, then either selecting one (stats pre-filled) or pressing Enter to add a plain "Dragon" combatant.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the user is typing in the combatant name input, **When** the text matches one or more bestiary creature names, **Then** matching suggestions appear below the input.
|
|
2. **Given** suggestions are visible, **When** the user selects a suggestion, **Then** the combatant is added with name, HP, and AC pre-filled from the bestiary.
|
|
3. **Given** suggestions are visible, **When** the user presses Enter without selecting a suggestion, **Then** a plain combatant is added with just the typed name (current behavior preserved).
|
|
4. **Given** the user types fewer than 2 characters, **Then** no suggestions are shown (to avoid overwhelming results).
|
|
|
|
---
|
|
|
|
### User Story 4 - Responsive Layout Transition (Priority: P4)
|
|
|
|
As a DM using the app on different devices, I want the layout to adapt between side-by-side (desktop) and drawer (mobile) views so that the stat block is usable regardless of screen size.
|
|
|
|
**Why this priority**: The core functionality works on desktop with the side-by-side layout. Mobile adaptation is important for table use but is an enhancement over the desktop experience.
|
|
|
|
**Independent Test**: Can be tested by resizing the browser window and verifying the stat block transitions between panel and drawer modes.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a wide viewport (desktop), **When** a stat block is open, **Then** the tracker and stat block display side-by-side.
|
|
2. **Given** a narrow viewport (mobile/tablet), **When** a stat block is open, **Then** it appears as a dismissible drawer overlay.
|
|
3. **Given** the viewport is resized from wide to narrow while a stat block is open, **Then** the layout transitions smoothly from panel to drawer.
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- What happens when two creatures from different future bestiary sources share the same name? The source tag is shown alongside the name in search results (e.g., "Goblin (MM 2024)").
|
|
- What happens when adding multiple creatures of the same type? Auto-numbering appends an incrementing suffix: "Goblin 1", "Goblin 2", etc. The first instance is renamed to "Goblin 1" when a second is added.
|
|
- What happens if the bestiary data fails to load? The app continues to function as a plain initiative tracker; the search icon is hidden or disabled with appropriate feedback.
|
|
- How does the stat block handle creatures with no traits or legendary actions? Those sections are simply omitted from the stat block display.
|
|
- How does the stat block handle very long content (e.g., a Lich with extensive spellcasting)? The stat block panel scrolls independently of the encounter tracker.
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: System MUST bundle the 2024 Monster Manual bestiary data as a static asset shipped with the application.
|
|
- **FR-002**: System MUST normalize raw bestiary data into a consistent internal creature format at load time via an adapter.
|
|
- **FR-003**: System MUST provide a search interface (magnifying glass icon) in the action bar that filters creatures by name substring matching.
|
|
- **FR-004**: Search results MUST appear as the user types, with results updating on each keystroke (or with minimal debounce for performance).
|
|
- **FR-005**: Selecting a creature from search results MUST add a combatant with name, max HP, current HP, and AC pre-filled from the creature's data.
|
|
- **FR-006**: System MUST auto-number duplicate creature names (e.g., "Goblin 1", "Goblin 2") when multiple combatants share the same bestiary creature name.
|
|
- **FR-007**: Auto-numbered names MUST remain editable via the existing rename functionality.
|
|
- **FR-008**: System MUST display a stat block panel showing the full creature information when a creature is selected.
|
|
- **FR-009**: The stat block MUST include: name, size, type, alignment, AC (with armor source if applicable), HP (average + formula), speed, ability scores with modifiers, saving throws, skills, damage vulnerabilities, damage resistances, damage immunities, condition immunities, senses, languages, challenge rating, proficiency bonus, traits, actions, bonus actions, reactions, and legendary actions.
|
|
- **FR-010**: System MUST strip bestiary markup tags (spell references, dice notation, attack tags) and render them as plain readable text.
|
|
- **FR-011**: On wide viewports, the layout MUST be side-by-side with the encounter tracker on the left and stat block on the right.
|
|
- **FR-012**: On narrow viewports, the stat block MUST appear as a dismissible drawer or slide-over.
|
|
- **FR-013**: The existing action bar name input SHOULD show bestiary suggestions as the user types, allowing selection for stat pre-fill or plain entry on Enter.
|
|
- **FR-014**: System MUST support adding more bestiary source files in the future without structural changes, each identified by a source tag.
|
|
- **FR-015**: Combatants added from the bestiary MUST retain a link to their creature data so the stat block can be re-opened from the tracker.
|
|
|
|
### Key Entities
|
|
|
|
- **Creature**: A bestiary entry representing a monster or NPC. Key attributes: name, source, size, type, alignment, armor class, hit points (average and formula), speed, ability scores (STR/DEX/CON/INT/WIS/CHA), saving throw bonuses, skill bonuses, damage resistances/immunities, condition immunities, senses, languages, challenge rating, proficiency bonus, traits, actions, legendary actions.
|
|
- **Bestiary Source**: A collection of creatures from a specific publication (e.g., "MM 2024"). Key attributes: source identifier, display name, tag label (e.g., "legacy" for 2014 books).
|
|
- **Combatant** (extended): Existing combatant entity gains an optional reference to a Creature, enabling stat block lookup and stat pre-fill on creation.
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: Users can search for and add a creature from the bestiary as a combatant in under 5 seconds (type query, select result, combatant appears with stats).
|
|
- **SC-002**: Search results appear within 200ms of typing for the full 2024 Monster Manual dataset (400+ creatures).
|
|
- **SC-003**: All stat block sections render correctly for 100% of creatures in the bundled bestiary (no missing data, no raw markup tags visible).
|
|
- **SC-004**: The stat block panel is readable and fully functional on viewports from 375px (mobile) to 2560px (ultrawide) without horizontal scrolling or content clipping.
|
|
- **SC-005**: Adding a creature from the bestiary pre-fills name, HP, and AC with 100% accuracy relative to the source data.
|
|
- **SC-006**: The existing "quick add by name" flow continues to work identically for users who do not interact with bestiary features (zero regression).
|