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:
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:
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:
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:
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.
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:
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.
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):
If you are a fan of functional programming, there are a few tile access methods that mirror JavaScript’s array methods: filterTiles, findTile. forEachTile.
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:
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:
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:
The Tiled parser has gotten some upgrades along the way – in particular, it can parse text objects and tile collision shapes.
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!
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:
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:
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:
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:
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.
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:
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.
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):
If you are a fan of functional programming, there are a few tile access methods that mirror JavaScript’s array methods: filterTiles, findTile. forEachTile.
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:
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:
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:
The Tiled parser has gotten some upgrades along the way – in particular, it can parse text objects and tile collision shapes.
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!