Index of every page on this site: llms.txt
All skills
Run it yourself

Sets 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`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/phaser-core

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈94 tokens for metadata: the name and description. ≈2.9k when used: this file. ≈1.9k more on demand in 1 file.

Description uses 4.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈377 characters, or 4.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 phaser in package.json, import Phaser from 'phaser', or classes that extend Phaser.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

  1. Read the installed major. Check package.json and 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.
  2. 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 --test without a browser, and a restart is just new state.
  3. Create one game from a config with type: Phaser.AUTO, a size, a scale mode and a scene array. The first scene in the array (and any with active: true) starts on boot.
  4. One Scene subclass per screen with a unique key. Reset run state in init(), queue assets in preload(), build objects in create(), step in update(time, delta).
  5. Move between screens with the right verb (start, launch, run, switch, sleep; see Patterns 4) and share data through this.registry or a scene's events.
  6. 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.dom or a plain overlay).
  7. 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

  1. Build or type-check first: npm run build (or npx tsc --noEmit in a TypeScript project) must pass.
  2. Test the rules modules with node --test when step 2 of the workflow was followed.
  3. Smoke-test the running game in a headless browser. With the dev server running and window.game exposed (Pattern 1), save and run this with node smoke.mjs <url>. It needs npm i -D playwright and npx 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 undefined in create → they were not queued in preload, or the key is wrong. The loader runs between preload and create. 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 on shutdown.
  • HUD hidden, reset, or drawn underneath → start stopped the gameplay scene; use launch. A second launch or run on a running scene restarts it, so guard with isActive. Scenes draw in scene-list order; call bringToTop('hud') if it was listed first.
  • Scene state read right after start/launch is stale → scene operations are queued and run at the start of the next game step.
  • No DOM Container set in game config from this.add.dom() → add dom: { createContainer: true } and a parent element 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 cancels keyup leaves 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/postFX and BitmapMask became filters (obj.enableFilters(), then obj.filters.internal / .external); setPipeline('Light2D') became setLighting(true); setTintFill(c) only logs an error, use setTint(c).setTintMode(Phaser.TintModes.FILL); Phaser.Math.TAU is now 2π (use Phaser.Math.PI_OVER_2 where v3 code meant π/2); Geom.Point is gone (use Phaser.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 on roundPixels, which defaults to false in 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.Game ran while the first was alive. Keep one instance and call game.destroy(true) on unmount; the teardown finishes on the next frame. Leave noReturn false or no new game can start.

References

  • Read references/scene-flow.md when 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 latest is Phaser 4.2.1 (published 2026-07-09). The newest 3.x on npm is 3.90.0.
  • The keyboard defaultPrevented behaviour and game.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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts9d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    The skill provides standard configuration and debugging patterns for Phaser 4 game development. It includes instructions for establishing game scenes, handling assets, and running smoke tests using the well-known Playwright library.

  • Socket9d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/phaser-core