How to create custom builds for Phaser
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
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
grunt custom --exclude gamepad,keyboard --filename phaser-nokeys
This will create two files:
phaser-nokeys.js and a minified version in
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
grunt custom --exclude gamepad,keyboard --filename phaser-nokeys --sourcemap true
7. Preset builds
There are 4 predefined builds you can use. They are:
This is the full version of Phaser with all modules enabled with the exception of Ninja Physics. It's our kitchen-sink build.
This is Phaser with Arcade Physics, Tilemaps and Particle support. It excludes P2 Physics and Ninja Physics.
Phaser without any of the physics systems, Tilemap or Particle support (as they both rely on Arcade Physics).
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:
|intro||Phaser UMD wrapper|
|bitmapdata||BitmapData Game Object|
|graphics||Graphics Game Object|
|rendertexture||RenderTexture Game Object|
|text||Text Game Object (inc. Web Font Support|
|bitmaptext||BitmapText Game Object|
|retrofont||Retro Fonts Game Object|
|video||Video Game Object|
|rope||Rope Game Object|
|tilesprite||Tile Sprite Game Object|
|sound||Sound Support (Web Audio and HTML Audio|
|creature||Creature Animation Tool|
|particles||Arcade Physics Particle System|
|outro||Phaser UMD closure|
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.