Phaser Tiled
This is a replacement for the tilemap implementation in the Phaser game framework.
The purpose of this plugin is to optimize the tilemaps for large complex maps built with
the Tiled Map Editor.
This plugin optimizes the rendering of large scrolling tilemaps. It also adds support for
many more Tiled features and lots of advanced functionality. You can read Why use this plugin?
below for more details
Usage
Simply download the dist/phaser-tiled.js
script and include it on your page after including Phaser:
<script src="phaser.js"></script>
<script src="phaser-tiled.js"></script>
After adding the script to the page you can activate it by enabling the plugin:
game.add.plugin(Phaser.Plugin.Tiled);
Then you can add a Tiled map to your game like this:
var cacheKey = Phaser.Plugin.Tiled.utils.cacheKey;
game.load.tiledmap(cacheKey('my-tiledmap', 'tiledmap'), 'assets/levels/tilemap.json', null, Phaser.Tilemap.TILED_JSON);
game.load.image(cacheKey('my-tiledmap', 'tileset', 'tileset1-name'), 'assets/levels/tileset1.png');
game.load.image(cacheKey('my-tiledmap', 'tileset', 'tileset2-name'), 'assets/levels/tileset2.png');
game.load.image(cacheKey('my-tiledmap', 'layer', 'layer-name'), 'assets/levels/layer.png');
var map = game.add.tiledmap('my-tiledmap');
That can get pretty heavy, and hardcoding what to load and how to name it can stink! Luckily, there is an easier
way to handle it. Instead of hard-coding what the tilemap should load and be named, this plugin has a gulp task
that can generate a Phaser Asset Pack that describes what and how to load the tiledmap. If you have this pack
it becomes this simple to load and create a tiledmap:
game.load.pack('my-tiledmap', 'assets/levels/tilemap-assets.json');
var map = game.add.tiledmap('my-tiledmap');
Wow, that was a lot easier! You can find out more about the generator on it's GitHub page.
Physics
This plugin comes with a couple ways to implement physics for your games. Right now the only officially supported engine
is p2.js, but hopefully arcade and others can join the party soon (need it now? submit a PR!).
Using the object tools
To create the physics bodies based on a tilemap, the simplest way is to create an object layer in Tiled Editor and use
the object tools to draw physics. You can use the rectangle, ellipse, polygon, or polyline tools. The only caveats are
that circles (not ellipses) are supported so height and width of the ellipse must be the same, and if you use the polyline
tool be sure to close the path to make a convex polygon!
Here is how you can convert your objects into collision bodies:
var map = game.add.tiledmap('tilemap-key');
game.physics.p2.convertTiledCollisionObjects(map, 'objectlayer-name');
That is it! All the objects in the layer named objectlayer-name
will be converted to p2 physics bodies and added
to the simulation.
Using collidable tiles
The second method is to set the collides
custom property on tiles in a tileset to true
. This tells the engine that
that specific tile is collidable wherever it is in the map, and a body will be created for it.
Here is how you can convert your collidable tiles into collision bodies:
var map = game.add.tiledmap('tilemap-key');
game.physics.p2.convertTiledmap(map, 'tilelayer-name');
That is it! All the collidable tiles in the layer named tilelayer-name
will be converted to p2 physics bodies
and added to the simulation. This will also try to combine bodies that are adjacent on the same X axis into a single
body to reduce the total number of bodies that are created. This algorithm can (and should) be much improved.
Why use this plugin?
Here are some features this plugin has that Phaser doesn't, or that this plugin
tries to do better:
- Faster render times
- Support for Tiled XML format
- Support for tile flipping
- Support for animated tiles (added in Tiled v0.10.0)
- Automatic layer creation from tiled data
- Automatic tileset creation from tiled data
Show me the performance!
Using a large test map with 256x256 tiles, each 16x16 pixels, and 3 layers of them. phaser-debug
gives me this performance graph for the core phaser tilemap implementation:

The spikes you see there are when I pan around the map. Using the same map with this plugin I get this:

Supported custom properties
Tilemap
None, yet.
Tileset
None, yet.
Tileset Tile (specific tile in the tileset)
collideLeft
- true will make this tile collide on the leftcollideRight
- true will make this tile collide on the rightcollideUp
- true will make this tile collide on the topcollideDown
- true will make this tile collide on the bottomcollides
- true will set all collision sides to true, if that collision side doesn't have a specific overrideblendMode
- string of the blendMode constant to use for this tile (e.g. 'NORMAL')
Tile Layer
batch
- true will place tile sprites into a SpriteBatch container.
Object Layer
batch
- true will place object sprites into a SpriteBatch container.blendMode
- string of the blendMode constant to use for all objects in this layer (e.g. 'NORMAL').
Object Layer Object (specific object in the layer)
blendMode
- string of the blendMode constant to use for this object (e.g. 'NORMAL')
Image Layer
None, yet.
Tiled features not yet implemented:
- Object layers
- Image layers
- Multi-image tilesets
Phaser Tilemap API features still needed:
Layer Properties:
- tileColor
- wrap
- scrollFactor
Map Methods:
- setTileIndexCallback
- setTileLocationCallback
- setCollision
- setCollisionBetween
- setCollisionByExclusion
- setCollisionByIndex
- copy
- paste
- swap
- swapHandler
- forEach
- replace
- random
- shuffle
- fill
Object Layer:
- object spritepool to pull custom object from
- Test, only minimally implemented right now
Image Layer:
General:
- Rerender on resize/rescale seems off
- Tile render debug stuff (edges, physics, etc)
- Memory optimizations