Initial Commit
This commit is contained in:
139
openspec/changes/enterprise-gaming-react-game-hud/proposal.md
Normal file
139
openspec/changes/enterprise-gaming-react-game-hud/proposal.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# OpenSpec Change: enterprise-gaming-react-game-hud
|
||||
|
||||
- **Change ID**: enterprise-gaming-react-game-hud
|
||||
- **Package**: `@suaveplan/react-game-hud`
|
||||
- **Category**: gaming/react
|
||||
- **Target path**: `gaming/react/react-game-hud`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-game-hud.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/react-game-hud` on the genesis branch from scratch at enterprise quality. The package is a headless React layer for in-game HUD overlays: health bar, ammo counter, mini-map widget, objective tracker, kill-feed, and XP/level display. A `HudStateManager` aggregates state from `@suaveplan/combat`, `@suaveplan/weapons`, `@suaveplan/progression`, and `@suaveplan/quest` into a single typed store; `useHud()` exposes it via `useSyncExternalStore`. All component primitives are unstyled (className/style passthrough) for game-specific theming. Genesis adds Storybook stories for every component, Vitest DOM tests, structured errors, and 100% coverage.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis yet — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/combat` (`workspace:^`) | Health/shield state |
|
||||
| `@suaveplan/weapons` (`workspace:^`) | Ammo/reload state |
|
||||
| `@suaveplan/progression` (`workspace:^`) | XP/level state |
|
||||
| `@suaveplan/quest` (`workspace:^`) | Active objectives |
|
||||
| `@suaveplan/events` (`workspace:^`) | State update subscriptions |
|
||||
| `react` (`catalog:react`) | React 18 |
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
```ts
|
||||
interface HudState {
|
||||
health: number
|
||||
maxHealth: number
|
||||
shield: number
|
||||
maxShield: number
|
||||
armor: number
|
||||
ammo: number
|
||||
maxAmmo: number
|
||||
isReloading: boolean
|
||||
level: number
|
||||
xp: number
|
||||
xpToNext: number
|
||||
activeObjectives: ActiveObjective[]
|
||||
killFeed: KillFeedEntry[]
|
||||
}
|
||||
|
||||
function createHudStateManager(options: HudStateOptions): HudStateManager
|
||||
interface HudStateManager {
|
||||
getSnapshot(): HudState
|
||||
subscribe(cb: () => void): () => void
|
||||
update(partial: Partial<HudState>): void
|
||||
}
|
||||
|
||||
function useHud(): HudState
|
||||
|
||||
// Components (headless unstyled)
|
||||
function HealthBar(props: HealthBarProps): JSX.Element
|
||||
function AmmoDisplay(props: AmmoDisplayProps): JSX.Element
|
||||
function XpBar(props: XpBarProps): JSX.Element
|
||||
function ObjectiveList(props: ObjectiveListProps): JSX.Element
|
||||
function KillFeed(props: KillFeedProps): JSX.Element
|
||||
function HudOverlay(props: HudOverlayProps): JSX.Element // container
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
gaming/react/react-game-hud/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
types/common.ts
|
||||
types/common.md
|
||||
state/
|
||||
hud-state-manager.ts
|
||||
hud-state-manager.md
|
||||
hud-state-manager.test.ts
|
||||
hooks/
|
||||
use-hud.ts
|
||||
use-hud.md
|
||||
use-hud.test.ts
|
||||
components/
|
||||
health-bar/
|
||||
health-bar.tsx
|
||||
health-bar.md
|
||||
health-bar.test.tsx
|
||||
health-bar.stories.tsx
|
||||
index.ts
|
||||
ammo-display/
|
||||
ammo-display.tsx
|
||||
ammo-display.md
|
||||
ammo-display.test.tsx
|
||||
ammo-display.stories.tsx
|
||||
index.ts
|
||||
xp-bar/
|
||||
xp-bar.tsx
|
||||
xp-bar.md
|
||||
xp-bar.test.tsx
|
||||
xp-bar.stories.tsx
|
||||
index.ts
|
||||
objective-list/
|
||||
objective-list.tsx
|
||||
objective-list.md
|
||||
objective-list.test.tsx
|
||||
objective-list.stories.tsx
|
||||
index.ts
|
||||
kill-feed/
|
||||
kill-feed.tsx
|
||||
kill-feed.md
|
||||
kill-feed.test.tsx
|
||||
kill-feed.stories.tsx
|
||||
index.ts
|
||||
hud-overlay/
|
||||
hud-overlay.tsx
|
||||
hud-overlay.md
|
||||
hud-overlay.test.tsx
|
||||
hud-overlay.stories.tsx
|
||||
index.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: game apps compose HUD components over R3F canvas. Prerequisites: `@suaveplan/combat`, `@suaveplan/weapons`, `@suaveplan/progression`, `@suaveplan/quest`, `@suaveplan/events`, react.
|
||||
45
openspec/changes/enterprise-gaming-react-game-hud/tasks.md
Normal file
45
openspec/changes/enterprise-gaming-react-game-hud/tasks.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Tasks: enterprise-gaming-react-game-hud
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## Phase 1 — Scaffold
|
||||
|
||||
- [ ] Create `gaming/react/react-game-hud/` (`@suaveplan/react-game-hud`, `0.1.0`, `sideEffects: false`)
|
||||
- [ ] `tsconfig.json` (react), `vitest.config.ts`
|
||||
|
||||
## Phase 2 — Types
|
||||
|
||||
- [ ] `src/types/common.ts` + `common.md`
|
||||
|
||||
## Phase 3 — HUD state manager
|
||||
|
||||
- [ ] `src/state/hud-state-manager.ts` — getSnapshot/subscribe/update
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 4 — `useHud` hook
|
||||
|
||||
- [ ] `src/hooks/use-hud.ts` — `useSyncExternalStore` wrapper
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 5 — Components (each with test + story)
|
||||
|
||||
- [ ] `HealthBar` — health/shield visual with percentage
|
||||
- [ ] `AmmoDisplay` — current/max ammo, reload indicator
|
||||
- [ ] `XpBar` — XP progress with level display
|
||||
- [ ] `ObjectiveList` — active quest objectives, completion ticks
|
||||
- [ ] `KillFeed` — scrolling kill/death entries with TTL
|
||||
- [ ] `HudOverlay` — absolute-positioned container
|
||||
|
||||
## Phase 6 — Storybook
|
||||
|
||||
- [ ] Default + playground + edge-case stories for every component
|
||||
|
||||
## Phase 7 — Pre-publish gate
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-game-hud` green
|
||||
- [ ] 100% coverage
|
||||
- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/react-game-hud`
|
||||
Reference in New Issue
Block a user