104 lines
2.7 KiB
Markdown
104 lines
2.7 KiB
Markdown
# OpenSpec Change: enterprise-gaming-react-game-map
|
|
|
|
- **Change ID**: enterprise-gaming-react-game-map
|
|
- **Package**: `@suaveplan/react-game-map`
|
|
- **Category**: gaming/react
|
|
- **Target path**: `gaming/react/react-game-map`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-game-map.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/react-game-map` on the genesis branch from scratch at enterprise quality. The package provides headless state management for 2D world maps in games. A `MapStateManager` tracks the world-space viewport, entity marker positions, fog-of-war revealed cells, custom icons, and overlays; `useGameMap()` exposes it via `useSyncExternalStore`. Canvas rendering helpers paint the background tile layer, entity markers, and fog-of-war cells. Storybook stories demonstrate a scrollable interactive map with entity tracking. Genesis adds typed schemas, 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/error` (`workspace:^`) | `GameMapError` |
|
|
| `@suaveplan/events` (`workspace:^`) | Entity position update subscriptions |
|
|
| `react` (`catalog:react`) | React 18 |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
interface MapState {
|
|
viewport: { x: number; y: number; zoom: number }
|
|
markers: MapMarker[]
|
|
fogCells: Set<string> // "cx,cy" revealed cell keys
|
|
overlays: MapOverlay[]
|
|
}
|
|
|
|
interface MapMarker {
|
|
id: string
|
|
x: number; y: number
|
|
icon: string
|
|
label?: string
|
|
color?: string
|
|
}
|
|
|
|
function createMapStateManager(options: MapStateOptions): MapStateManager
|
|
function useGameMap(): MapState
|
|
|
|
// Components
|
|
function GameMapCanvas(props: GameMapCanvasProps): JSX.Element
|
|
function MapMarkerLayer(props: MapMarkerLayerProps): JSX.Element
|
|
function FogOfWarLayer(props: FogOfWarLayerProps): JSX.Element
|
|
function MiniMap(props: MiniMapProps): JSX.Element
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
gaming/react/react-game-map/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
types/common.ts
|
|
types/common.md
|
|
state/
|
|
map-state-manager.ts
|
|
map-state-manager.md
|
|
map-state-manager.test.ts
|
|
hooks/
|
|
use-game-map.ts
|
|
use-game-map.md
|
|
use-game-map.test.ts
|
|
components/
|
|
game-map-canvas/
|
|
game-map-canvas.tsx
|
|
game-map-canvas.md
|
|
game-map-canvas.test.tsx
|
|
game-map-canvas.stories.tsx
|
|
index.ts
|
|
mini-map/
|
|
mini-map.tsx
|
|
mini-map.md
|
|
mini-map.test.tsx
|
|
mini-map.stories.tsx
|
|
index.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: composed with `@suaveplan/r3f-minimap` for 3D map overlay. Prerequisites: `@suaveplan/error`, `@suaveplan/events`, react.
|