FAQ - samme/phaser3-faq GitHub Wiki

How do I learn Phaser?

And see next questions.

I'm new to web development

I'm new to JavaScript

I know JavaScript but I've never made a game before / I've made a game before but I've never used Phaser

Are then any large/real games made with Phaser?

Yes, see featured games.

Should I use Phaser 3 or Phaser 2/CE?

Probably Phaser 3, especially if you're new to both of them.

Phaser 3 doesn't have

Will Phaser 2 code work in Phaser 3?

No.

Should I convert this Phaser 2 project/tutorial to Phaser 3?

Probably not, especially if you're new to Phaser 3.

Does Phaser 3 use PixiJS?

No.

What is Phaser 4?

Phaser 4 is the next-generation version, in development.

When will Phaser 4 be done?

Follow the dev logs on Patreon or the phaser-4 channel on Discord.

Can I use Phaser 4 in production?

No.

Which Phaser am I using?

Look in the browser console after creating a game, or in Phaser.VERSION.

Should I use phaser.js or phaser.min.js?

Use phaser.js until your game is done, then switch to phaser.min.js.

phaser.min.js is the minified (packed) build.

But I switched and now my game doesn't work! :(

That is nearly impossible. Make sure you haven't switched Phaser versions by accident (look in browser console).

Which web server should I use (on my own computer)?

There are many and you may have some already installed.

If you already have Node/npm, then http-server is a good choice. Install once with

npm i -g http-server

Then run in your project directory:

http-server . -c-1 --open

-c-1 means don't cache and --open means open a browser.

How should I organize my project?

There's no particular requirement, except one HTML file that loads the Phaser library and your own game script.

How can I code in modules?

In the browser, you can use ES modules for your own code but not Phaser. You use the global Phaser like usual.

If you're using a bundler, you can import Phaser as a module.

Can I use ES6 syntax?

Yes. If you're publishing a game for general use, you may want to transpile it.

How do I use Phaser with TypeScript?

Since v3.17.0, Phaser's declaration file is included.

It's usually found automatically, but if it's not, you can add node_modules/phaser/types/phaser.d.ts to the files entry of your project's tsconfig file.

Can Phaser do (something) / How can I do (something) with Phaser?

Study the examples.

How do I use the API Reference?

Start at new Phaser.Game() or the Scene menu or search Phaser Chains.

How can I fix errors in the API docs or TypeScript definitions?

Make a pull request. Phaser uses the JSDoc format and generates the TypeScript definitions from them for each release.

How do I use Phaser with webpack?

phaser3-project-template is a simple configuration, and there are others.

How do I make a custom build of Phaser?

See phaser3-custom-build or phaser3-project-template-custom-build.

I tried to run my Phaser game and all I see is a blank page/black canvas.

Open the browser console and look for errors.

Why don't my assets load?

Look in your browser's address bar. If you see a file: URL, you need to run a local web server and open the game from there instead. The URL in the address bar should start with http: or https:, like http://localhost or http://127.0.0.1.

Open your browser's console and look for errors.

If you see Not found errors, open the full URL and check it for mistakes.

If you see error messages similar to Cross origin requests are only supported for HTTP, you need to run a local web server and open the game from there instead.

If you see errors similar to Origin [origin] is not allowed by Access-Control-Allow-Origin, you can try making cross-origin requests.

How do I load cross-origin assets?

Set loader.crossOrigin to 'anonymous' in your game config, or use this.load.setCORS('anonymous'). But this doesn't guarantee the cross-origin request will succeed; the server hosting the asset also has to agree to share it.

If you're loading assets from the same origin (usually the same domain or server), don't set crossOrigin.

Do I have to load the assets I need in every scene?

No. All of Phaser's caches are global. Assets need to be loaded (only once) before they can be used, in any scene.

How do I make a loading progress indicator?

Bind to the loader's start, progress, and loadcomplete events during the preload callback, or earlier.

I need per-file loading progress.

Bind to the fileprogress event.

Can I queue files during loading?

Yes.

How can I make a game object stay the same size when the camera zooms?

How do I pause/resume the game?

Call pause or resume on each scene.

