or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

actions.mdanimation.mdaudio.mdcameras.mddata-management.mdevents.mdgame-objects.mdindex.mdinput.mdloading.mdmath-geometry.mdphysics.mdrendering.mdscenes.mdtweens.mdutilities.md
tile.json

tessl/npm-phaser

A fast, free and fun HTML5 Game Framework for Desktop and Mobile web browsers

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/phaser@3.90.x

To install, run

npx @tessl/cli install tessl/npm-phaser@3.90.0

index.mddocs/

Phaser 3.90.0

Overview

Phaser is a fast, free, and fun HTML5 game framework for desktop and mobile web browsers. It provides a comprehensive suite of tools for 2D game development with WebGL and Canvas rendering support, physics engines, input handling, audio management, and much more.

Phaser follows a modular architecture centered around Scenes, GameObjects, and Systems that work together to create interactive games and applications.

Package Information

  • Package Name: phaser
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install phaser

Core Imports

CommonJS

const Phaser = require('phaser');

ES Modules

import Phaser from 'phaser';

CDN

<script src="https://cdn.jsdelivr.net/npm/phaser@3.90.0/dist/phaser.min.js"></script>

Basic Usage

Game Initialization

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    scene: {
        preload: preload,
        create: create,
        update: update
    }
};

const game = new Phaser.Game(config);

function preload() {
    this.load.image('logo', 'assets/logo.png');
}

function create() {
    this.add.image(400, 300, 'logo');
}

function update() {
    // Game loop logic
}

Scene Class Approach

class GameScene extends Phaser.Scene {
    constructor() {
        super({ key: 'GameScene' });
    }
    
    preload() {
        this.load.image('background', 'assets/bg.jpg');
        this.load.spritesheet('player', 'assets/player.png', {
            frameWidth: 32,
            frameHeight: 48
        });
    }
    
    create() {
        this.add.image(0, 0, 'background').setOrigin(0);
        this.player = this.add.sprite(100, 450, 'player');
    }
    
    update() {
        // Update logic
    }
}

const game = new Phaser.Game({
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    scene: GameScene
});

Architecture

Phaser uses a component-based architecture with the following key concepts:

Game Instance

The root Phaser.Game object manages the entire game lifecycle, including scenes, rendering, input, and system updates.

Scenes

Scenes are self-contained game states (menu, gameplay, game over). Each scene has its own:

  • Display list (rendered objects)
  • Update list (objects that receive update calls)
  • Input handling
  • Physics world
  • Camera system

GameObjects

All visual and interactive elements inherit from Phaser.GameObjects.GameObject. Common objects include Sprites, Images, Text, Graphics, and Containers.

Systems

Scenes contain various systems for managing different aspects:

  • scene.add - GameObject factory
  • scene.input - Input handling
  • scene.physics - Physics simulation
  • scene.cameras - Camera management
  • scene.tweens - Animation tweening

Capabilities

Game Objects

Comprehensive collection of display objects for creating game content.

Key APIs:

// Sprites with texture animation support
scene.add.sprite(x, y, 'texture', frame);

// Static images 
scene.add.image(x, y, 'texture');

// Text rendering with styling
scene.add.text(x, y, 'Hello World', { fontSize: '32px', fill: '#000' });

// Vector graphics drawing
const graphics = scene.add.graphics();
graphics.fillRect(0, 0, 100, 100);

// Containers for grouping objects
const container = scene.add.container(x, y);
container.add([sprite1, sprite2, text]);

Coverage: Sprites, Images, Text, Graphics, Containers, Shapes, Particle Systems, Video, DOM Elements, WebGL Shaders, 3D Objects

Scene Management

Scene lifecycle management and transitions between game states.

Key APIs:

// Scene transitions
scene.scene.start('NextScene', data);
scene.scene.pause();
scene.scene.resume();

// Multiple scenes
scene.scene.launch('UIScene');
scene.scene.run('BackgroundScene');

Coverage: Scene lifecycle, transitions, parallel scenes, data passing, scene plugins

Input Handling

Multi-platform input support for keyboard, mouse, touch, and gamepad.

Key APIs:

// Keyboard input
const cursors = scene.input.keyboard.createCursorKeys();
if (cursors.left.isDown) { /* move left */ }

// Mouse/touch input
scene.input.on('pointerdown', (pointer) => {
    console.log('Clicked at:', pointer.x, pointer.y);
});

// Interactive objects
sprite.setInteractive();
sprite.on('pointerdown', () => { /* handle click */ });

Coverage: Keyboard, mouse, touch, gamepad, interactive objects, drag and drop

Animation Systems

Frame-based animations and tweening for smooth visual effects.

Key APIs:

