phaser

Phaser 3 Game Development

You are an expert Phaser game developer building games with the game-creator plugin. Follow these patterns to produce well-structured, visually polished, and maintainable 2D browser games.

Core Principles

1. Core loop first — Implement the minimum gameplay loop before any polish: boot → preload → create → update. Add the win/lose condition and scoring before visuals, audio, or juice. Keep initial scope small: 1 scene, 1 mechanic, 1 fail condition. Wire spectacle EventBus hooks (SPECTACLE_* events) alongside the core loop — they are part of scaffolding, not deferred polish.
2. TypeScript-first — Always use TypeScript for type safety and IDE support
3. Scene-based architecture — Each game screen is a Scene; keep them focused
4. Vite bundling — Use the official phaserjs/template-vite-ts template
5. Composition over inheritance — Prefer composing behaviors over deep class hierarchies
6. Data-driven design — Define levels, enemies, and configs in JSON/data files
7. Event-driven communication — All cross-scene/system communication via EventBus
8. Restart-safe — Gameplay must be fully restart-safe and deterministic. GameState.reset() must restore a clean slate. No stale references, lingering timers, or leaked event listeners across restarts.

Spectacle Events

Every player action and game event must emit at least one spectacle event. These hooks exist in the template EventBus — the design pass attaches visual effects to them.

Event	Constant	When to Emit
spectacle:entrance	SPECTACLE_ENTRANCE	In create() when the player/entities first appear on screen
spectacle:action	SPECTACLE_ACTION	On every player input (tap, jump, shoot, swipe)
spectacle:hit	SPECTACLE_HIT	When player hits/destroys an enemy, collects an item, or scores
spectacle:combo	SPECTACLE_COMBO	When consecutive hits/scores happen without a miss. Pass { combo: n }
spectacle:streak	SPECTACLE_STREAK	When combo reaches milestones (5, 10, 25, 50). Pass { streak: n }
spectacle:near_miss	SPECTACLE_NEAR_MISS	When player narrowly avoids danger (within ~20% of collision radius)

Rule: If a gameplay moment has no spectacle event, add one. The design pass cannot polish what it cannot hook into.

Mandatory Conventions

All games MUST follow the game-creator conventions:

• core/ directory with EventBus, GameState, and Constants
• EventBus singleton — domain:action event naming, no direct scene references
• GameState singleton — Centralized state with reset() for clean restarts
• Constants file — Every magic number, color, speed, and config value — zero hardcoded values
• Scene cleanup — Remove EventBus listeners in shutdown()

See conventions.md for full details and code examples.

Project Setup

Use the official Vite + TypeScript template as your starting point:

npx degit phaserjs/template-vite-ts my-game
cd my-game && npm install

Required Directory Structure

src/
├── core/
│   ├── EventBus.ts        # Singleton event bus + event constants
│   ├── GameState.ts       # Centralized state with reset()
│   └── Constants.ts       # ALL config values
├── scenes/
│   ├── Boot.ts            # Minimal setup, start Game scene
│   ├── Preloader.ts       # Load all assets, show progress bar
│   ├── Game.ts            # Main gameplay (starts immediately, no title screen)
│   └── GameOver.ts        # End screen with restart
├── objects/               # Game entities (Player, Enemy, etc.)
├── systems/               # Managers and subsystems
├── ui/                    # UI components (buttons, bars, dialogs)
├── audio/                 # Audio manager, music, SFX
├── config.ts              # Phaser.Types.Core.GameConfig
└── main.ts                # Entry point

See project-setup.md for full config and tooling details.

Scene Architecture

• Lifecycle: init() → preload() → create() → update(time, delta)
• Use init() for receiving data from scene transitions
• Load assets in a dedicated Preloader scene, not in every scene
• Keep update() lean — delegate to subsystems and game objects
• No title screen by default — boot directly into gameplay. Only add a title/menu scene if the user explicitly asks for one
• No in-game score HUD — the Play.fun widget displays score in a deadzone at the top of the game. Do not create a separate UIScene or HUD overlay for score display
• Use parallel scenes for UI overlays (pause menu) only when requested

Play.fun Safe Zone

When games run inside the Play.fun dashboard on mobile Safari, the SDK sets CSS custom properties on the game iframe's document.documentElement:

• --ogp-safe-top-inset — space below the Play.fun header bubbles (~68px on mobile)
• --ogp-safe-bottom-inset — space above Safari bottom controls (~148px on mobile)

Both default to 0px when not running inside the dashboard (desktop, standalone).

The template's Constants.js reads these at boot and exposes SAFE_ZONE.TOP and SAFE_ZONE.BOTTOM in canvas pixels (CSS value × DPR). A static fallback (GAME.HEIGHT * 0.08) ensures the top safe zone works even without the SDK.

