gamedev-skills/awesome-gamedev-agent-skills / skills/web-engines/phaser-core
phaser-core
VerifiedSets up and debugs Phaser 4 games (and pinned Phaser 3.90): Game config, Scene lifecycle, the loader, scene transitions and Phaser 3 to 4 migration. Use when code imports phaser, or on a black screen, assets undefined in create, or a HUD scene behind the game. Not for colliders (`phaser-arcade-physics`), HUD layout (`game-ui-ux`) or PixiJS (`pixijs-rendering`).
Phaser 4 core
Builds the foundation of a Phaser game: one Phaser.Game, a scene per screen, assets loaded
per scene into a global cache, and a clear split between game rules and the scenes that draw
them. New projects target Phaser 4.2. A project pinned to Phaser 3.90 stays on 3.x unless
the user asks for a migration.
When to use
- Starting a Phaser game, structuring scenes, loading assets, wiring cameras, passing data between scenes, or porting Phaser 3 code to Phaser 4.
- The project has
phaserinpackage.json,import Phaser from 'phaser', or classes that extendPhaser.Scene. - Not for bodies, colliders and movement (
phaser-arcade-physics), Matter.js physics, or engine-neutral menu and HUD design (game-ui-ux; load it next to this skill for UI work).
Workflow
- Read the installed major. Check
package.jsonand the lockfile. Phaser 3 and 4 share the scene model but not the renderer, so a v3 snippet can run and still look wrong in v4. - Keep rules out of scenes. Put state and rules (score, turns, inventory, AI) in plain
modules with no Phaser import. A scene reads that state, draws it, and sends input actions
back. The rules then run under
node --testwithout a browser, and a restart is just new state. - Create one game from a config with
type: Phaser.AUTO, a size, ascalemode and ascenearray. The first scene in the array (and any withactive: true) starts on boot. - One
Scenesubclass per screen with a unique key. Reset run state ininit(), queue assets inpreload(), build objects increate(), step inupdate(time, delta). - Move between screens with the right verb (
start,launch,run,switch,sleep; see Patterns 4) and share data throughthis.registryor a scene'sevents. - Pick where UI lives. A score or health readout fits a parallel HUD scene. Text-heavy
menus and settings work better as HTML over the canvas (
this.add.domor a plain overlay). - Verify with the build and the headless smoke check in Verify.
Patterns
1. Game config and boot
// main.js: one Game owns the renderer, loop, cache and Scene Manager.
import Phaser from 'phaser';
import BootScene from './scenes/BootScene.js';
import PlayScene from './scenes/PlayScene.js';
import HudScene from './scenes/HudScene.js';
const config = {
type: Phaser.AUTO, // WebGL, Canvas only as a fallback
parent: 'game', // id of the element that holds the canvas
width: 800,
height: 600,
backgroundColor: '#1d1d28',
scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
dom: { createContainer: true }, // only if you use this.add.dom(); needs `parent`
scene: [BootScene, PlayScene, HudScene], // later in the list = drawn on top
};
const game = new Phaser.Game(config);
Object.assign(window, { game }); // for the smoke check and console debugging (TS-safe)
2. A scene with the full lifecycle
// scenes/PlayScene.js
import Phaser from 'phaser';
import { createRun, stepRun } from '../rules/run.js'; // plain module, no Phaser import
export default class PlayScene extends Phaser.Scene {
constructor() {
super('play');
}
init(data) {
this.run = createRun({ level: data.level ?? 1 }); // runs on every (re)start
}
preload() {
this.load.image('player', 'assets/player.png');
this.load.spritesheet('coin', 'assets/coin.png', { frameWidth: 16, frameHeight: 16 });
}
create() {
this.player = this.add.sprite(400, 300, 'player');
this.cursors = this.input.keyboard.createCursorKeys();
if (!this.scene.isActive('hud')) this.scene.launch('hud');
}
update(time, delta) {
const dir = (this.cursors.right.isDown ? 1 : 0) - (this.cursors.left.isDown ? 1 : 0);
stepRun(this.run, { dir }, delta / 1000); // delta is milliseconds
this.player.x = this.run.playerX;
this.registry.set('score', this.run.score);
}
}
3. Cross-scene data and events
// HUD scene: react to registry changes instead of polling every frame.
create() {
this.scoreText = this.add.text(10, 10, 'Score: 0', { fontSize: '20px', color: '#fff' });
const onScore = (_parent, value) => this.scoreText.setText(`Score: ${value}`);
this.registry.events.on('changedata-score', onScore);
// The registry outlives scenes: remove the listener or it stacks on every restart.
this.events.once('shutdown', () => this.registry.events.off('changedata-score', onScore));
}
// Talk to another running scene directly through its event emitter.
this.scene.get('hud').events.emit('show-message', 'Level cleared!');
4. Scene transitions
this.scene.start('gameover', { score }); // stop this scene, start the target
this.scene.launch('hud'); // run in parallel; restarts it if already running
this.scene.run('hud'); // wake if asleep, resume if paused, else start
this.scene.switch('menu'); // sleep this scene, start or wake the target
this.scene.pause(); // stop updating, keep drawing (modal menus)
this.scene.sleep(); // stop updating and drawing, keep state
this.scene.bringToTop('hud'); // draw order follows the scene list
5. HTML over the canvas
// Requires dom.createContainer and parent in the game config (Pattern 1).
const panel = this.add.dom(400, 300).createFromHTML(`
<form class="settings"><label>Volume <input name="vol" type="range"></label></form>`);
panel.addListener('input');
panel.on('input', (event) => this.sound.setVolume(event.target.value / 100));
6. Camera follow
this.cameras.main.setBounds(0, 0, 1600, 1200);
this.cameras.main.startFollow(this.player, true, 0.1, 0.1); // lerp follow
Verify
- Build or type-check first:
npm run build(ornpx tsc --noEmitin a TypeScript project) must pass. - Test the rules modules with
node --testwhen step 2 of the workflow was followed. - Smoke-test the running game in a headless browser. With the dev server running and
window.gameexposed (Pattern 1), save and run this withnode smoke.mjs <url>. It needsnpm i -D playwrightandnpx playwright install chromium; if the user does not want that, ask them to open the page and report the console output and what they see.
// smoke.mjs: fails on any page error; prints renderer, running scenes and a screenshot path.
import { chromium } from 'playwright';
const browser = await chromium.launch();
const page = await browser.newPage();
const errors = [];
page.on('pageerror', (e) => errors.push(e.message));
page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
await page.goto(process.argv[2]);
await page.waitForFunction(() => window.game?.isRunning, null, { timeout: 15000 });
await page.waitForTimeout(1500); // let the first scenes finish preload
const state = await page.evaluate(() => ({
renderer: window.game.config.renderType === 2 ? 'webgl' : 'canvas', // Phaser.WEBGL = 2
scenes: window.game.scene.getScenes(true).map((s) => s.sys.settings.key),
}));
await page.screenshot({ path: 'smoke.png' });
await browser.close();
console.log(JSON.stringify({ ...state, errors }, null, 2));
process.exit(errors.length ? 1 : 0);
Expect renderer: "webgl", the scene keys you meant to be running (for example ["play", "hud"]), and an empty errors list. Open smoke.png and confirm the playfield and HUD are
drawn; DOM checks alone miss a canvas that renders nothing.
Gotchas
- Assets are
undefinedincreate→ they were not queued inpreload, or the key is wrong. The loader runs betweenpreloadandcreate. A failed file shows as a 404 in the console, and sprites using that key draw Phaser's placeholder "missing" texture. - State leaks across a restart → fields set in the constructor. A scene instance is reused,
so reset run state in
init()and clear collections onshutdown. - HUD hidden, reset, or drawn underneath →
startstopped the gameplay scene; uselaunch. A secondlaunchorrunon a running scene restarts it, so guard withisActive. Scenes draw in scene-list order; callbringToTop('hud')if it was listed first. - Scene state read right after
start/launchis stale → scene operations are queued and run at the start of the next game step. No DOM Container set in game configfromthis.add.dom()→ adddom: { createContainer: true }and aparentelement to the game config.- Keys stay down after release, or Left + Right cancel out → Phaser 4.2.1 skips keyboard
events that are already
defaultPrevented, so a host-page listener that cancelskeyupleaves the key held. Check host listeners and extensions before touching movement code (diagnosis in the reference). - A Phaser 3 snippet runs but looks wrong in Phaser 4 →
preFX/postFXandBitmapMaskbecame filters (obj.enableFilters(), thenobj.filters.internal/.external);setPipeline('Light2D')becamesetLighting(true);setTintFill(c)only logs an error, usesetTint(c).setTintMode(Phaser.TintModes.FILL);Phaser.Math.TAUis now 2π (usePhaser.Math.PI_OVER_2where v3 code meant π/2);Geom.Pointis gone (usePhaser.Math.Vector2). - Phaser 3 custom pipelines or renderer plugins fail in Phaser 4 → the renderer was rebuilt and the old pipeline extension points are gone. Port them against the v4 migration guide instead of copying renderer internals. Canvas rendering still works but is deprecated.
- Pixel art is blurry or shimmers → set
pixelArt: true; it turns off antialiasing and turns onroundPixels, which defaults tofalsein Phaser 4. - Black screen with no error → no scene started, or the canvas has no size. Run
game.scene.dump()in the console to list scene states. - Two canvases after hot reload or a React/Vue remount → a second
new Phaser.Gameran while the first was alive. Keep one instance and callgame.destroy(true)on unmount; the teardown finishes on the next frame. LeavenoReturnfalse or no new game can start.
References
- Read
references/scene-flow.mdwhen a transition behaves unexpectedly (pause vs sleep vs stop), listeners stack up after restarts, a scene key must be replaced, or keys stay stuck down.
Related skills
phaser-arcade-physics: velocity, gravity, colliders, overlaps and groups.game-ui-ux: HUD and menu layout, scaling and focus rules.input-systems: rebindable, multi-device input architecture.platformer,puzzle,tower-defense: genre skills that build on Phaser.
Version notes
Last verified: 2026-11-11.
- npm
latestis Phaser 4.2.1 (published 2026-07-09). The newest 3.x on npm is 3.90.0. - The keyboard
defaultPreventedbehaviour andgame.destroy(removeCanvas, noReturn)were checked in the v4.2.1 source; recheck the keyboard diagnosis on other versions. - Sources:
npm view phaser dist-tags, Phaser 4 migration guide, Phaser 3 to 4 article, v4.2.1 source.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |