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.

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().

object.setInteractive().on('pointerdown', (pointer) => {
  // Handle click/touch
});

5. Tweens & Animations

Use Tweens for smooth transitions instead of manual update math where possible.

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.

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.