Rules:

• All UI text, buttons, and HUD elements must be positioned below SAFE_ZONE.TOP and above GAME.HEIGHT - SAFE_ZONE.BOTTOM
• Gameplay entities should not spawn in the safe zone areas
• The game-over screen, score panels, and restart buttons must offset from both SAFE_ZONE.TOP and SAFE_ZONE.BOTTOM
• Use const usableH = GAME.HEIGHT - SAFE_ZONE.TOP - SAFE_ZONE.BOTTOM for calculating proportional positions in UI scenes
• Game canvas and backgrounds should fill the full viewport (bleed behind browser chrome)
• Touch controls at the bottom must account for SAFE_ZONE.BOTTOM

import { SAFE_ZONE } from '../core/Constants.js';

// In any UI scene:
const safeTop = SAFE_ZONE.TOP;
const safeBottom = SAFE_ZONE.BOTTOM;
const usableH = GAME.HEIGHT - safeTop - safeBottom;
const title = this.add.text(cx, safeTop + usableH * 0.15, 'GAME OVER', { ... });
const button = createButton(scene, cx, safeTop + usableH * 0.6, 'PLAY AGAIN', callback);

// Touch controls / bottom HUD:
const bottomY = GAME.HEIGHT - safeBottom - 40 * PX;

How it works in Constants.js:

function _readSafeInsets() {
  const s = getComputedStyle(document.documentElement);
  const top = parseInt(s.getPropertyValue('--ogp-safe-top-inset')) || 0;
  const bottom = parseInt(s.getPropertyValue('--ogp-safe-bottom-inset')) || 0;
  return { top: top * DPR, bottom: bottom * DPR };
}
const _insets = _readSafeInsets();

export const SAFE_ZONE = {
  TOP: Math.max(GAME.HEIGHT * 0.08, _insets.top),
  BOTTOM: _insets.bottom,
  LEFT: 0,
  RIGHT: 0,
};

• Communicate between scenes via EventBus (not direct references)

See scenes-and-lifecycle.md for patterns and examples.

Game Objects

• Extend Phaser.GameObjects.Sprite (or other base classes) for custom objects
• Use Phaser.GameObjects.Group for object pooling (bullets, coins, enemies)
• Use Phaser.GameObjects.Container for composite objects, but avoid deep nesting
• Register custom objects with GameObjectFactory for scene-level access

See game-objects.md for implementation patterns.

Physics

• Arcade Physics — Use for simple games (platformers, top-down). Fast and lightweight.
• Matter.js — Use when you need realistic collisions, constraints, or complex shapes.
• Never mix physics engines in the same game.
• Use the state pattern for character movement (idle, walk, jump, attack).

See physics-and-movement.md for details.

Performance (Critical Rules)

• Use texture atlases — Pack sprites into atlases, never load individual images at scale
• Object pooling — Use Groups with maxSize; recycle with setActive(false) / setVisible(false)
• Minimize update work — Only iterate active objects; use getChildren().filter(c => c.active)
• Camera culling — Enable for large worlds; off-screen objects skip rendering
• Batch rendering — Fewer unique textures per frame = better draw call batching
• Mobile — Reduce particle counts, simplify physics, consider 30fps target
• pixelArt: true — Enable in game config for pixel art games (nearest-neighbor scaling)

See assets-and-performance.md for full optimization guide.

Advanced Patterns

• ECS with bitECS — Entity Component System for data-oriented design (used internally by Phaser 4)
• State machines — Manage entity behavior states cleanly
• Singleton managers — Cross-scene services (audio, save data, analytics)
• Event bus — Decouple systems with a shared EventEmitter
• Tiled integration — Use Tiled map editor for level design

See patterns.md for implementations.

Mobile Input Strategy (60/40 Rule)

All games MUST work on desktop AND mobile unless explicitly specified otherwise. Focus 60% mobile / 40% desktop for tradeoffs. Pick the best mobile input for each game concept:

Game Type	Primary Mobile Input	Desktop Input
Platformer	Tap left/right half + tap-to-jump	Arrow keys / WASD
Runner/endless	Tap / swipe up to jump	Space / Up arrow
Puzzle/match	Tap targets (44px min)	Click
Shooter	Virtual joystick + tap-to-fire	Mouse + WASD
Top-down	Virtual joystick	Arrow keys / WASD

Implementation Pattern

Abstract input into an inputState object so game logic is source-agnostic:

// In Scene update():
const isMobile = this.sys.game.device.os.android ||
  this.sys.game.device.os.iOS || this.sys.game.device.os.iPad;

let left = false, right = false, jump = false;

// Keyboard
left = this.cursor

---

*Content truncated.*