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
- 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.
- TypeScript-first — Always use TypeScript for type safety and IDE support
- Scene-based architecture — Each game screen is a Scene; keep them focused
- Vite bundling — Use the official
phaserjs/template-vite-ts template
- Composition over inheritance — Prefer composing behaviors over deep class hierarchies
- Data-driven design — Define levels, enemies, and configs in JSON/data files
- Event-driven communication — All cross-scene/system communication via EventBus
- 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';
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);
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:
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;
left = this.cursors.left.isDown || this.wasd.left.isDown;
right = this.cursors.right.isDown || this.wasd.right.isDown;
jump = Phaser
