{"id":11550,"library":"phaser","title":"Phaser HTML5 Game Framework","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://phaserjs@github.com/phaserjs/phaser","tags":["javascript","2d","HTML5","WebGL","canvas","game","physics","tweens","typescript"],"install":[{"cmd":"npm install phaser","lang":"bash","label":"npm"},{"cmd":"yarn add phaser","lang":"bash","label":"yarn"},{"cmd":"pnpm add phaser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Phaser = require('phaser');","symbol":"Phaser","correct":"import Phaser from 'phaser';"},{"note":"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.","wrong":"import { Scene } from 'phaser';","symbol":"Phaser.Scene (class access)","correct":"import Phaser from 'phaser';\nclass MyScene extends Phaser.Scene { /* ... */ }"},{"note":"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.","wrong":"import { Phaser } from 'phaser';","symbol":"Phaser (Type Import)","correct":"import type Phaser from 'phaser';"}],"quickstart":{"code":"import Phaser from 'phaser';\n\nclass DemoScene extends Phaser.Scene {\n    constructor() {\n        super({ key: 'DemoScene' });\n    }\n\n    preload() {\n        // Load assets here if needed, e.g., this.load.image('logo', 'assets/phaser3-logo.png');\n    }\n\n    create() {\n        this.add.text(100, 100, 'Hello Phaser 4!', { font: '32px Arial', color: '#ffffff' });\n        console.log('Phaser 4 Demo Scene created!');\n\n        // Example: Add a simple tween\n        const circle = this.add.circle(400, 300, 50, 0xff0000);\n        this.tweens.add({\n            targets: circle,\n            x: 600,\n            duration: 2000,\n            ease: 'Power2',\n            yoyo: true,\n            loop: -1\n        });\n    }\n\n    update(time: number, delta: number) {\n        // Game logic updated every frame\n    }\n}\n\nconst config: Phaser.Types.Core.GameConfig = {\n    type: Phaser.AUTO,\n    width: 800,\n    height: 600,\n    backgroundColor: '#1a1a1a',\n    scene: DemoScene,\n    parent: 'game-container', // Ensure you have a div with id=\"game-container\" in your HTML\n    physics: {\n        default: 'arcade',\n        arcade: {\n            debug: false\n        }\n    }\n};\n\nnew Phaser.Game(config);","lang":"typescript","description":"This code sets up a minimal Phaser 4 game with a single scene, displaying a text object and animating a circle using tweens."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"Texture wrapping modes like `REPEAT` may not apply correctly to non-power-of-two (NPOT) textures in WebGL, potentially causing unexpected visual artifacts.","severity":"gotcha","affected_versions":">=4.0.0-rc.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0-rc.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Uncaught ReferenceError: Phaser is not defined"},{"fix":"Access core classes and namespaces as properties of the default `Phaser` import: `class MyScene extends Phaser.Scene { ... }` or `const game = new Phaser.Game(...)`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'Scene')"},{"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.","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.","error":"Module not found: Error: Can't resolve 'phaser' in '[your_project_path]' (webpack)"},{"error":"WebGL error 1282: Invalid operation"},{"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.","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.","error":"Shader program compilation failed (WebGL)"}],"ecosystem":"npm"}