# Phaser Development

> Best practices for building performant 2D web games with Phaser 3, React integration, and TypeScript.

- Skill: `involvex/phaser-development` (Agent Skill)
- Install (CLI): `npx skillmds@latest add involvex/phaser-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/involvex/phaser-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: involvex (https://skillmd.com/u/involvex)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/involvex/phaser-development

---


# Phaser 3 Development Guide

Phaser 3 is a fast, free, and open-source HTML5 game framework. This skill provides guidance for architecting complex 2D games, specifically integrated with modern React/TypeScript stacks.

## Core Concepts

### 1. The Game Instance
Always manage the game instance lifecycle. In React, use `useRef` for the container and `useEffect` to initialize/destroy.
```tsx
const gameRef = useRef<HTMLDivElement>(null);
useEffect(() => {
  const config = { ... };
  const game = new Phaser.Game(config);
  return () => game.destroy(true);
}, []);
```

### 2. Scenes
Scenes are the building blocks. Use multiple scenes for overlays (UI, Hud).
- `preload()`: Load assets (images, audio, json).
- `create()`: Initialize objects, input, and animations.
- `update(time, delta)`: Main game loop logic.

### 3. GameObjects
- **Sprites/Images**: Textured objects.
- **Shapes (Arc, Rectangle)**: Useful for UI and placeholders.
- **Text**: Digital typography. Always use `String(value)` for numbers to satisfy strict linting.

### 4. Input & Interactivity
Enable interactivity via `.setInteractive()`.
```javascript
object.setInteractive().on('pointerdown', (pointer) => {
  // Handle click/touch
});
```

### 5. Tweens & Animations
Use Tweens for smooth transitions instead of manual `update` math where possible.
```javascript
scene.tweens.add({
  targets: object,
  alpha: 0,
  duration: 1000,
  onComplete: () => object.destroy()
});
```

## React Integration Patterns

### Bridging Game & React State
Pass callbacks from React props to the Phaser Scene via the scene `init` or `data` parameter.
```tsx
const PhaserGame = ({ onEvent }) => {
  useEffect(() => {
      class MyScene extends Phaser.Scene {
          create() {
              this.events.on('custom-event', onEvent);
          }
      }
  }, [onEvent]);
};
```

## Performance & Mobile Optimization
1. **Resolution**: Use `scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH }`.
2. **Texture Atlases**: Combine images to reduce draw calls.
3. **Destruction**: Always cleanup objects in `onComplete` or Scene `shutdown`.
4. **Input**: Use `input.setPollAlways()` for smoother mouse tracking if needed, but be mindful of CPU.

## TypeScript Best Practices
- Define interfaces for `SceneData`.
- Use specific types for GameObjects (e.g., `Phaser.GameObjects.Sprite`).
- Avoid `any` in scene events by typing the event emitter.