# Feature Specification: Player Character Management **Feature Branch**: `005-player-characters` **Created**: 2026-03-12 **Status**: Draft **Input**: User description: "Allow users to create and manage Player characters via the bottom bar. Each player character has a name, AC, max HP, a chosen color, and a preset icon. Player characters persist across sessions and are searchable when adding combatants to an encounter. A dedicated management view lets users edit and delete existing player characters." ## User Scenarios & Testing *(mandatory)* ### Creating Player Characters **Story PC-1 — Create a new player character (Priority: P1)** A game master opens a "Create Player" modal from the bottom bar and fills in the character's name, AC, max HP, selects a color from a palette, and picks an icon from a preset grid. On saving, the player character is persisted and available for future encounters. **Why this priority**: Creating player characters is the foundational action — nothing else in this feature works without it. **Independent Test**: Can be fully tested by creating a player character and verifying it appears in the saved player list. **Acceptance Scenarios**: 1. **Given** the bottom bar is visible, **When** the user clicks the "Create Player" icon button, **Then** a modal opens with fields for Name, AC, Max HP, a color palette, and an icon selection grid. 2. **Given** the create player modal is open, **When** the user fills in Name "Aragorn", AC 16, Max HP 120, selects the color green, and selects the shield icon, **Then** clicking save creates a player character with those attributes and closes the modal. 3. **Given** no player characters exist, **When** the user creates their first player character, **Then** it is persisted and appears in the player character list. 4. **Given** the create player modal is open, **When** the user submits with an empty name, **Then** a validation error is shown and the player character is not created. 5. **Given** the create player modal is open, **When** the user submits with a whitespace-only name, **Then** a validation error is shown and the player character is not created. 6. **Given** the create player modal is open, **When** the user clicks cancel or closes the modal, **Then** no player character is created and any entered data is discarded. --- ### Player Character Persistence **Story PC-2 — Player characters survive page reload (Priority: P1)** Player characters are long-lived entities that persist across browser sessions. Unlike encounter combatants which belong to a single encounter, player characters represent recurring party members that the GM reuses across many encounters. **Why this priority**: Without persistence, users would need to recreate their party every session, defeating the purpose. **Independent Test**: Can be tested by creating a player character, reloading the page, and verifying it still exists. **Acceptance Scenarios**: 1. **Given** the user has created player characters, **When** the page is reloaded, **Then** all player characters are restored with their name, AC, max HP, color, and icon intact. 2. **Given** saved player character data is corrupt or malformed, **When** the page loads, **Then** the application starts with an empty player character list without crashing. 3. **Given** no saved player character data exists, **When** the page loads, **Then** the application starts with an empty player character list. --- ### Adding Player Characters to Encounters **Story PC-3 — Search and add player characters as combatants (Priority: P1)** When adding combatants to an encounter, the GM can search for their saved player characters by name. Selecting a player character adds it as a combatant with its saved stats (AC, max HP) pre-filled, along with its color and icon for visual identification. **Why this priority**: This is the core value proposition — reusing pre-configured characters instead of re-entering stats every encounter. **Independent Test**: Can be tested by creating a player character, then adding it to an encounter via the combatant search. **Acceptance Scenarios**: 1. **Given** player characters "Aragorn" and "Legolas" exist, **When** the user types "Ara" in the combatant search field, **Then** "Aragorn" appears in the search results alongside bestiary creatures. 2. **Given** player character "Aragorn" (AC 16, Max HP 120) exists, **When** the user selects "Aragorn" from search results, **Then** a combatant is added to the encounter with name "Aragorn", AC 16, max HP 120, current HP 120, and the player character's color and icon. 3. **Given** player character "Gandalf" exists, **When** the user adds "Gandalf" to two separate encounters (or the same encounter twice), **Then** each combatant is an independent copy — modifying one combatant's HP does not affect the other or the saved player character. 4. **Given** no player characters exist, **When** the user searches in the combatant search field, **Then** only bestiary creatures appear in results (no empty "Players" section is shown). --- ### Displaying Player Characters in Encounters **Story PC-4 — Visual distinction for player character combatants (Priority: P2)** Combatants originating from player characters display their chosen color and icon next to their name in the combatant row, making it easy to visually distinguish PCs from monsters at a glance. **Why this priority**: Color and icon display enhances usability but the feature is functional without it. **Independent Test**: Can be tested by adding a player character to an encounter and verifying the color and icon render in the combatant row. **Acceptance Scenarios**: 1. **Given** a combatant was added from a player character with color green and the shield icon, **When** the combatant row is rendered, **Then** the player character's icon is displayed next to the name and the color is applied as a visual accent (e.g., colored border, background tint, or icon tint). 2. **Given** a combatant was added from the bestiary (not a player character), **When** the combatant row is rendered, **Then** no player character icon or color accent is shown. --- ### Managing Player Characters **Story PC-5 — View all saved player characters (Priority: P2)** The GM can access a dedicated management view to see all their saved player characters at a glance, with each character's name, AC, max HP, color, and icon displayed. **Why this priority**: Management view is needed for editing and deleting, but basic create/add flow works without it. **Independent Test**: Can be tested by creating several player characters and opening the management view to verify all are listed. **Acceptance Scenarios**: 1. **Given** player characters exist, **When** the user opens the player character management view, **Then** all saved player characters are listed showing their name, AC, max HP, color, and icon. 2. **Given** no player characters exist, **When** the user opens the management view, **Then** an empty state message is shown encouraging the user to create their first player character. --- **Story PC-6 — Edit an existing player character (Priority: P2)** The GM realizes a player character's stats have changed (e.g., level up) or wants to fix a typo. They open the management view and edit the character's attributes. **Why this priority**: Editing is important for ongoing campaigns but the feature delivers value without it initially. **Independent Test**: Can be tested by editing a player character's name and stats and verifying the changes persist. **Acceptance Scenarios**: 1. **Given** player character "Aragorn" exists, **When** the user edits "Aragorn" to change the name to "Strider" and AC to 18, **Then** the changes are saved and reflected in the player character list. 2. **Given** a player character is being edited, **When** the user submits with an empty name, **Then** a validation error is shown and the changes are not saved. 3. **Given** a player character is being edited, **When** the user cancels the edit, **Then** the original values are preserved. 4. **Given** a player character was previously added to an encounter as a combatant, **When** the player character is edited, **Then** existing combatants in the current encounter are not affected (they are independent copies). --- **Story PC-7 — Delete a player character (Priority: P2)** The GM no longer needs a player character and wants to remove it from their saved list. **Why this priority**: Deletion keeps the list manageable but is not needed for core functionality. **Independent Test**: Can be tested by deleting a player character and verifying it no longer appears in the list or search results. **Acceptance Scenarios**: 1. **Given** player character "Boromir" exists, **When** the user deletes "Boromir" with confirmation, **Then** the player character is removed from the saved list. 2. **Given** player character "Boromir" was previously added to the current encounter as a combatant, **When** the player character is deleted, **Then** the combatant in the encounter is not affected (it is an independent copy). 3. **Given** the delete action is initiated, **When** the user is asked to confirm, **Then** the confirmation follows the existing ConfirmButton two-step pattern (as defined in spec 001). --- ### Edge Cases - **Duplicate player character names**: Permitted. Player characters are identified by a unique internal ID, not by name. - **Adding the same player character to an encounter multiple times**: Each addition creates an independent combatant copy. Multiple copies of the same PC in one encounter are allowed. - **Editing a player character while it is also a combatant in the active encounter**: The active combatant is not affected; only future additions use the updated stats. - **Deleting a player character while it is a combatant in the active encounter**: The combatant remains in the encounter unchanged. - **Very long player character names**: The UI should truncate or ellipsize names that exceed the available space. - **Browser storage quota exceeded**: Player character persistence silently fails; the current in-memory session continues. - **Corrupt player character data on load**: The application discards corrupt data and starts with an empty player character list. - **Color/icon rendering on different screen sizes**: Color and icon must remain visible and distinguishable at all supported viewport sizes. - **Search ranking**: When searching, player characters should appear in a distinct group (e.g., "Players" section) above or alongside bestiary results to make them easy to find. --- ## Requirements *(mandatory)* ### Functional Requirements #### FR-001 — Create: Modal via bottom bar The system MUST provide an icon button in the bottom bar that opens a "Create Player" modal. #### FR-002 — Create: Required fields The create modal MUST include fields for Name (text), AC (number), and Max HP (number). #### FR-003 — Create: Color selection The create modal MUST include a color palette allowing the user to select one color from a predefined set of distinguishable colors. #### FR-004 — Create: Icon selection The create modal MUST include a grid of ~10-20 preset icons (e.g., sword, shield, skull, heart, wand) from which the user selects one. #### FR-005 — Create: Name validation Creating a player character MUST reject empty or whitespace-only names, showing a validation error. #### FR-006 — Create: Unique identity Each player character MUST be assigned a unique internal identifier on creation. #### FR-007 — Persistence: Cross-session storage Player characters MUST be persisted to browser storage and restored on page load. #### FR-008 — Persistence: Independent from encounter storage Player character storage MUST be separate from encounter storage — clearing an encounter does not affect saved player characters. #### FR-009 — Persistence: Graceful degradation The system MUST NOT crash when player character data is missing, corrupt, or storage is unavailable. It MUST fall back to an empty player character list. #### FR-010 — Search: Player characters in combatant search Player characters MUST appear in the combatant search results when the user searches for combatants to add to an encounter. Matching is by name substring. #### FR-011 — Search: Distinct grouping Player character results MUST be visually distinguishable from bestiary creature results in the search dropdown. #### FR-012 — Add to encounter: Pre-filled stats When a player character is added to an encounter as a combatant, the combatant MUST be created with the player character's name, AC, max HP, and current HP set to max HP. #### FR-013 — Add to encounter: Color and icon association When a combatant is created from a player character, the combatant MUST carry the player character's color and icon for display purposes. #### FR-014 — Add to encounter: Independent copy Combatants created from player characters MUST be independent copies. Changes to the combatant's stats during an encounter do not modify the saved player character, and vice versa. #### FR-015 — Display: Color and icon in combatant row Combatant rows for player-character-originating combatants MUST display the chosen icon and color accent. #### FR-016 — Management: View all player characters The system MUST provide a view listing all saved player characters with their name, AC, max HP, color, and icon. #### FR-017 — Management: Edit player character The system MUST allow editing a player character's name, AC, max HP, color, and icon. Edits MUST be persisted. #### FR-018 — Management: Delete player character The system MUST allow deleting a player character with two-step confirmation (ConfirmButton pattern from spec 001). #### FR-019 — Management: Delete does not affect active combatants Deleting a player character MUST NOT remove or modify any combatants currently in an encounter. ### Key Entities - **PlayerCharacter**: A persistent, reusable character template with a unique `PlayerCharacterId` (branded string), required `name`, `ac` (number), `maxHp` (number), `color` (string from predefined set), and `icon` (string identifier from preset icon set). - **PlayerCharacterStore** (port): Interface for loading, saving, and deleting player characters. Implemented as a browser storage adapter. --- ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Users can create a player character with name, AC, max HP, color, and icon in under 30 seconds. - **SC-002**: Player characters persist across page reloads with all attributes intact. - **SC-003**: Player characters appear in combatant search results and can be added to an encounter in a single selection. - **SC-004**: Combatants created from player characters display their color and icon in the initiative tracker. - **SC-005**: Users can edit any attribute of a saved player character and see the change persisted immediately. - **SC-006**: Deleting a player character requires two deliberate user interactions (ConfirmButton pattern) and does not affect active encounter combatants. - **SC-007**: All player character domain operations (create, edit, delete) are pure functions with no I/O, consistent with the project's deterministic domain core. - **SC-008**: The player character domain module has zero imports from application, adapter, or UI layers. - **SC-009**: Corrupt or missing player character data never causes a crash — the application gracefully falls back to an empty player character list. --- ## Assumptions - Player character IDs are generated by the caller (application layer), keeping domain functions pure. - The predefined color palette contains 8-12 visually distinct colors suitable for both light and dark backgrounds. - The preset icon set uses Lucide React icons already available in the project, requiring no additional icon dependencies. - Player characters are stored in a separate `localStorage` key from encounter data. - Name validation trims whitespace; a name that is empty after trimming is invalid. - Duplicate player character names are permitted — characters are distinguished by their unique ID. - MVP baseline does not include importing/exporting player characters. - MVP baseline does not include player-character-specific fields beyond name, AC, max HP, color, and icon (e.g., no class, level, or ability scores). - MVP baseline does not include reordering player characters in the management view. - The management view is accessible from the bottom bar or a dedicated UI affordance, separate from the encounter view. - When a player character is added to an encounter, a snapshot of its current stats is copied — future edits to the player character do not retroactively update existing combatants.