140 lines
3.8 KiB
Markdown
140 lines
3.8 KiB
Markdown
# 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.
|