How do I stop the game from pausing when switching tabs/applications?

You can't.

This is not a true game pause but the browser suspending the page, which necessarily halts the update loop.

Use the game events BLUR, FOCUS, HIDDEN, and VISIBLE to respond to these changes.

setTimeout calls may run as often as once per second while in the background, depending on the browser. Web Workers can run more frequently.

How does AUTO choose the renderer?

It chooses WebGL if the device appears to support it and Canvas (2d) otherwise.

How do I make a high-resolution canvas?

In v3.15, pass a resolution value larger than 1 in the game config.

Since v3.16, resolution is unsupported.

How do I scale/resize the game canvas?

Since v3.16, use the Scale Manager.

Why do my sprites look blurry?

Set antialias: false or pixelArt: true in your game config. You don't need to set both.

Why is my text blurry?

Avoid scaling a Text object or the game canvas larger than 100%. Avoid positioning a Text object on fractional pixels or origin.

How do scenes work?

A scene is like a self-contained "world" within the game. Every game has at least one scene. If you've used preload(), create(), or update(), then you've already used a scene.

In multi-scene games, a scene can be a "screen", a menu, a level, or a window.

How do I use this in a scene?

  • Within a scene's method hooks (init, preload, create, update), this is the scene itself.
  • If you define your own scene methods, call them as this.method(…) to keep the scene context.
  • If you pass a callback that uses this, you must also pass a callback context or use an arrow function. Pass this if you want to keep the scene context. An arrow function will also keep the same context.
  • If you pass a callback that doesn't use this, you don't need to pass a callback context.

Can I use just one scene?

For simple games, yes. Most of the examples are written this way.

When should I use different scenes?

It depends, but if you want to pause it, start/restart it, or move it, it could be a scene.

How do I switch scenes?

this.scene.start('key') stops the current scene and starts another (named by 'key'). Using only start, you can move through scenes one at a time.

launch, run, and switch are variations on start. They affect the calling scene differently.

How do I restart a scene?

this.scene.restart() or this.scene.launch('key')

What happens when I stop/restart a scene?

When you stop a scene, the scene's display and update lists are emptied and the game objects they contained are destroyed (unlinked). The scene systems (clock, input, physics, tweens) shut down and clear their own data and event handlers. The scene's own event handlers are not cleared. The scene becomes inactive and invisible, but it's still there, and it can be started again.

When you restart a scene, it's stopped and then started again, calling init(), preload(), and create().

Why do I get errors when I restart a scene?

Look at the error message and trace. You may be able to figure out which object or event handler is involved.

  • Before restarting, remove any scene event handlers (this.events) that reference game objects.
  • Before restarting, reset your own state variables, if you have any.
  • Avoid setInterval() and setTimeout().

What's the difference between a scene's add and make methods?

The add methods use ordered arguments and register the new object with scene.

The make methods use configuration objects and register the new object with the scene only if specified, or by default, depending on the method. You might always pass an add/addToScene value to avoid confusion.

How do I add a child sprite?

Phaser 3's display list is flat (mostly), so there are no child sprites. It does have a special game object, Container, that applies transformations to its children (including other containers).

Blitters and particle managers act like simple containers for their children (bobs and particle emitters).

Can I nest containers?

Yes.

Can I mask a container?

Yes, only if that container is not in another container.

Can I mask a game object in a container?

Yes, only if the mask source is not in the container.

Can I set a container's origin?

No, but you can position children around (0, 0).

How do I extend a game object?

You can use the traditional ES5 form, the Phaser.Class helper, or ES6 classes.

The most common mistake is to add the instance to the scene incorrectly or not at all. From the scene, you can call

// `this` is the scene
this.add.existing( new ExtendedObject(this, x, y, texture, frame) );

or from the class

// `this` is the new game object
this.scene.add.existing(this);

For a physics-enabled game object, use the physics plugin's existing method also:

this.physics.add.existing( new ExtendedObject(this, x, y, texture frame) );

Every game object constructor's first argument is scene. Cannot read property 'queueDepthSort' of undefined often comes from omitting this argument.

When in doubt, imitate the factory method of the parent class. Make sure you're passing every required argument to the parent constructor.

