Phaser 4 Encyclopedia

What is Phaser 4?

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Phaser 4 is a 2D game framework for the web. It renders to WebGL (with a Canvas fallback), runs in every modern browser, and ships as a TypeScript-first library.

A scene-based architecture for organizing game state and rendering. A retained-mode display list of game objects (sprites, text, shapes, containers). An asset loader with a typed cache. Pluggable physics (Arcade for fast AABB, Matter for full rigid-body). Input across keyboard, pointer (mouse + touch), and gamepad. A tilemap system, particle system, animation manager, audio pipeline, and a tween engine for property interpolation.

Installation

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Phaser 4 ships its own TypeScript types — no needed.

For quick experiments or single-file demos:

tracks the latest 4.x release. Pin to an exact version (e.g. ) in production so a new release can't shift your behavior. See the changelog for current releases.

Verifying the install

The smallest possible Phaser 4 program — a black canvas, ready to receive game objects:

If you see the text on a black background, you're set up. Continue to Your First Scene.

Your First Scene

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

A Phaser 4 program is, at minimum, a configured with at least one . A scene has three lifecycle hooks you'll use constantly:

— load assets into the cache. — build the initial scene graph. — run per-frame logic.

Here is the smallest interesting program: a sprite that bounces around its bounds. Edit the source in your own project and the same code will run identically.

**** asks Phaser to pick the best renderer (WebGL where available, Canvas otherwise). The config enables Arcade physics with no gravity, so the sprite moves in a straight line until something deflects it. queues an asset; the l…

Project Setup

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

For a sketch or single-file demo, the installation snippet is enough. For a real project, a few decisions will save you weeks.

Vite is the recommended starting point — Phaser 4 ships ESM, and Vite handles asset URLs and HMR with no config.

A layout that scales from a jam game to a shipped project:

Keep import-free of Phaser where you can — pure logic is easier to test.

Phaser 4 ships strict types. Use them:

Vite HMR works for everything outside a running scene. To pick up changes inside a scene, restart the scene with or use a dev-only key binding to do so.

Core Concepts

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

The pages in this section explain why Phaser is shaped the way it is. They are not recipes — see Guides for those — but the vocabulary on this page reappears across the rest of the encyclopedia.

The Game Loop — how and are scheduled, and what actually means. Scenes — Phaser's unit of "screen" or "mode," and how multiple scenes coexist. Game Objects — the retained display list, transforms, and the difference between an and a . Cameras — viewports, scroll, zoom, and effects. Input — keyboard, pointer, and gamepad, and how Phaser routes events to objects. Loader & Assets — the loading pipeline a…

The Game Loop

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Every frame, Phaser does roughly this:

Drain the input queue (pointer, keyboard, gamepad events received since the last frame). Call each active scene's . Step the physics world. Render the display list to the canvas.

is a monotonic millisecond timestamp; is the milliseconds elapsed since the previous frame.

Frame-rate independence

The single most important rule:

> Multiply movement and rates by , not by a constant.

This applies to physics velocities you set manually, animation timers, particle emission rates, and anything else expressed as "per second."

Scenes

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

A Scene is a self-contained world: it owns a display list, a camera, an input handler, and (optionally) a physics world. A runs one or more scenes; each has its own update loop.

A scene that's stopped and later started again sees / / fire afresh — pair every with the it cleans up after.

Multiple scenes at once

Scenes are not mutually exclusive. Common patterns:

A persistent HUD scene runs in parallel with the gameplay scene. A pause menu scene sits on top; the gameplay scene is paused but not stopped. A long-lived audio or save scene exists purely for cross-cutting state.

Game Objects

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

A Game Object is anything that lives in the scene graph and can be rendered, transformed, or hit-tested. Phaser uses retained-mode rendering: you create objects once, mutate their properties, and the renderer draws whatever currently exists. There is no per-frame "draw a sprite at (x, y)" call.

Rule of thumb: reach for first; promote to only when you need animations.

The transform hierarchy

Containers form a tree. Each child's world transform is its local transform composed with its parent's. This is how you build composite objects:

Cameras

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

A Camera is a viewport onto the scene's world space. Every scene has at least one (); you can add more for splits, minimaps, and picture-in-picture.

World vs. screen coordinates

World coordinates are where game objects live. They do not change when the camera moves. Screen coordinates are where pixels land on the canvas.

The camera maps one to the other via , , and . When you need a screen-space overlay (HUD), put it in a separate scene whose camera does not scroll.

The lerp factors smooth the follow — is instant, never moves.

Built-in transitions:

Input

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Phaser unifies keyboard, pointer (mouse + touch), and gamepad behind a single input manager exposed as .

Polling fits continuous actions (movement); events fit discrete actions (jump, fire, menu select).

The pointer always reports screen coordinates. Use to translate.

Per-object interactivity

For "click this sprite" semantics, opt the object in:

Phaser tests the object's bounds (rectangle by default; pixel-perfect if requested) and only fires events when the pointer actually intersects.

Gamepad support is off by default — enable it in the game config:

Loader & Assets

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Each scene has a Loader () that queues asset requests during . When returns, the loader runs to completion before is called.

Each entry registers under a string key. The corresponding cache exposes typed accessors — , , etc.

To show a progress bar, listen on the loader during :

A common pattern is a tiny Boot scene that loads the loading bar's own assets, then transitions to a Preload scene that loads everything else.

You can call after , but you must explicitly start the loader:

Useful for streaming-in level data, but prefer eager loading where you can — the runtime cost of a mid-game st…

Guides

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Guides are how-to documents. Each one walks through a single task end to end, with working code. If you want the why, see Core Concepts; if you want the what, see the API Reference.

Physics - Arcade physics — fast AABB collisions for platformers, shmups, and most arcade-style games. - Matter physics — full rigid-body simulation with joints and stacking. Tilemaps — loading Tiled maps, layers, and collision. Animation — frame animations and the animation manager. Tweens — interpolating any numeric property over time. Audio — Web Audio integration, music, and spatial sound. Particles — the par…

Arcade Physics

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Arcade is Phaser 4's fast physics system. It models everything as axis-aligned bounding boxes (AABBs) or circles — no rotation, no rigid-body stacking, no joints. In exchange you get a system fast enough to step hundreds of bodies per frame on a phone.

Use Arcade when all of these are true:

You don't need rotational physics ("a tilted box rests on a slope"). You don't need stacking ("boxes pile up correctly"). You don't need joints, constraints, or compound bodies.

Most platformers, top-down adventures, shmups, brick-breakers, and casual puzzle games fit. If you find yourself fighting Arcad…

Matter Physics

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Matter is the heavyweight physics option. It models true rigid bodies — with rotation, friction, restitution, joints, constraints, and arbitrary polygon shapes — at the cost of more CPU per body and a more complex API surface.

Choose Matter the moment you need any of:

Rotation. A tilted box that comes to rest on a slope at the correct angle. Stacking. A pile of boxes that settles realistically. Joints / constraints. Ropes, chains, hinges, springs, motorized wheels. Compound bodies. A vehicle with a chassis plus separate wheels. Polygon collision. A non-rectangular hitbox.

Tilemaps

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Phaser 4's tilemap system reads Tiled JSON exports. You author the map externally and let Phaser handle rendering, collision, and runtime mutation.

Two files are involved: the map JSON and the tileset image referenced by it.

Then assemble the map and its layers:

The third and fourth args are world coordinates of the layer's top-left corner — usually .

Three idiomatic ways to mark which tiles collide:

For one-way platforms, slopes, and other angle-aware collision, see the API reference — methods and the Arcade-specific cover most cases.

Animation

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Phaser 4's animation system plays sequences of texture frames on a . Animations are defined once at the scene level (or globally) and then played on any number of sprites — the definition and the playback are separate.

Where animations live

* — the scene-level animation manager. Animations live here by default. (rare) — a global manager you can use to share definitions across scenes.

Almost always use the scene-level manager. Cross-scene sharing tends to leak state.

Defining an animation

You need a source — a spritesheet (uniform frames) or an atlas (named frames, irregular):

Tweens

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

A tween interpolates a value over time. You point a tween at one or more objects and tell it what properties to change, how, and over what duration — Phaser handles the per-frame math.

Tweens are the single most-used utility in Phaser code: fades, eased camera moves, UI bounce, dialog reveals, value animations driving custom logic.

Reads as: "move to 400 over 1000ms, using the default easing." Phaser captures the current value of at the moment the tween starts and interpolates from there.

A tween can drive any number of objects at once:

Audio

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Phaser 4 wraps the browser's Web Audio API behind . You load audio through the standard loader and play it through a typed sound manager.

Always ship at least two formats. OGG covers Firefox and Chrome; MP3 or M4A is needed for Safari.

returns the sound but doesn't keep a reference — use + whenever you need to control the sound after starting it (pause, fade, change volume).

The user-gesture unlock

Browsers refuse to start audio until the page has received a user gesture (click, key press, touch). Phaser detects this and unlocks the audio context on the first input — but any sound you try…

Particles

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

A particle emitter spawns many short-lived sprites with randomized properties and (optionally) interpolated lifetimes. Phaser 4 ships a single emitter class that covers everything from a smoke trail to a screen-shaking explosion.

The shape of an emitter

Per-particle randomness via range objects. randomizes the initial value; interpolates from start to end over the particle's lifetime. Per-emitter rate via + . Together they set "particles per second." switches to explosion mode — emit particles at once when is called.

Shaders

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Phaser 3's system is gone in Phaser 4. Three replacements cover almost every use case:

Pipelines, , , and no longer exist. If you're porting from v3, see Migrating from Phaser 3 for the mechanical swaps.

Filters: the built-in catalogue

Every game object and every camera exposes a property with and filter lists. Internal filters affect the object itself; external filters affect the rendering context (typically full screen).

The full set ships with v4: , , , , , , , , , , , , , , , , , , , , , , , . Each call returns a Controller you can tweak or remove later:

