phaser

library0.3jsnpmunverified

Phaser is a robust, open-source HTML5 game framework designed for creating 2D games across desktop and mobile web browsers, currently stable at version 4.0.0. It leverages WebGL and Canvas rendering and has been under active development for over a decade. Version 4 represents a significant, ground-up rebuild of its WebGL renderer, featuring a new, node-based architecture that replaces the v3 pipeline system for enhanced performance and reliability, while striving to maintain a familiar API for developers. The framework offers an extensive suite of features for 2D game development, including advanced physics engines, sophisticated tweening systems, and web audio management. It supports development using both JavaScript and TypeScript and is compatible with various modern front-end frameworks. The project is commercially developed and maintained by Phaser Studio Inc. with strong community contributions, adhering to a release cadence that includes extensive pre-release candidates for major versions, ensuring a stable and well-tested core.

web-framework ai-ml serialization

npm install phaser

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PHASER

phaser

web-frameworkjavascriptv0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Phaser

✓ import Phaser from 'phaser';

✗ const Phaser = require('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)

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

✗ import { Scene } from 'phaser';

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)

✓ import type Phaser from 'phaser';

✗ import { 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.

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);

Debug

Known issues

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

affects: >=4.0.0

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

affects: >=4.0.0

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

affects: >=4.0.0-rc.6

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

affects: >=4.0.0

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

affects: >=4.0.0-rc.4

Errors

Common errors & fixes

Uncaught ReferenceError: Phaser is not defined

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')

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)

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)

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.

Upgrade

Version history

0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/phaserjs/phaser ↗

packagehttps://www.npmjs.com/package/phaser ↗

homepagehttps://phaser.io ↗