// Create frame animation
scene.anims.create({
    key: 'walk',
    frames: scene.anims.generateFrameNumbers('player', { start: 0, end: 3 }),
    frameRate: 10,
    repeat: -1
});

// Tween animations
scene.tweens.add({
    targets: sprite,
    x: 400,
    duration: 2000,
    ease: 'Power2'
});

Coverage: Sprite animations, tweens, timelines, easing functions, animation events

Physics Systems

Physics simulation with Arcade Physics (fast) and Matter.js (realistic).

Key APIs:

// Enable Arcade Physics
scene.physics.add.sprite(x, y, 'texture');

// Collision detection
scene.physics.add.collider(player, platforms);

// Matter.js physics bodies
scene.matter.add.rectangle(x, y, width, height);

Coverage: Arcade Physics, Matter.js integration, collision detection, physics groups, constraints

Camera System

Flexible camera system with effects, following, and multi-camera support.

Key APIs:

// Camera controls
scene.cameras.main.startFollow(player);
scene.cameras.main.setZoom(2);

// Camera effects
scene.cameras.main.shake(1000, 0.05);
scene.cameras.main.fade(1000);

// Multiple cameras
const camera2 = scene.cameras.add(100, 100, 200, 200);

Coverage: Camera movement, following, effects, bounds, multiple cameras

Audio Management

Comprehensive audio system with Web Audio API and HTML5 Audio support.

Key APIs:

// Load and play sounds
scene.load.audio('music', 'assets/music.mp3');
const music = scene.sound.add('music');
music.play();

// Audio sprites
scene.load.audioSprite('sfx', 'assets/sounds.json', 'assets/sounds.mp3');
scene.sound.playAudioSprite('sfx', 'jump');

Coverage: Audio loading, playback, audio sprites, 3D audio, sound effects

Asset Loading

Flexible asset loading system supporting multiple file types and loading strategies.

Key APIs:

// Load various asset types
scene.load.image('logo', 'assets/logo.png');
scene.load.spritesheet('player', 'assets/player.png', { frameWidth: 32, frameHeight: 48 });
scene.load.atlas('atlas', 'assets/atlas.png', 'assets/atlas.json');
scene.load.audio('music', 'assets/music.mp3');

// Loading events
scene.load.on('progress', (percent) => {
    console.log('Loading:', Math.round(percent * 100) + '%');
});

Coverage: Image loading, spritesheets, atlases, audio, JSON, XML, binary data, asset packs

Math & Geometry

Comprehensive mathematical functions and geometric operations.

Key APIs:

// Vector math
const vector = new Phaser.Math.Vector2(x, y);
vector.normalize().scale(100);

// Geometric shapes
const circle = new Phaser.Geom.Circle(x, y, radius);
const rect = new Phaser.Geom.Rectangle(x, y, width, height);

// Intersection testing
Phaser.Geom.Intersects.CircleToRectangle(circle, rect);

Coverage: Vector math, matrices, geometric shapes, intersection testing, interpolation, easing

Rendering & Display

WebGL and Canvas rendering with textures, effects, and display management.

Key APIs:

// Texture management
scene.textures.addBase64('key', base64Data);
scene.textures.create('canvas', canvasElement);

// Blend modes and effects
sprite.setBlendMode(Phaser.BlendModes.ADD);
sprite.setTint(0xff0000);

// Render textures
const renderTexture = scene.add.renderTexture(x, y, width, height);
renderTexture.draw(sprite);

Coverage: WebGL/Canvas rendering, textures, blend modes, shaders, render textures, display utilities

Tweens & Timeline Animation

Property tweening and complex animation sequences for smooth visual transitions.

Key APIs:

// Property tweening
scene.tweens.add({
    targets: sprite,
    x: 400,
    alpha: 0.5,
    duration: 2000,
    ease: 'Power2'
});

// Timeline sequences
const timeline = scene.tweens.timeline();
timeline.add({ targets: sprite1, x: 200, duration: 1000 });
timeline.add({ targets: sprite2, y: 300, duration: 500 });

Coverage: Individual tweens, tween chains, timelines, easing functions, tween control, property interpolation

Tweens

Data Management

Key-value data storage with event-driven updates for GameObjects and Scenes.

Key APIs:

// Store data with events
scene.data.set('score', 1500);
sprite.data.set('health', 100);

// Listen for data changes
scene.data.on('setdata-score', (parent, key, value) => {
    updateScoreDisplay(value);
});

// Manipulate numeric data
scene.data.inc('score', 100);
sprite.data.dec('health', 25);

Coverage: Scene data management, GameObject data storage, data events, serialization, cross-scene data sharing

Data Management

Events System