Plugins

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

A plugin is a self-contained module that hooks into Phaser's lifecycle. Phaser 4 supports three shapes, each with different scope and lifecycle:

Pick the smallest scope that fits. A global plugin that only one scene uses is just a leak.

A class extending . It's instantiated once when the game starts and exposed via from anywhere.

instantiates immediately; exposes it as on every scene. Without , you reach for it via .

A class extending . Each scene gets its own instance, and the plugin can hook into the scene's lifecycle events:

Scene transitions

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

swaps scenes hard — the outgoing scene's fires before the incoming scene's . gives you an overlap window where both scenes run together, perfect for crossfades, slide-ins, and "wipe one scene off the screen while the next slides on" effects.

Reads as: "start running alongside me; for the next 600ms call with progress; when it ends, do X to me (sleep / shutdown / remove)."

The target scene's and fire immediately. Its runs every frame from frame zero of the transition. The outgoing scene keeps updating too (unless you stop it from the ).

Examples

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Every example here runs in a sandboxed iframe with a pinned Phaser 4 build. The source on the page is the exact source being executed — there's no hidden setup.

Basic sprite — load a texture and draw it. Keyboard movement — WASD / arrows moving a sprite, polling style with delta-time velocity. Scene transition — fade between two scenes using the camera fade API. Tween chain — chain a sequence of tween effects on a single target. Collision response — click to drop physics balls that collide with each other and the world bounds. Particle burst — click anywhere to fire a one-shot explosion using…

Basic sprite

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

picks WebGL where supported, else Canvas. mounts onto the provided by the playground iframe. The image is loaded over the network — the playground will show a brief blank canvas while it resolves.

Keyboard movement

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Click the playground first so the iframe receives keyboard focus. gives you ready to poll. lets you offer WASD parity with a one-liner. Movement is — pixels per second, framerate-independent. See The Game Loop. Polling style fits continuous movement; events fit discrete actions (jump, fire). See Input.

Scene transition

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

The array registers multiple scenes; the first runs by default. darkens the camera; is the inverse. The completion is signalled by the event — perfect place to swap scenes. replaces the current scene (vs. which runs in parallel — useful for HUDs and pause menus). See Scenes for the rest of the lifecycle.

Tween chain

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Each item in is a full tween config — its own , , , callbacks. The chain runs them sequentially, capturing the current value of each property as it starts. The outer re-arms the chain — the "perpetual loop" pattern. (You could also use on a regular tween for simpler loops.) See the Tweens guide for chain, value tweens, and the rest of the API.

Collision response

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

A physics group with keeps every member inside the canvas. makes group members collide with each other — the second pass over the group is what gives you ball-on-ball bouncing. switches the body from the default rectangular AABB to a circle. Phaser's Arcade defaults to rectangles even for round sprites. Pointer events fire on the iframe — / are already in canvas coordinates. See Arcade Physics for groups, colliders, overlaps, and the rest.

Particle burst

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

* stops the emitter from spawning particles continuously, freeing you to fire bursts on demand. spawns particles immediately at the given world position. * gives the bright "glow" look — switch to if you want crisper, less hot-looking particles. The emitter itself lives at — particle positions are absolute since we override with . For a follow-the-player trail, position the emitter and use the default emit-from-center behavior. See the Particles guide for emitter zones, common recipes (smoke / explosion / trail), and performance.

Physics overlap (pickups)

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

Click the playground to give it keyboard focus first. vs. : overlap fires a callback when bounding boxes intersect without separating them — perfect for pickups, triggers, hitboxes. separates the bodies and stops them interpenetrating — for walls, floors, enemies. Group convenience: a single covers every coin in the group. No per-coin wiring. **** removes the coin from the scene and the group; subsequent overlap checks skip it automatically. See Arcade Physics for groups, dynamic vs. static bodies, tunneling pitfalls, and debug rendering.

Shader filter (Glow)

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

* is one of Phaser 4's built-in filters. The full set: , , , , , , , , , , , , , , , , , , , , , , , . vs. lists: internal filters affect just the object; external filters affect the object in its rendering context (typically full screen). Glow usually wants since the light spreads beyond the source pixels. The returned Controller is a normal object — properties like , , and are tween-friendly, which makes it trivial to animate the effect. Note: Bloom isn't a single filter.* v3 had a FX; in v4 it's composed via , which sets up multiple filters internally via . The Glow filter above is the si…

Glossary — Phaser terms for web developers

Konstantin Ryzhov — Sat, 30 May 2026 00:00:00 GMT

A consolidated list of the Phaser 4 terms used throughout this encyclopedia. Phaser runs right in the browser on JavaScript/TypeScript, so the web analogies here are especially close.

Game — the root object (): it creates the canvas, starts the game loop, and wires up the render, input, audio, and scene managers. Analogy: the application root () mounted into the DOM once.

Scene — a self-contained "screen" or mode: it owns its display list, a camera, an input handler, and (optionally) a physics world. Analogy: a route in an SPA. Scenes aren't mutually exclusive — several can run in parallel (…