106 lines
4.4 KiB
Markdown
106 lines
4.4 KiB
Markdown
# 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.
|
|
- *Keep files short and focused**: Each file should have a single responsibility, and not exceed 200 lines.
|
|
|
|
## 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 |