Custom Phaser 2 Builds

With the release of Phaser 2.3.0 we introduced the ability for you to customise exactly which modules are built into Phaser, and which are excluded.

In previous versions of Phaser we adopted something of a 'kitchen sink' approach, whereby lots of features were bundled in with no way to turn them off. This lead to some quite large build file sizes, even if you didn't need lots of the capabilities present in there.

With 2.3.0 this changed. We made steps to carefully break Phaser up into more logical chunks and it's something we'll continue to evolve in future releases. This guide will show you how to create your own custom builds, saving file size and bandwidth in the process.

1. Install Grunt

You will need grunt installed locally to run our build scripts. Grunt has a comprehensive Getting Started Guide that you'll need to run through if you're unfamiliar with it.

2. Clone the Phaser git repository

With Grunt installed you need to clone the Phaser git repository. There are many different ways to achieve this: from using a visual client such as SmartGit or GitHub for Windows to doing it from the command-line. Whatever your preference clone the Phaser repository locally.

3. npm install

Open a command-prompt or terminal and navigate into the cloned phaser folder. Once there issue the command npm install. This will pull down all of the packages that Phaser requires to run its build scripts.

4. Creating your first custom build

Inside the Phaser folder issue the command grunt custom. Without any parameters it will output the help files including a list of all optional modules:

The module list is likely to change with future Phaser versions, so don't be alarmed if yours has different modules to those in the screen shot above.

The Phaser build scripts work on the principle of telling Phaser what to exclude from the bundle. Let's create a custom build for a game that was created entirely for mouse and touch input. Because of this we know it doesn't need either the Gamepad or Keyboard Input modules, so we exclude them:

grunt custom --exclude=gamepad,keyboard

The build script will now run through its tasks. First it cleans out the dist folder and then it processes all of the Phaser source files, excluding those that we specified:

When the tasks have finished it will have created 2 files inside the dist folder: phaser.js and phaser.min.js.

These files are your custom build of Phaser. That is all of Phasers features except for the Gamepad and Keyboard APIs. If you try and access either of those APIs in your game code it will likely throw an error, so only exclude modules you know you don't need.

5. Specifying your own filename

You can tell the build script to create your version of Phaser with your own filename. Just provide a filename parameter:

grunt custom --exclude=gamepad,keyboard --filename=phaser-nokeys

This will create two files: phaser-nokeys.js and a minified version in phaser-nokeys.min.js.

Note: Don't include the .js part of the filename in the parameter

6. Creating Source Maps

The build script can create a source map for your custom build. Just provide the parameter --sourcemap true and as well as the JavaScript files a sourcemap will also be generated:

grunt custom --exclude=gamepad,keyboard --filename=phaser-nokeys --sourcemap=true

7. Preset builds

There are 4 predefined builds you can use. They are:

grunt full

This is the full version of Phaser with all modules enabled with the exception of Ninja Physics. It's our kitchen-sink build.

grunt arcadephysics

This is Phaser with Arcade Physics, Tilemaps and Particle support. It excludes P2 Physics and Ninja Physics.

grunt nophysics

Phaser without any of the physics systems, Tilemap or Particle support (as they both rely on Arcade Physics).

grunt minimum

A bare-bones Phaser build. Every possible module is excluded with the exception of Pixi and the UMD wrappers. This is as small as it gets at the moment - the final build file is only 83KB minified and gzipped.

8. Modules List

As of Phaser 2.4.0 the list of optional modules are:

9. Knowing what to exclude

Most of the modules should be obvious if you can exclude them or not. For example if you don't use P2 physics anywhere in your game then remove it from the build and you'll save hundreds of KB from the file size.

If you don't use Tilemaps then also exclude those. The build script is intelligent enough to know to only exclude the Tilemap part of Arcade Physics, so you can still use Arcade Physics in your game.

Finally lots of games don't actually have any sound - in which case removing the Sound Manager will help save from the file size.

If when you exclude a module it has dependencies the build script will warn you. For example you cannot exclude the RenderTexture module but still use RetroFonts as they rely on RenderTexture to work. There are not many couplings like this, but the build script will prompt you when it can.

In short - try to exclude as much as you can, but if your game suddenly breaks then start introducing modules back in again until you know which one caused it.