Add game architecture patterns documentation
Document layered architecture, spawner patterns, reactive UI state, and tween interruption for framework users. Includes best practices and common pitfalls to avoid. docs: add architecture patterns documentation Provide a reference guide for implementing board games with the framework. Covers layered architecture, reactive scenes, spawner patterns, UI state management, and common development pitfalls.
This commit is contained in:
parent
23575dd516
commit
eefcef861a
|
|
@ -0,0 +1,105 @@
|
|||
# Game Architecture Patterns & Practices
|
||||
|
||||
> Reference guide for implementing board games using `boardgame-phaser` framework.
|
||||
> Explore `packages/onitama-game/` and `packages/sample-game/` for concrete implementations.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
Games follow a layered architecture separating logic, presentation, and UI state:
|
||||
|
||||
```
|
||||
packages/my-game/
|
||||
├── src/
|
||||
│ ├── game/ # Pure game logic (re-exported from boardgame-core)
|
||||
│ ├── scenes/ # Phaser scenes (MenuScene, GameScene)
|
||||
│ ├── spawners/ # Data-driven object lifecycle
|
||||
│ ├── renderers/ # Renderers for game objects
|
||||
│ ├── state/ # UI-only reactive state
|
||||
│ ├── config.ts # Centralized layout & style constants
|
||||
│ └── ui/App.tsx # Preact root component
|
||||
```
|
||||
|
||||
| Layer | Responsibility |
|
||||
|-------|----------------|
|
||||
| `game/` | State, commands, prompts, validation (pure logic) |
|
||||
| `scenes/` | Phaser lifecycle, input handling, visual composition |
|
||||
| `spawners/` | Reactive game object spawn/update/despawn |
|
||||
| `renderers/` | Phaser visual representation of game objects |
|
||||
| `state/` | UI-only reactive state (selection, hover, etc.) |
|
||||
| `ui/` | Preact components bridging Phaser and DOM |
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### 1. ReactiveScene / GameHostScene
|
||||
Extend `ReactiveScene`(`packages\framework\src\scenes\ReactiveScene.ts`) to use reactive integration features.
|
||||
- Access game context for scene navigation
|
||||
- Use `this.disposables` for auto-cleanup on shutdown.
|
||||
|
||||
### 2. Spawner Pattern
|
||||
Implement `Spawner<TData, TObj>` for data-driven objects.
|
||||
- `*getData()`: Yield objects that should exist.
|
||||
- `getKey()`: Unique identifier for diffing.
|
||||
- `onSpawn()`: Create Phaser objects.
|
||||
- `onUpdate()`: Handle data changes (animate if needed).
|
||||
- `onDespawn()`: Clean up with optional animation.
|
||||
- See: `packages/onitama-game/src/spawners/`
|
||||
|
||||
### 3. Reactive UI State
|
||||
Use `MutableSignal` for UI-only state, separate from game state.
|
||||
- Mutate via `.produce()`.
|
||||
- React via `effect()` from `@preact/signals-core`.
|
||||
- Clean up effects on object `'destroy'` to prevent leaks.
|
||||
- See: `packages/onitama-game/src/state/ui.ts`
|
||||
|
||||
### 4. Custom Containers
|
||||
Extend `Phaser.GameObjects.Container` to encapsulate visuals and state.
|
||||
- Store logical state as private signals.
|
||||
- Use `effect()` for reactive highlights/selections.
|
||||
|
||||
### 5. Tween Interruption
|
||||
Always register state-related tweens: `this.scene.addTweenInterruption(tween)`.
|
||||
Prevents visual glitches when game state changes mid-animation.
|
||||
|
||||
### 6. Scene Navigation
|
||||
Use `await this.sceneController.launch('SceneKey')`.
|
||||
Register scenes in `App.tsx` via `<PhaserScene>`. Pass data via `data` prop.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Centralize Config**: Keep `CELL_SIZE`, `BOARD_OFFSET`, colors, etc., in `src/config.ts` with `as const`. Avoid magic numbers.
|
||||
- **Type Imports**: Use `import type { Foo } from 'bar'` for type-only imports.
|
||||
- **Input Handling**: Use `this.add.zone()` for grid/cell-based input zones.
|
||||
- **Cleanup**: Always dispose `effect()` on `'destroy'`. Use `this.disposables.add()` for scene-level resources.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
| Pitfall | Solution |
|
||||
|---------|----------|
|
||||
| Duplicate constants across files | Export from single `config.ts` or shared spawner |
|
||||
| Missing tween interruptions | Always call `addTweenInterruption()` |
|
||||
| Effect memory leaks | `this.on('destroy', () => dispose())` |
|
||||
| Hardcoded magic numbers | Extract to `src/config.ts` |
|
||||
| UI state staleness | Clear related selections on state change |
|
||||
|
||||
## Testing
|
||||
Add Vitest for UI state transitions, coordinate conversions, and spawner logic.
|
||||
See `packages/framework/` for test setup examples.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Pattern | Purpose |
|
||||
|---------|---------|
|
||||
| `GameHostScene` | Connect Phaser to game host |
|
||||
| `Spawner<T, TObj>` | Reactive object lifecycle |
|
||||
| `MutableSignal` | UI-only reactive state |
|
||||
| `effect()` | React to signal changes in Phaser objects |
|
||||
| `addTweenInterruption()` | Prevent animation race conditions |
|
||||
| `sceneController.launch()` | Navigate between scenes |
|
||||
| `spawnEffect()` | Register spawners |
|
||||
| `this.disposables.add()` | Auto-cleanup resources |
|
||||
|
||||
## Related Documents
|
||||
- `AGENTS.md` — Project overview, commands, and code style
|
||||
- `docs/GameModule.md` — GameModule implementation guide
|
||||
- `packages/framework/src/` — `boardgame-phaser` source code
|
||||
- `packages/onitama-game/src/` — Complete game implementation reference
|
||||
Loading…
Reference in New Issue