Phaser HTML5 Game Framework

Common errors

• Uncaught ReferenceError: Phaser is not defined

  cause The global `Phaser` object is not accessible, either because the script tag for Phaser was not loaded correctly (if using a CDN) or an `import` statement is missing or incorrect in a module environment.
  fix If using a CDN, ensure the `<script>` tag for `phaser.min.js` is correctly placed in your HTML and loaded before your game code. If using modules, ensure `import Phaser from 'phaser';` is present at the top of your module file.

• TypeError: Cannot read properties of undefined (reading 'Scene')

  cause Attempting to destructure or directly import a core Phaser class (like `Scene`, `Game`, `GameObjects`) that is not a named export from the `phaser` package. These classes are properties of the default `Phaser` object.
  fix Access core classes and namespaces as properties of the default `Phaser` import: `class MyScene extends Phaser.Scene { ... }` or `const game = new Phaser.Game(...)`.

• Module not found: Error: Can't resolve 'phaser' in '[your_project_path]' (webpack)

  cause The `phaser` package is not correctly installed or your build tool (e.g., Webpack, Vite, Rollup) cannot locate it, possibly due to an incorrect `node_modules` path or improper ES Module configuration.
  fix Run `npm install phaser` or `yarn add phaser` to ensure the package is installed. Verify your `tsconfig.json` (for TypeScript) or build tool configuration correctly handles module resolution for ES Modules. If migrating, ensure all `require()` calls are updated to `import` statements.

• WebGL error 1282: Invalid operation

• Shader program compilation failed (WebGL)

  cause These are common WebGL context errors, often indicating issues with custom shader uniform setup, incorrect texture binding, or invalid WebGL state changes. The new v4 renderer architecture is more strict with WebGL state management.
  fix Carefully review any custom shaders and direct WebGL interactions. Ensure shader uniform types and values match expectations. Refer to the Phaser v4 documentation on the new Render Node Architecture and `Shader#setUniform()` for correct usage and state management.

Warnings

• breaking Phaser v4 introduces a completely rewritten WebGL renderer with a new, node-based architecture, fundamentally changing the rendering pipeline from v3. The v3 pipeline system has been replaced.
  Fix: Review and refactor any custom render logic, shaders, and pipeline interactions. The new architecture manages WebGL state more explicitly; consult the v4 documentation for migration guidance.
• gotcha The full `phaser.js` bundle is over 8MB raw due to extensive inline JSDoc documentation, which is stripped during minification. Shipping this bundle to production will significantly increase load times.
  Fix: Always use `phaser.min.js` (approximately 345 KB gzipped) or a custom build with unneeded features excluded for production environments to optimize bundle size.
• gotcha Texture wrapping modes like `REPEAT` may not apply correctly to non-power-of-two (NPOT) textures in WebGL, potentially causing unexpected visual artifacts.
  Fix: Ensure all textures intended for `REPEAT` wrapping have dimensions that are powers of two. Utilize `Texture#setWrap()` for explicit control over texture wrap modes and consult browser console for WebGL warnings.
• gotcha Phaser 4's module structure and official examples primarily leverage ES Modules (`import`). While some transpiled environments might accommodate CommonJS (`require`), it is not the recommended or fully supported approach, and may lead to module resolution issues.
  Fix: Adopt an ES Module-first development workflow. Use `import Phaser from 'phaser';` and ensure your project's build system (e.g., Vite, Webpack, Rollup) is correctly configured for ESM.
• gotcha Significant performance optimizations related to data buffer sizing, especially for filters and masks, were introduced in v4.0.0-rc.4. While generally leading to speedups (up to 16x on mobile), specific, complex filter configurations might behave differently.
  Fix: Profile game performance on target devices, particularly in scenes heavy with filters or masks. Adjust filter usage or settings if any unexpected performance changes (positive or negative) are observed.

Install

• npm install phaser npm
• yarn add phaser yarn
• pnpm add phaser pnpm

Imports

• Phaser
  wrong:

  const Phaser = require('phaser');

  correct:

  import Phaser from 'phaser';

  Phaser v4 is primarily designed for ES Modules. While `require` might work in some transpiled environments, `import` is the idiomatic and officially supported way to consume the package.
• Phaser.Scene (class access)
  wrong:

  import { Scene } from 'phaser';

  correct:

  import Phaser from 'phaser';
  class MyScene extends Phaser.Scene { /* ... */ }

  Core classes like `Scene`, `Game`, and `GameObjects` are typically properties of the default `Phaser` export, not direct named exports from the top-level package. Access them via the `Phaser` object.
• Phaser (Type Import)
  wrong:

  import { Phaser } from 'phaser';

  correct:

  import type Phaser from 'phaser';

  For TypeScript, use `import type` when only needing the type definition of the `Phaser` framework object, which helps in build optimizations by preventing bundling of the runtime code if not otherwise used.

Quickstart

This code sets up a minimal Phaser 4 game with a single scene, displaying a text object and animating a circle using tweens.

import Phaser from 'phaser';

class DemoScene extends Phaser.Scene {
    constructor() {
        super({ key: 'DemoScene' });
    }

    preload() {
        // Load assets here if needed, e.g., this.load.image('logo', 'assets/phaser3-logo.png');
    }

    create() {
        this.add.text(100, 100, 'Hello Phaser 4!', { font: '32px Arial', color: '#ffffff' });
        console.log('Phaser 4 Demo Scene created!');

        // Example: Add a simple tween
        const circle = this.add.circle(400, 300, 50, 0xff0000);
        this.tweens.add({
            targets: circle,
            x: 600,
            duration: 2000,
            ease: 'Power2',
            yoyo: true,
            loop: -1
        });
    }

    update(time: number, delta: number) {
        // Game logic updated every frame
    }
}

const config: Phaser.Types.Core.GameConfig = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    backgroundColor: '#1a1a1a',
    scene: DemoScene,
    parent: 'game-container', // Ensure you have a div with id="game-container" in your HTML
    physics: {
        default: 'arcade',
        arcade: {
            debug: false
        }
    }
};

new Phaser.Game(config);