49 lines
2.7 KiB
Markdown
49 lines
2.7 KiB
Markdown
# Quickstart: Combatant HP Tracking
|
|
|
|
**Feature**: 009-combatant-hp | **Date**: 2026-03-05
|
|
|
|
## Overview
|
|
|
|
This feature adds optional health point (HP) tracking to combatants. Each combatant can optionally have a max HP and current HP. Both HP fields are always visible per combatant row (current HP disabled until max HP is set). The current HP is adjusted via +/- controls or direct entry, always clamped to [0, maxHp]. When max HP changes and the combatant is at full health, current HP stays synced.
|
|
|
|
## Implementation Order
|
|
|
|
1. **Domain types** — Extend `Combatant` interface with optional `maxHp` and `currentHp`. Add new event types to `events.ts`.
|
|
|
|
2. **Domain functions** — Implement `setHp` (set/clear max HP) and `adjustHp` (apply delta to current HP) as pure functions following the existing pattern in `edit-combatant.ts`.
|
|
|
|
3. **Domain tests** — Write tests for both domain functions covering acceptance scenarios, invariants, error cases, and edge cases.
|
|
|
|
4. **Application use cases** — Create `setHpUseCase` and `adjustHpUseCase` following the existing get-call-save pattern.
|
|
|
|
5. **Persistence** — Extend `loadEncounter()` validation to handle optional `maxHp`/`currentHp` fields on combatants.
|
|
|
|
6. **Web hook** — Add `setHp` and `adjustHp` callbacks to `useEncounter`.
|
|
|
|
7. **UI components** — Add HP controls to combatant rows in `App.tsx`: both Current HP and Max HP inputs always visible (Current HP disabled until Max HP is set), +/- buttons shown only when HP tracking is active, direct current HP entry.
|
|
|
|
## Key Files to Modify
|
|
|
|
| File | Change |
|
|
|------|--------|
|
|
| `packages/domain/src/types.ts` | Add optional `maxHp` and `currentHp` to `Combatant` |
|
|
| `packages/domain/src/events.ts` | Add `MaxHpSet` and `CurrentHpAdjusted` event types |
|
|
| `packages/domain/src/set-hp.ts` | New file: pure function for setting max HP |
|
|
| `packages/domain/src/adjust-hp.ts` | New file: pure function for adjusting current HP |
|
|
| `packages/domain/src/index.ts` | Re-export new functions |
|
|
| `packages/application/src/set-hp-use-case.ts` | New file: set HP use case |
|
|
| `packages/application/src/adjust-hp-use-case.ts` | New file: adjust HP use case |
|
|
| `packages/application/src/index.ts` | Re-export new use cases |
|
|
| `apps/web/src/hooks/use-encounter.ts` | Add setHp/adjustHp callbacks |
|
|
| `apps/web/src/persistence/encounter-storage.ts` | Validate HP fields on load |
|
|
| `apps/web/src/App.tsx` | HP controls in combatant rows |
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
pnpm test # Run all tests
|
|
pnpm vitest run packages/domain/src/__tests__/set-hp.test.ts # Single test
|
|
pnpm check # Full quality gate
|
|
pnpm --filter web dev # Dev server
|
|
```
|