Skip to content

Getting started with Phaser 3

Jump to bottom
samme edited this page Apr 22, 2023 · 58 revisions

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, 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 you can 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. Plugins and types are also in there.

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

Phaser 3 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.

/* global Phaser */

import { gameConfig } from './gameConfig';

new Phaser.Game(gameConfig);

NPM

npm install phaser

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

npm install phaser@~3.55

For beta testing:

npm install phaser@beta

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.

Bundlers

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

Some bundler matters:

  • Parcel, Vite, and Webpack also bundle static assets, so you have to import them in your Phaser code.

You can find project templates on GitHub.

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.

Clone this wiki locally