Warning

Due to the rapid pace of change some links or details may no longer be correct.

Published in Phaser World Issue 108 on 4th December 2017 by Richard Davey   @photonstorm

Phaser 3 Tilemap API and Sound Manger updates covered in detail.

You can try all new features shown in this Dev Log in Phaser 3 Beta 13. Grab it from GitHub pre-built, or from npm using the beta tag.

This issue we've updates to the Sound API and massive report on the state of the Tilemap API with loads of new demos and example code. Felipe has been hard at work implementing pre-multiplied alpha support, which we'll cover next issue. And I've been all over the API. From fixing bugs in the matter.js API, to adding features into Group, to adding support for right-to-left Text objects (brand new to V3). It's been quite a week with progress across the whole API. I also had time to create a little game which I'll cover next issue. For now, dig into the two huge updates we've got for you now ...

Sound API Update

Here's the latest on the new Sound Manager from Pavle:

This week I took some time to test what’s been done with the Sound API on mobile devices and came across a few issues

One was related to the detune option - turns out that Webkit implementation of Web Audio API (used mainly in Safari and older browsers) doesn’t support detune option natively.

Some of you guys on slack pointed out that my explanation of detuning few issues ago was a bit vague so I’m gonna go into more detail now :)

Both rate and detune settings determine the speed at which the audio will play. For example, setting the rate to 2.0 will have the same effect as setting detune to 1200 and will double the speed (and raise the pitch by one octave). On the other hand setting rate to 0.5 will have the same effect as setting detune to -1200 and will halve the playback speed (and lower the pitch by one octave), and they can be used in combination.

Having both of these options allows you much more control over the playback speed and I didn’t want to ditch detuning just because it was not supported by all Web Audio implementations. I did some research and managed to accomplish the same effect, that native detune option provides, by using
some clever math. Another good thing is that this approach can be used with HTML5 Audio as well, which of course does not support it natively either, so you can expect the same behavior across all browsers and platforms.

Here is an example that demonstrates how the rate and detune can be used along with mute and volume options:

image

Another neat thing is that last week’s work done on adding markers made it very easy to add support for audiosprite tool. I have remade one of the markers examples to use audioprite to show you how to make use of it in your own projects:

image

Tilemap API Update

Michael has completed his work on the new Tilemap API. It's looking incredible and here's an extended feature on what you can now find in Beta 13:

This week was focused on getting the final touches on the Tilemap API in place. Aside from Physics integration, the Tilemap API is stable, documented and chock full of examples. You can skip straight to Phaser Labs and see the 20+ new examples, or jump into the weeds with me below. One particular example worth checking out is the roguelike dungeon generator. It generates a random map with connected rooms and then uses some of the new API features to fill in the details:

image

Two weeks ago, I demoed how you can create a map with static or dynamic layers from a JSON file, a CSV file or a plain ol’ 2D. Now we can jump into some of the fun things you can do with those maps, once they’ve been created. A quick refresher first:

image

One area where things have been improved in the new API is with tile operations – getting, putting, removing, etc. tiles. In v2, TilemapLayers and Tilemaps had different methods – you could shuffle the tiles by map.shuffle(…), but you couldn’t call layer.shuffle(…). Conversely, you could layer.getTiles(…) but not map.getTiles(…). All the tile methods in v3 - GetTileAt, HasTileAt, WorldToTileXY, etc. - can be invoked on a map or on a static/dynamic layer.

image

Note: Tilemaps keep track of the current layer and apply tile operations on that layer, if no explicit layer is specified. There’s only one layer in that example, so you can use map.getTile(…) and layer.getTile(…) interchangeably. With multiple layers, you can set a map’s current layer using the map.layer property or map.setLayer(…). Check out the example below to see that in action:

image

Of course, there is an important exception to this idea of unifying map and layer methods! Any method that mutates tiles (e.g. shuffle, removeTileAt) is not available on a StaticTilemapLayer.

image

I won’t bore you with listing all the tile access & manipulation methods, but suffice it to say there’s one for each method from v2 and then some. I’ll highlight some of the new features.

You can now get tiles within a shape (and optionally filter out non-colliding, empty or non-interesting tiles):

image

If you are a fan of functional programming, there are a few tile access methods that mirror JavaScript’s array methods: filterTiles, findTile. forEachTile.

image

There are some upgrades to tile manipulation. In addition to randomize, there’s a weightedRandomize method that gives you more control over randomizing tiles. There is also a putTilesAt method, which gives you the ability to “stamp” out rows or grids of tiles into a map really easily:

image

image

image

Instead of creating layers from 2D arrays/CSV/JSON, you can also create blank layers in v3 and then use any of these handy tile manipulation methods to create your map on-the-fly. Although blank layers must be dynamic, there’s a way to convert a layer from dynamic to static, so you get the benefits of the dynamic map methods when initially creating a level, but then the zippy performance of a static map when it comes to rendering. Check out these examples:

image

image

Another improved area of v3 is tile position world position conversions. Any method that has “world” in its name is referring to pixel position with layer scale & position and camera scroll all factored in. (v2 had a couple different meanings of “world” mixed together.) You can check out an updated previous example to see that in action with the new Pointer#positionToCamera method.

While tilemaps aren’t integrated with the shiny new Physics systems yet, you can still mark tiles for collision. There’s a new renderDebug method that will allow you to visualize colliding tiles and edges:

image

image

The Tiled parser has gotten some upgrades along the way – in particular, it can parse text objects and tile collision shapes.

image

Whew! If you read all that, feel free to have a look at the source code on GitHub to see what else is new.

Phaser 3 Labs

Phaser 3 Beta 13 is out and ready for testing.

Visit the Phaser 3 Labs to view the new API structure in depth, read the FAQ, previous Developer Logs and contribution guides.

You can also join the Phaser 3 Google Group or post to the Phaser 3 Forum - we'd love to hear from you!