Claude Skill

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

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download gamedev-skills-awesome-gamedev-agent-skills-skills_web-engines_phaser-core-4cce500.zip · 7 KB

Install

skills CLI npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/main/skills/web-engines/phaser-core
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gamedev-skills-awesome-gamedev-agent-skills@llmmart
Git 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.Game config, structuring Scenes, 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)

// 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 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.
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.

No comments yet.

Reviews (0)

No reviews yet.