Comprehensive event-driven communication system throughout the framework.

Key APIs:

// Event handling
scene.events.on('eventName', callback);
gameObject.on('pointerdown', handleClick);

// Event emission
scene.events.emit('customEvent', data);

// Scene lifecycle events
scene.events.on('preupdate', updateLogic);
scene.events.on('shutdown', cleanup);

Coverage: EventEmitter pattern, scene events, GameObject events, input events, physics events, custom events

Events

Actions System

Batch operations for efficiently manipulating arrays of GameObjects.

Key APIs:

// Bulk positioning
Phaser.Actions.SetXY(gameObjects, 100, 200);
Phaser.Actions.PlaceOnCircle(gameObjects, circle);
Phaser.Actions.GridAlign(gameObjects, { width: 5, height: 4 });

// Visual properties
Phaser.Actions.SetAlpha(gameObjects, 0.5);
Phaser.Actions.SetScale(gameObjects, 2);
Phaser.Actions.RandomRectangle(gameObjects, bounds);

Coverage: Positioning actions, geometric placement, random placement, visual properties, utility operations

Actions

Utilities

Essential utility functions for arrays, objects, strings, device detection, and data encoding.

Key APIs:

// Array manipulation
Phaser.Utils.Array.Shuffle(array);
Phaser.Utils.Array.GetRandom(array);

// Object operations
Phaser.Utils.Objects.Clone(object);
Phaser.Utils.Objects.GetValue(config, 'key', defaultValue);

// Device detection
const device = scene.sys.game.device;
if (device.os.mobile) { /* mobile optimizations */ }

// String utilities
const uuid = Phaser.Utils.String.UUID();
const encoded = Phaser.Utils.Base64.Encode(data);

Coverage: Array utilities, object manipulation, string formatting, device/browser detection, Base64 encoding, NOOP functions

Utilities

Constants and Configuration

Renderer Types

Phaser.AUTO      // Auto-detect (WebGL with Canvas fallback)
Phaser.WEBGL     // Force WebGL
Phaser.CANVAS    // Force Canvas
Phaser.HEADLESS  // Headless mode for testing

Common Constants

Phaser.FOREVER   // -1 (infinite loops)
Phaser.VERSION   // '3.90.0'

Direction Constants

Phaser.LEFT      // 7
Phaser.RIGHT     // 8  
Phaser.UP        // 5
Phaser.DOWN      // 6

Game Configuration

Basic Configuration

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    backgroundColor: '#2c3e50',
    scene: [MenuScene, GameScene, GameOverScene],
    physics: {
        default: 'arcade',
        arcade: {
            gravity: { y: 300 },
            debug: false
        }
    },
    scale: {
        mode: Phaser.Scale.FIT,
        autoCenter: Phaser.Scale.CENTER_BOTH
    }
};

Advanced Configuration

const config = {
    type: Phaser.WEBGL,
    width: 1024,
    height: 768,
    canvas: document.getElementById('game-canvas'),
    canvasStyle: 'width: 100%; height: 100%;',
    scene: {
        preload: preloadAssets,
        create: createGame,
        update: updateGame
    },
    physics: {
        default: 'matter',
        matter: {
            gravity: { y: 0.8 },
            debug: true
        }
    },
    input: {
        keyboard: true,
        mouse: true,
        touch: true,
        gamepad: true
    },
    loader: {
        baseURL: 'https://cdn.example.com/assets/',
        crossOrigin: 'anonymous'
    },
    plugins: {
        global: [
            { key: 'MyPlugin', plugin: MyPluginClass, start: true }
        ],
        scene: [
            { key: 'ScenePlugin', plugin: ScenePluginClass, mapping: 'myPlugin' }
        ]
    }
};

Namespace Organization

Phaser organizes its functionality into logical namespaces:

  • Phaser.Actions - Bulk operations on GameObject arrays
  • Phaser.Animations - Animation system
  • Phaser.Cameras - Camera management
  • Phaser.Core - Core game systems
  • Phaser.Display - Display utilities
  • Phaser.GameObjects - All GameObject types
  • Phaser.Geom - Geometric shapes and operations
  • Phaser.Input - Input handling systems
  • Phaser.Loader - Asset loading
  • Phaser.Math - Mathematical functions
  • Phaser.Physics - Physics engines
  • Phaser.Scale - Game scaling
  • Phaser.Scene - Scene base class
  • Phaser.Sound - Audio system
  • Phaser.Textures - Texture management
  • Phaser.Tweens - Animation tweening
  • Phaser.Utils - Utility functions

This modular organization allows for efficient development and easy navigation of Phaser's extensive API surface covering over 1000 methods across 200+ classes.