phaser-core
Set up and debug a Phaser 4 game: the Game config, the Scene lifecycle (init/preload/create/update), the asset loader, cameras, and cross-scene communication. Use when building or debugging a Phaser game — when the user mentions Phaser, Phaser.Game, Phaser.Scene, preload/create/u
Install
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/main/skills/web-engines/phaser-core
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gamedev-skills-awesome-gamedev-agent-skills@llmmart
git clone https://github.com/gamedev-skills/awesome-gamedev-agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gamedev-skills/awesome-gamedev-agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Phaser 4 Core
Set up the foundation of a Phaser game: the Game config, the Scene
lifecycle, asset loading, cameras, and passing data between scenes. Targets
Phaser 4.2 for new projects; keep an existing Phaser 3.90 project on its
pinned major unless the user explicitly asks for a migration.
When to use
- Use when starting a Phaser game, wiring the
Phaser.Gameconfig, structuringScenes, loading assets inpreload, or fixing scene transitions and shared state. - Use when the project has
phaserinpackage.jsonorimport Phaser from 'phaser', and code usespreload()/create()/update().
When not to use: movement, velocity, colliders, gravity, or overlap → use
phaser-arcade-physics. Complex rigid-body simulation uses Matter physics (a
separate concern). For cross-engine save/load patterns use save-systems.
Core workflow
- Detect the installed major first. Read
package.jsonand the lockfile. Use Phaser 4.2 for new work; do not silently rewrite a Phaser 3 project as Phaser 4. - Create the game from a config.
new Phaser.Game(config)withtype: Phaser.AUTO(WebGL with Canvas fallback), awidth/height, and ascenearray. The first scene (and any withactive: true) starts automatically. - Model each screen as a
Scene. SubclassPhaser.Scene, pass a uniquekeytosuper, and implement the lifecycle:init(data)→preload()→create(data)→update(time, delta). - Load assets in
preload, use them increate. Queued assets are not available untilcreate. The loader is per-scene; the cache it fills is global. - Reset per-run state in
init(), not the constructor. A scene instance is reused across restarts, so constructor-set fields keep stale values. - Move between screens with
this.scene.start/launch/switch/sleep/wake. Share data throughthis.registry(global) or a sibling scene's event emitter. - Run and observe. Serve the page, open it, and confirm assets load (watch the Network tab and console) and scenes switch as expected before assuming success.
Patterns
1. Game config + boot (ES module)
// 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';
const config = {
type: Phaser.AUTO, // WebGL if available, else Canvas
width: 800,
height: 600,
backgroundColor: '#1d1d28',
scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
scene: [BootScene, PlayScene] // BootScene starts first
};
new Phaser.Game(config);
2. A Scene with the full lifecycle
// scenes/PlayScene.js
import Phaser from 'phaser';
export default class PlayScene extends Phaser.Scene {
constructor() {
super('play'); // unique scene key
}
init(data) {
// Reset run-specific state HERE so restarts start clean.
this.score = 0;
this.level = data.level ?? 1;
}
preload() {
// Queue downloads. Not usable until create().
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.scoreText = this.add.text(10, 10, 'Score: 0', { fontSize: '20px', color: '#fff' });
this.cursors = this.input.keyboard.createCursorKeys();
}
update(time, delta) {
// delta is milliseconds since last frame; divide by 1000 for seconds.
const speed = 200 * (delta / 1000);
if (this.cursors.left.isDown) this.player.x -= speed;
if (this.cursors.right.isDown) this.player.x += speed;
}
}
3. Cross-scene data + events
// The registry is a global DataManager shared by every scene.
this.registry.set('coins', 0); // in any scene
const coins = this.registry.get('coins'); // read anywhere
// React to registry changes (e.g. a HUD scene listening to gameplay):
this.registry.events.on('changedata-coins', (parent, value) => {
this.coinText.setText(`Coins: ${value}`);
});
// Talk directly to another running scene via its event emitter:
const ui = this.scene.get('hud');
ui.events.emit('show-message', 'Level cleared!');
4. Scene transitions (pick the right verb)
this.scene.start('gameover', { score: this.score }); // stop this scene, start target
this.scene.launch('hud'); // run a second scene in parallel (restarts it if already running)
this.scene.run('hud'); // wake if sleeping, resume if paused, else (re)start
this.scene.bringToTop('hud'); // draw order follows the scene list, not launch order
this.scene.switch('menu'); // sleep this scene, start/wake target
this.scene.pause(); // freeze updates but keep rendering (modal)
this.scene.sleep(); // stop updating AND rendering, keep state for wake
5. A camera that follows the player
this.cameras.main.setBounds(0, 0, 1600, 1200); // world size
this.cameras.main.startFollow(this.player, true, 0.1, 0.1); // smooth lerp follow
this.cameras.main.setZoom(1.5);
Pitfalls
- A key works once, then stays down (or Left + Right cancel out) → in Phaser
4.2.1, a
keyupcancelled before the keyboard manager receives it is ignored becauseevent.defaultPreventedis set. Inspect host-page listeners and browser extensions before changing movement code. Read the keyboard diagnosis and capture-phase fallback contract inreferences/scene-flow.md. - Assets are
undefinedincreate/update→ you forgot to queue them inpreload, or used the wrong key. The loader runs betweenpreloadandcreate. - State leaks across a restart → you set fields in the constructor. The Scene
instance is reused; reset run state in
init()and clear arrays onshutdown. this.scene.startvsthis.scene.launch→startstops the calling scene;launchruns the target alongside it. Usingstartfor a HUD hides the game.- HUD loses its state or draws behind the game →
launch(andrun) on a scene that is already running shuts it down and starts it again; launch the HUD once, or guard withif (!this.scene.isActive('hud')). Scenes draw in scene-list order, so a HUD listed before the gameplay scene renders underneath it until you callthis.scene.bringToTop('hud'). - Scene state read right after
start/launchis stale → scene operations are queued and run at the start of the next game step, not synchronously. thisis wrong in a callback → arrow functions keep the Scene'sthis; plainfunctioncallbacks need a context argument or.bind(this).- Phaser 2 tutorials don't work → "States" were renamed to "Scenes" in Phaser 3, and each Scene owns its own systems (input, cameras, tweens) rather than a global Game World.
- Phaser 3 custom pipelines fail in Phaser 4 → Phaser 4 rebuilt the renderer and replaced the old FX/pipeline extension points. Migrate custom shaders and renderer plugins against the Phaser 4 guide; do not mechanically copy internal renderer code.
- A Phaser 3 snippet runs but looks wrong in Phaser 4 → common renames:
preFX/postFXandBitmapMaskbecame filters (obj.enableFilters()thenobj.filters.internal/.external);setPipeline('Light2D')becamesetLighting(true);setTintFill(c)only logs an error, so 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). Canvas rendering still works but is deprecated. - Pixel art is blurry or shimmers while moving → set
pixelArt: truein the game config. It turns off antialiasing and turns onroundPixels, which defaults tofalsein Phaser 4. - Nothing renders / black screen → confirm the canvas mounted,
width/heightare set, and a scene actually started (checkgame.scene.dump()output). - Two canvases (two games running) after a hot reload or a React/Vue remount →
a second
new Phaser.Gameran while the first was still alive. Keep one instance and callgame.destroy(true)when the host component unmounts; the teardown finishes on the next frame. LeavenoReturnfalse, or no new game can start on the page.
References
- For the full scene state machine (pause/resume vs sleep/wake vs stop/start, the
restart-state bug, removing/replacing scenes, and stuck keyboard input), read
references/scene-flow.md.
Related skills
phaser-arcade-physics— velocity, gravity, colliders, overlap, and groups.input-systems— rebindable, multi-device input architecture (engine-agnostic).pixijs-rendering/threejs-scene-setup— other browser rendering stacks.platformer/puzzle— genre templates that compose Phaser skills.
Files (awesome-gamedev-agent-skills)
-
references
-
scene-flow.md 7.2 KB
Loading…
-
-
SKILL.md 9.3 KB
--- name: phaser-core description: > Set up and debug a Phaser 4 game: the Game config, the Scene lifecycle (init/preload/create/update), the asset loader, cameras, and cross-scene communication. Use when building or debugging a Phaser game — when the user mentions Phaser, Phaser.Game, Phaser.Scene, preload/create/update, this.load, this.add, or scene transitions. For Arcade Physics movement/collisions use phaser-arcade-physics. --- # Phaser 4 Core Set up the foundation of a Phaser game: the `Game` config, the `Scene` lifecycle, asset loading, cameras, and passing data between scenes. Targets **Phaser 4.2** for new projects; keep an existing Phaser 3.90 project on its pinned major unless the user explicitly asks for a migration. ## When to use - Use when starting a Phaser game, wiring the `Phaser.Game` config, structuring `Scene`s, loading assets in `preload`, or fixing scene transitions and shared state. - Use when the project has `phaser` in `package.json` or `import Phaser from 'phaser'`, and code uses `preload()`/`create()`/`update()`. **When *not* to use:** movement, velocity, colliders, gravity, or overlap → use `phaser-arcade-physics`. Complex rigid-body simulation uses Matter physics (a separate concern). For cross-engine save/load patterns use `save-systems`. ## Core workflow 1. **Detect the installed major first.** Read `package.json` and the lockfile. Use Phaser 4.2 for new work; do not silently rewrite a Phaser 3 project as Phaser 4. 2. **Create the game from a config.** `new Phaser.Game(config)` with `type: Phaser.AUTO` (WebGL with Canvas fallback), a `width`/`height`, and a `scene` array. The first scene (and any with `active: true`) starts automatically. 3. **Model each screen as a `Scene`.** Subclass `Phaser.Scene`, pass a unique `key` to `super`, and implement the lifecycle: `init(data)` → `preload()` → `create(data)` → `update(time, delta)`. 4. **Load assets in `preload`, use them in `create`.** Queued assets are not available until `create`. The loader is per-scene; the cache it fills is global. 5. **Reset per-run state in `init()`, not the constructor.** A scene instance is reused across restarts, so constructor-set fields keep stale values. 6. **Move between screens** with `this.scene.start/launch/switch/sleep/wake`. Share data through `this.registry` (global) or a sibling scene's event emitter. 7. **Run and observe.** Serve the page, open it, and confirm assets load (watch the Network tab and console) and scenes switch as expected before assuming success. ## Patterns ### 1. Game config + boot (ES module) ```js // 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'; const config = { type: Phaser.AUTO, // WebGL if available, else Canvas width: 800, height: 600, backgroundColor: '#1d1d28', scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH }, scene: [BootScene, PlayScene] // BootScene starts first }; new Phaser.Game(config); ``` ### 2. A Scene with the full lifecycle ```js // scenes/PlayScene.js import Phaser from 'phaser'; export default class PlayScene extends Phaser.Scene { constructor() { super('play'); // unique scene key } init(data) { // Reset run-specific state HERE so restarts start clean. this.score = 0; this.level = data.level ?? 1; } preload() { // Queue downloads. Not usable until create(). 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.scoreText = this.add.text(10, 10, 'Score: 0', { fontSize: '20px', color: '#fff' }); this.cursors = this.input.keyboard.createCursorKeys(); } update(time, delta) { // delta is milliseconds since last frame; divide by 1000 for seconds. const speed = 200 * (delta / 1000); if (this.cursors.left.isDown) this.player.x -= speed; if (this.cursors.right.isDown) this.player.x += speed; } } ``` ### 3. Cross-scene data + events ```js // The registry is a global DataManager shared by every scene. this.registry.set('coins', 0); // in any scene const coins = this.registry.get('coins'); // read anywhere // React to registry changes (e.g. a HUD scene listening to gameplay): this.registry.events.on('changedata-coins', (parent, value) => { this.coinText.setText(`Coins: ${value}`); }); // Talk directly to another running scene via its event emitter: const ui = this.scene.get('hud'); ui.events.emit('show-message', 'Level cleared!'); ``` ### 4. Scene transitions (pick the right verb) ```js this.scene.start('gameover', { score: this.score }); // stop this scene, start target this.scene.launch('hud'); // run a second scene in parallel (restarts it if already running) this.scene.run('hud'); // wake if sleeping, resume if paused, else (re)start this.scene.bringToTop('hud'); // draw order follows the scene list, not launch order this.scene.switch('menu'); // sleep this scene, start/wake target this.scene.pause(); // freeze updates but keep rendering (modal) this.scene.sleep(); // stop updating AND rendering, keep state for wake ``` ### 5. A camera that follows the player ```js this.cameras.main.setBounds(0, 0, 1600, 1200); // world size this.cameras.main.startFollow(this.player, true, 0.1, 0.1); // smooth lerp follow this.cameras.main.setZoom(1.5); ``` ## Pitfalls - **A key works once, then stays down (or Left + Right cancel out)** → in Phaser 4.2.1, a `keyup` cancelled before the keyboard manager receives it is ignored because `event.defaultPrevented` is set. Inspect host-page listeners and browser extensions before changing movement code. Read the keyboard diagnosis and capture-phase fallback contract in `references/scene-flow.md`. - **Assets are `undefined` in `create`/`update`** → you forgot to queue them in `preload`, or used the wrong key. The loader runs between `preload` and `create`. - **State leaks across a restart** → you set fields in the constructor. The Scene instance is reused; reset run state in `init()` and clear arrays on `shutdown`. - **`this.scene.start` vs `this.scene.launch`** → `start` stops the calling scene; `launch` runs the target alongside it. Using `start` for a HUD hides the game. - **HUD loses its state or draws behind the game** → `launch` (and `run`) on a scene that is already running shuts it down and starts it again; launch the HUD once, or guard with `if (!this.scene.isActive('hud'))`. Scenes draw in scene-list order, so a HUD listed before the gameplay scene renders underneath it until you call `this.scene.bringToTop('hud')`. - **Scene state read right after `start`/`launch` is stale** → scene operations are queued and run at the start of the next game step, not synchronously. - **`this` is wrong in a callback** → arrow functions keep the Scene's `this`; plain `function` callbacks need a context argument or `.bind(this)`. - **Phaser 2 tutorials don't work** → "States" were renamed to "Scenes" in Phaser 3, and each Scene owns its own systems (input, cameras, tweens) rather than a global Game World. - **Phaser 3 custom pipelines fail in Phaser 4** → Phaser 4 rebuilt the renderer and replaced the old FX/pipeline extension points. Migrate custom shaders and renderer plugins against the Phaser 4 guide; do not mechanically copy internal renderer code. - **A Phaser 3 snippet runs but looks wrong in Phaser 4** → common renames: `preFX`/ `postFX` and `BitmapMask` became filters (`obj.enableFilters()` then `obj.filters.internal`/`.external`); `setPipeline('Light2D')` became `setLighting(true)`; `setTintFill(c)` only logs an error, so 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`). Canvas rendering still works but is deprecated. - **Pixel art is blurry or shimmers while moving** → set `pixelArt: true` in the game config. It turns off antialiasing and turns on `roundPixels`, which defaults to `false` in Phaser 4. - **Nothing renders / black screen** → confirm the canvas mounted, `width`/`height` are set, and a scene actually started (check `game.scene.dump()` output). - **Two canvases (two games running) after a hot reload or a React/Vue remount** → a second `new Phaser.Game` ran while the first was still alive. Keep one instance and call `game.destroy(true)` when the host component unmounts; the teardown finishes on the next frame. Leave `noReturn` false, or no new game can start on the page. ## References - For the full scene state machine (pause/resume vs sleep/wake vs stop/start, the restart-state bug, removing/replacing scenes, and stuck keyboard input), read `references/scene-flow.md`. ## Related skills - `phaser-arcade-physics` — velocity, gravity, colliders, overlap, and groups. - `input-systems` — rebindable, multi-device input architecture (engine-agnostic). - `pixijs-rendering` / `threejs-scene-setup` — other browser rendering stacks. - `platformer` / `puzzle` — genre templates that compose Phaser skills.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.