94 lines
5.5 KiB
Markdown
94 lines
5.5 KiB
Markdown
# Feature Specification: Combatant Armor Class Display
|
|
|
|
**Feature Branch**: `016-combatant-ac`
|
|
**Created**: 2026-03-06
|
|
**Status**: Draft
|
|
**Input**: User description: "Display Armor Class for each combatant using a small shield icon with the AC value (e.g., shield 17) next to the name in the encounter list."
|
|
|
|
## User Scenarios & Testing
|
|
|
|
### User Story 1 - Set AC for a Combatant (Priority: P1)
|
|
|
|
A game master sets an Armor Class value on a combatant using the inline AC input in the encounter list so it is stored and visible in the tracker.
|
|
|
|
**Why this priority**: AC must exist on the combatant before it can be displayed. This is the foundational data entry path.
|
|
|
|
**Independent Test**: Can be tested by setting an AC value on an existing combatant and confirming the value persists in the encounter state.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a combatant exists in the encounter, **When** the user clicks the AC area next to the combatant's name and enters 17, **Then** the combatant's AC is set to 17 and the shield icon with "17" appears.
|
|
2. **Given** a combatant exists in the encounter without an AC value, **When** the encounter list is displayed, **Then** no AC input or shield icon is visible until the user activates the AC field.
|
|
|
|
---
|
|
|
|
### User Story 2 - Display AC in the Encounter List (Priority: P1)
|
|
|
|
A game master views the encounter list and sees each combatant's Armor Class displayed as a shield icon with the numeric value (e.g., shield icon followed by 17) next to the combatant's name.
|
|
|
|
**Why this priority**: This is the core visual feature requested by the user, tied with Story 1 since both are needed for the feature to be useful.
|
|
|
|
**Independent Test**: Can be tested by loading an encounter with combatants that have AC values and verifying the shield icon and number appear next to each name.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a combatant has AC 17, **When** the encounter list is displayed, **Then** a shield icon and the value "17" appear next to the combatant's name.
|
|
2. **Given** a combatant has no AC set, **When** the encounter list is displayed, **Then** no shield icon or AC value is shown for that combatant.
|
|
3. **Given** multiple combatants with different AC values, **When** the encounter list is displayed, **Then** each combatant shows its own correct AC value.
|
|
|
|
---
|
|
|
|
### User Story 3 - Edit AC for an Existing Combatant (Priority: P2)
|
|
|
|
A game master edits an existing combatant to add, change, or remove their Armor Class value.
|
|
|
|
**Why this priority**: Editing supports corrections and mid-session changes but is secondary to initial entry and display.
|
|
|
|
**Independent Test**: Can be tested by editing a combatant's AC and confirming the updated value appears in the encounter list.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a combatant has AC 15, **When** the user edits the combatant and changes AC to 18, **Then** the displayed AC updates to 18.
|
|
2. **Given** a combatant has AC 15, **When** the user edits the combatant and clears the AC field, **Then** no AC is displayed for that combatant.
|
|
3. **Given** a combatant has no AC, **When** the user edits the combatant and sets AC to 12, **Then** the shield icon and "12" appear next to the combatant's name.
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- What happens when AC is 0? The system displays the shield icon with "0" (AC 0 is a valid value in tabletop RPGs).
|
|
- What happens when AC is a very large number (e.g., 99)? The display accommodates up to two-digit values without layout issues.
|
|
- What happens when AC is negative? The system does not accept negative AC values; AC must be a non-negative integer.
|
|
|
|
## Requirements
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: The combatant data model MUST support an optional Armor Class field that holds a non-negative integer.
|
|
- **FR-002**: The system MUST allow users to set an AC value on any combatant via an inline input in the encounter list.
|
|
- **FR-003**: The system MUST allow users to edit the AC value for an existing combatant (add, change, or remove).
|
|
- **FR-004**: The encounter list MUST display each combatant's AC as a shield icon followed by the numeric value, positioned next to the combatant's name.
|
|
- **FR-005**: The encounter list MUST NOT display a shield icon or AC value for combatants without an AC set.
|
|
- **FR-006**: The system MUST persist AC values through the existing storage mechanism (same as other combatant fields).
|
|
- **FR-007**: AC values MUST be validated as non-negative integers (0 or greater).
|
|
|
|
### Key Entities
|
|
|
|
- **Combatant**: Gains an optional Armor Class attribute, a non-negative integer. Relates to existing combatant fields (name, initiative, HP).
|
|
|
|
## Success Criteria
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: Users can set an AC value for any combatant within the existing add/edit workflows with no additional steps beyond filling in the field.
|
|
- **SC-002**: AC values are visible at a glance in the encounter list without expanding or hovering over any element.
|
|
- **SC-003**: Combatants without AC display no visual clutter — the shield icon only appears when AC is set.
|
|
- **SC-004**: All existing functionality (HP tracking, initiative, turn navigation) continues to work without regression.
|
|
|
|
## Assumptions
|
|
|
|
- AC is always a non-negative integer (consistent with D&D 5e and most tabletop RPG systems).
|
|
- The shield icon is rendered using the project's existing icon library (Lucide React), not an emoji character.
|
|
- The AC display is read-only in the encounter list row; editing AC uses the existing combatant edit flow.
|
|
- MVP baseline does not include AC-based calculations (e.g., to-hit comparisons) or conditional formatting based on AC thresholds.
|