You can also write your own factory method and call it, or register your game object with the plugin manager.

How do I run a game object's update method automatically?

  • Bind the method to the scene's update event (you must also unbind it!); or
  • Add the game object to a group and set the group's runChildUpdate; or
  • Use a plugin

If the game object has a preUpdate method (such as a Sprite, but not an Image), you can override the preUpdate method instead. Make sure you call the parent class's method as well.

How do I make a button?

Make an interactive game object and go from there. See Buttons in Phaser 3.

Do I have to remove tweens when they complete?

No.

Do I have to remove timer events when they complete?

No.

Which physics system should I use?

Arcade Physics is a simple, high-performance model. It uses only circular or rectangular shapes.

Impact Physics is similar. You'll probably use it only if you're already familiar with it (from ImpactJS).

Matter is a full-body physics engine.

Do Arcade Physics bodies rotate?

Geometrically, no.

Can I give a sprite more than one Arcade Physics body?

No.

How do I find out which sprite is colliding?

Use the arguments in the collision callback.

What's the difference between an Arcade Physics body's blocked and touching?

blocked is a collision/overlap with the world bounds, a tile, or a static body.

touching is a collision/overlap between two bodies (dynamic or static), but not embedded.

embedded is a collision/overlap between two bodies where, on at least axis, both bodies aren't moving.

Why do my tilemap tiles show small gaps/lines/seams?

It's a visual artifact of normal WebGL rendering. Use a tool to extrude the tileset image.

Why do I get the warning The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page?

This is normal when using Phaser with Web Audio in Chrome. By itself it doesn't signify a problem. Phaser will automatically resume the audio context when the user clicks/taps. Sound may be muted before that, though.

If your game doesn't use sound, disable it and you won't see the warning:

new Phaser.Game({ audio: { noAudio: true } });

How do I fix/debug my game?

  • Open the console. Read errors and warnings.
  • Expand error stack traces. Find the last point your own code was involved.
  • Break on exceptions. Examine values in the debugger.
  • If the problem isn't in the paused function, step backwards through the call stack and find it.
  • Don't use the minified script (phaser.min.js) during development; the traces are hard to read. Use phaser.js instead.

Use Phaser's debugging tools:

Use a plugin:

Check your code against Phaser's API documentation.

Use your browser's debugging tools. You don't have to use Chrome; most of these are similar across the main browsers.

A few tools can be especially helpful for games:

Cannot read property 'property' of undefined / undefined is not an object / undefined is not a function

You tried to read a property from an undefined value, which is impossible (undefined has no properties).

You need to find the expression that evaluated to undefined. Firefox and Safari give more helpful error messages in this respect.

If this is involved, you've likely made a scope error: either accessing an undefined scope (this === undefined) or a scope different from the object you're expecting (so missing the named property).

How do I ask for help?

Help people help you. :)

Clearly describe your original problem, e.g., what you expect to happen and what happens instead. Remember only you know how your game is supposed to work and what it's supposed to look like.

Provide a runnable example or the minimal code to produce the problem.

If there is an error message, include the error message and trace.

I want to X but it doesn't work, by itself, is not a good way to ask for help.

Why doesn't my question get answered?

Possibly:

  • It's not clear what you're asking
  • You haven't given enough information
  • The code is too long/complex to assess
  • People who know the answer haven't seen your question yet

Why is my game slow?

Use your browser's Performance/Profile/Timeline tool to identify bottlenecks. Usually, you'll use the Bottom-Up view or sort by Self Time.

Generally, it depends, but try:

  • Combine images into atlases/spritesheets
  • Render same-texture and same-blend-mode objects consecutively (by keeping them adjacent on the display list)
  • Reduce the use of nested Containers, complex Graphics, or Text
  • Reduce texture dimensions
  • Reduce game canvas dimensions

If the game slows consistently over a few seconds, you may have made a programming mistake, e.g.,

  • drawing repeatedly to a Graphic without clearing it
  • adding duplicate event handlers

Where can I publish my game (for free)?

On itch.io (cli) or GitHub Pages or Surge.

Node-based apps can be deployed on Heroku.