Getting started with Phaser 3 - samme/phaser3-faq GitHub Wiki

On the web

No setup required. Fork or remix:

You can upload your own assets on Glitch and CodeSandbox.

On your computer

You will need a web server, unless your bundler has one.

You don't have to use a bundler. The simplest setup is one HTML page, a Phaser script (phaser.js), and your game script. You can download the First Phaser 3 game (zip) to start from.

<!DOCTYPE html>
<html lang="en">
<meta charset="utf-8">
<title>Phaser 3 game</title>
<style>html, body { height: 100%; margin: 0; }</style>

<body>
  <script src='https://cdn.jsdelivr.net/npm/[email protected]/dist/phaser.js'></script>
  <script>
    new Phaser.Game({
      scene: {
        create: function () {
          this.add.text(0, 0, 'Hello world');
        }
      }
    });
  </script>
</body>

</html>

Choosing a Phaser script

Generally, use the latest Phaser 3 release for a new project. If you've forked another project or are following a tutorial, use that Phaser version, and consider updating later. The biggest changes are in Phaser v3.50 and v3.60.

You can use any one of the alternative builds:

  • phaser.js
  • phaser-arcade-physics.js — without Matter Physics
  • phaser-facebook-instant-games.js — with Facebook Instant Games
  • phaser-ie9.js — with IE9 support

Use the unminified script (e.g. phaser.js) during development and switch to the minified one (e.g. phaser.min.js) before publishing your game. (I know some tutorials don't do this.) This will make it easier to read errors and step through the code during development.

CDN

I use Phaser 3 on jsDelivr, e.g.,

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/phaser.js" crossorigin></script>

You can choose any script in the dist directory, and you can switch Phaser versions in the dropdown menu. Phaser 3 plugins and types are also in there.

Source code

You don't need to download all of Phaser 3's source code (usually a zip file) unless you want to build it yourself.

If you do have the source code, you can use the script file at dist/phaser.js inside.

Autocomplete, Intellisense, suggestions

If you've installed Phaser with npm then VS Code should find Phaser's type declarations automatically.

If you haven't installed Phaser with npm, you can try copying Phaser's type declarations directly into your project. Make sure the versions match.

Modules

The default Phaser 3 build (phaser.js) is a CommonJS module, not an ES module, so you can't use it as a module directly in the browser:

<!-- NO -->
<script type="module" src="phaser.js"></script>
// NO, unless with a bundler
import Phaser from './phaser.js';

You can write your own code in ES modules; just use the Phaser global like usual.

<script src='phaser.js'></script>
<script type='module' src='main.js'></script>
/* global Phaser */

import { gameConfig } from './gameConfig.js';

new Phaser.Game(gameConfig);

Since Phaser v3.60, there's an experimental ES module build:

import * as Phaser from './phaser.esm.js';

new Phaser.Game(/*…*/);

NPM

npm install phaser

You may want to stay within a minor version, e.g.,

npm install phaser@~3.70

For beta testing:

npm install phaser@beta

Beta releases are uncommon. You can check

npm show phaser dist-tags

You can install from the development branch:

npm install photonstorm/phaser#COMMIT

Then either build Phaser yourself or alias it to src/phaser.js for your bundler.

Custom builds

They're done with Webpack and Phaser's source files. See details in phaser3-custom-build and phaser3-project-template-custom-build. Also possible with rollup.

You'll probably have to customize the entry point imports for each Phaser version. See src/phaser.js for an example.

Terser (minifier)

Remove all comments.

terser({ format: { comments: false } })

or

terser({ output: { comments: false } })

esbuild

Remove all comments.

esbuild.build({ legalComments: 'none' })

Bundlers

Webpack is notoriously complicated, but better than it used to be. Parcel and Rollup are easier. ESBuild and Vite are newer and faster.

Parcel, Vite, and Webpack also bundle static assets, so you have to import them in your Phaser code. The imported value is the URL of the bundled asset, which you'll use in Phaser's load methods. You may be able to find a bundler plugin or build script that copies static assets without bundling them, if you prefer that. You must copy static assets when using multi-texture atlases or Spine atlases, because bundlers can't transform URLs inside those. If you're using npm and Mac/Unix, something like this can work:

{
  "scripts": {
    "prebuild": "npm run copy-assets",
    "prestart": "npm run copy-assets",
    "copy-assets": "cp -Rv src/assets dist/assets"
  }
}

Vite and Webpack convert very small static assets to data URLs, and these can't be loaded in Phaser. Turn off this feature.

Parcel and Vite output URLs from the base /. This is fine if you're publishing to the root of a domain, but if you're publishing to a subdirectory (such as on itch.io), the links will break. Set the base URL to ./ instead.

Some bundler web servers act like a "single-page app" by serving the main page (usually index.html) instead of 404 Not Found for any URL with no matching resource. This is extremely confusing for game development because you'll get errors processing bad assets instead of proper network errors.

You can find project templates on GitHub.

Parcel

Vite

Webpack

Create React App

Typescript

Phaser's type declarations are included if you install with npm. You can also download them from GitHub or jsDelivr, in the types directory. Make sure the versions match.

You may need to use type assertions to resolve some ambiguities.

If you find errors in Phaser's types, open an issue.

Server-side rendering

Turn it off. Phaser can't run outside a browser (and window).

⚠️ **GitHub.com Fallback** ⚠️