Matter.js physics lands in V3. Sound API updates and work on rendering displays.
Another week and another huge load of work completed. You can try all new features shown in this Dev Log in Phaser 3 Beta 12. Grab it from GitHub pre-built, or from npm using the beta tag.
Sound API Update
Pavle reports on progress to the Sound API: Although I said that adding support for looping and seeking is next on the list I decided to work on
making basic playback options more solid before moving on to more advanced things, so I added support for sound markers first.
A sound marker is part of sound represented by a unique name and a start time and duration. This allows you to bundle multiple sounds together into a single audio file and use markers to jump between them for playback.
Addition in v3 compared to v2 is that marker can contain a config property, the same as the one that you would pass to sound play or add methods, so that each marker can play at different playback rate, at different volume level etc.
I’ve also exposed two additional properties on sound objects: duration and totalDuration.
Duration holds the value of currently playing marker duration or duration of the entire sound if no marker is being played, while totalDuration represents the duration of the entire sound - obviously. :D
Without this, you wouldn’t be able to make a music player in Phaser, which I mentioned in the previous issue, as you need to know the duration of a sound in order to display its value and position correctly playback slider cursor.
I’ve recreated two examples from v2 to demonstrate how to use markers in v3, so if you feel a bit nostalgic go check them out and play around with different config values!
Tilemap API Update
Mike reports on the updates to the Tilemap API: "It was a short week here in the states because of Thanksgiving, but the Tilemap API still marches forward:"
The Tiled parser has been modularized and updated. It can read in layer offsets and properly apply them to objects within layers. It can also parse Tiled’s text objects, so you could potentially visually lay out a HUD in Tiled and generate it in Phaser.
Tiles can be set to collide, so everything is in place for physics integration. (A small technical note - recalculating interesting faces is magnitudes faster in a few important cases, so you probably won’t often need to think about preventing recalculations like in v2.)
The documentation effort is now well underway.
And last but not least, v3 now has the ability to get tiles that overlap with a geometry shape. You can see this in the screen shot below (it's not a demo yet, so don't try and click it).
Pre-Multiplied Alpha
Felipe writes: "The past week was mostly fixing already present issues on the WebGL rendering backend. Some really small that only affected specific parts and others that affect large chunks of the code.
The most important issue I fixed was getting the correct colors to appear when you scale and rotate textures by using pre-multiplied alpha. Read this NVIDIA article for more details about how it all works.
So far the progress looks good:
In the image above you can clearly see the difference between the scaled and rotated textures before and after this work.
Another effect I worked on was simple but very useful - allowing you to set a fill color for a sprite. This would allow for sprites to have an overlay color that only affects the RGB channel, using the Alpha channel as a control for mixing the texture and tint with the fill color.
This would allow for effects the animation below by only modifying a single property on the Game Object:
There are some issues left to fix with regard to masking (the new alpha work has broken masking), so as soon as that's sorted I'll merge the work into master. It means you won't see the above in Beta 12, but keep an eye on the repo to see it land this week.
Matter.js Physics
I spent last week working hard on getting Matter.js integrated with V3. It's one of the final areas of the API and brings us a massive step closer to feature completion.
For those who have not come across Matter before, it's a rigid body physics system with a host of powerful features: Compound and Convex bodies, concave and convex hulls, physical properties (mass, area density), restitution, collision filters, stacking, resting and a whole load of other really nice things. It replaces the use of P2 Physics from Phaser 2 and is our new default full-body physics engine. There are several reasons for picking it over P2. The first, and most important, is that it's still actively developed. The main developer is available and responsive, which is great! It also has some superb features missing from P2, such as the ability to translate, scale or rotate a body without modifying its velocity at all. Perfect if you want to tween a physics body and still have it respond accurately. And finally, and it's a small one but still great: everything is done in pixels. There is no meters to pixels conversion needed anywhere, which makes your code simpler, the API code simpler and much easier to debug as well.
Integration was pretty smooth and I've done my best to make it as friendly as possible, following the same conventions as the rest of the V3 API. I still expose the whole of the Matter API to you for when you just want to get in there and play with it directly. There are also lots of helper methods and classes, which you'll see some of in a moment, but just know that they're optional and you can hit the metal directly if you wish and roll your own.
I'm going to cover the use of Matter in more detail next issue. For now feel free to play with the API (as it's all present in Beta 12), look at the stacks of examples in the labs and check out these demos. As usual, click the screenshots to run the examples in browser.
Mixed Bodies
Creating bodies in Matter is really simple. Using the Factory API you can call upon methods like Add.rectangle or Add.polygon and provide the required parameters. For a polygon you specify a radius in pixels and then the number of sides it should have. Ask for 3 sides and you'll get a triangle but it can increase from there. The more sides you add the more like a circle it becomes.
There are 5 built-in body types: Circle, Rectangle, Polygon, Trapezoid and one called FromVertices, which takes a series of points and if needed decomposes it into concave hulls and gives you a single body as the end result.
Rounded Bodies (Chamfering)
Bodies also have an optional chamfer property during creation. It allows you to set the number of points used for the edges of the body. In effect, you can create smooth edged bodies really quickly, such as in the example above. You can control the number of points used for the whole shape, or per corner.
Chains
The Matter Factory has built-in support for creating a chain between a group of bodies. It works by creating a constraint tween each body. You can control the properties of the constraint, such as the resting length and stiffness, allowing for some complex behaviors. The example above also shows the use of sprites with a bound body. When you start combining constraints you automatically open-up the ability to create springy bridges like this:
Attractors and World Wrap
Matter has a small but nice plugin ecosystem going and we've taken a couple of them and merged them into our default build. The Attractors plugin allows for the creation of continual forces, such as wind, gravity or magnetism. You can see it in action in the demo below:
The World Wrap plugin allows you to wrap a body around the bounds of a world should it stray off the edge. Think of the classic game Asteroids, and how the ship and rocks appeared on the other side of the screen? It basically allows you to do this, without accidentally teleporting your body right through something else. Both of these available by default and you can enable them with a single line in your game config or game code.
Simple API
As you'd expect from us by now, the API is dead simple to use. Just specify that you want to use Matter as your physics engine in the game config and then you can call the Factory functions directly. Have a look at the following code:
Literally, one line of code to create a full rigid physics body bound to an image. It will automatically size the body to match the image texture, assigning it the correct mass and density. You can pass in additional properties as well, such as giving it your own mass, or telling it to use a different body shape, or a static body, or any number of other options.
There are lots of helper methods on our Matter classes, such as setBodyShape, setVelocity, thrustLeft and thrustRight, setBounce and helpers to deal with collision groups and collision filtering. We wanted it to be as easy to use as possible. For it to be really quick to get something up and running, but flexible enough that you can really go to town creating physics games with it, or just fun demos like this:
I'm nearly done with integration of the API, there are a few elements left to test but it's 90% there already. I'll show some more demos next week, after which we will be moving on to the new Phaser 3 Scale Manager. It's the final system to build for V3. There are more features to complete, such as Pointer Lock support and Tilemap collision, but the Scale Manager is the final system to actually develop. With that in place it will give us the rest of the year to hammer through tests, docs and examples, ready for the New Year.
Phaser 3 Labs
Phaser 3 Beta 12 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!
Another week and another huge load of work completed. You can try all new features shown in this Dev Log in Phaser 3 Beta 12. Grab it from GitHub pre-built, or from npm using the beta tag.
Sound API Update
Pavle reports on progress to the Sound API: Although I said that adding support for looping and seeking is next on the list I decided to work on
making basic playback options more solid before moving on to more advanced things, so I added support for sound markers first.
A sound marker is part of sound represented by a unique name and a start time and duration. This allows you to bundle multiple sounds together into a single audio file and use markers to jump between them for playback.
Addition in v3 compared to v2 is that marker can contain a config property, the same as the one that you would pass to sound play or add methods, so that each marker can play at different playback rate, at different volume level etc.
I’ve also exposed two additional properties on sound objects: duration and totalDuration.
Duration holds the value of currently playing marker duration or duration of the entire sound if no marker is being played, while totalDuration represents the duration of the entire sound - obviously. :D
Without this, you wouldn’t be able to make a music player in Phaser, which I mentioned in the previous issue, as you need to know the duration of a sound in order to display its value and position correctly playback slider cursor.
I’ve recreated two examples from v2 to demonstrate how to use markers in v3, so if you feel a bit nostalgic go check them out and play around with different config values!
Tilemap API Update
Mike reports on the updates to the Tilemap API: "It was a short week here in the states because of Thanksgiving, but the Tilemap API still marches forward:"
The Tiled parser has been modularized and updated. It can read in layer offsets and properly apply them to objects within layers. It can also parse Tiled’s text objects, so you could potentially visually lay out a HUD in Tiled and generate it in Phaser.
Tiles can be set to collide, so everything is in place for physics integration. (A small technical note - recalculating interesting faces is magnitudes faster in a few important cases, so you probably won’t often need to think about preventing recalculations like in v2.)
The documentation effort is now well underway.
And last but not least, v3 now has the ability to get tiles that overlap with a geometry shape. You can see this in the screen shot below (it's not a demo yet, so don't try and click it).
Pre-Multiplied Alpha
Felipe writes: "The past week was mostly fixing already present issues on the WebGL rendering backend. Some really small that only affected specific parts and others that affect large chunks of the code.
The most important issue I fixed was getting the correct colors to appear when you scale and rotate textures by using pre-multiplied alpha. Read this NVIDIA article for more details about how it all works.
So far the progress looks good:
In the image above you can clearly see the difference between the scaled and rotated textures before and after this work.
Another effect I worked on was simple but very useful - allowing you to set a fill color for a sprite. This would allow for sprites to have an overlay color that only affects the RGB channel, using the Alpha channel as a control for mixing the texture and tint with the fill color.
This would allow for effects the animation below by only modifying a single property on the Game Object:
There are some issues left to fix with regard to masking (the new alpha work has broken masking), so as soon as that's sorted I'll merge the work into master. It means you won't see the above in Beta 12, but keep an eye on the repo to see it land this week.
Matter.js Physics
I spent last week working hard on getting Matter.js integrated with V3. It's one of the final areas of the API and brings us a massive step closer to feature completion.
For those who have not come across Matter before, it's a rigid body physics system with a host of powerful features: Compound and Convex bodies, concave and convex hulls, physical properties (mass, area density), restitution, collision filters, stacking, resting and a whole load of other really nice things. It replaces the use of P2 Physics from Phaser 2 and is our new default full-body physics engine. There are several reasons for picking it over P2. The first, and most important, is that it's still actively developed. The main developer is available and responsive, which is great! It also has some superb features missing from P2, such as the ability to translate, scale or rotate a body without modifying its velocity at all. Perfect if you want to tween a physics body and still have it respond accurately. And finally, and it's a small one but still great: everything is done in pixels. There is no meters to pixels conversion needed anywhere, which makes your code simpler, the API code simpler and much easier to debug as well.
Integration was pretty smooth and I've done my best to make it as friendly as possible, following the same conventions as the rest of the V3 API. I still expose the whole of the Matter API to you for when you just want to get in there and play with it directly. There are also lots of helper methods and classes, which you'll see some of in a moment, but just know that they're optional and you can hit the metal directly if you wish and roll your own.
I'm going to cover the use of Matter in more detail next issue. For now feel free to play with the API (as it's all present in Beta 12), look at the stacks of examples in the labs and check out these demos. As usual, click the screenshots to run the examples in browser.
Mixed Bodies
Creating bodies in Matter is really simple. Using the Factory API you can call upon methods like Add.rectangle or Add.polygon and provide the required parameters. For a polygon you specify a radius in pixels and then the number of sides it should have. Ask for 3 sides and you'll get a triangle but it can increase from there. The more sides you add the more like a circle it becomes.
There are 5 built-in body types: Circle, Rectangle, Polygon, Trapezoid and one called FromVertices, which takes a series of points and if needed decomposes it into concave hulls and gives you a single body as the end result.
Rounded Bodies (Chamfering)
Bodies also have an optional chamfer property during creation. It allows you to set the number of points used for the edges of the body. In effect, you can create smooth edged bodies really quickly, such as in the example above. You can control the number of points used for the whole shape, or per corner.
Chains
The Matter Factory has built-in support for creating a chain between a group of bodies. It works by creating a constraint tween each body. You can control the properties of the constraint, such as the resting length and stiffness, allowing for some complex behaviors. The example above also shows the use of sprites with a bound body. When you start combining constraints you automatically open-up the ability to create springy bridges like this:
Attractors and World Wrap
Matter has a small but nice plugin ecosystem going and we've taken a couple of them and merged them into our default build. The Attractors plugin allows for the creation of continual forces, such as wind, gravity or magnetism. You can see it in action in the demo below:
The World Wrap plugin allows you to wrap a body around the bounds of a world should it stray off the edge. Think of the classic game Asteroids, and how the ship and rocks appeared on the other side of the screen? It basically allows you to do this, without accidentally teleporting your body right through something else. Both of these available by default and you can enable them with a single line in your game config or game code.
Simple API
As you'd expect from us by now, the API is dead simple to use. Just specify that you want to use Matter as your physics engine in the game config and then you can call the Factory functions directly. Have a look at the following code:
Literally, one line of code to create a full rigid physics body bound to an image. It will automatically size the body to match the image texture, assigning it the correct mass and density. You can pass in additional properties as well, such as giving it your own mass, or telling it to use a different body shape, or a static body, or any number of other options.
There are lots of helper methods on our Matter classes, such as setBodyShape, setVelocity, thrustLeft and thrustRight, setBounce and helpers to deal with collision groups and collision filtering. We wanted it to be as easy to use as possible. For it to be really quick to get something up and running, but flexible enough that you can really go to town creating physics games with it, or just fun demos like this:
I'm nearly done with integration of the API, there are a few elements left to test but it's 90% there already. I'll show some more demos next week, after which we will be moving on to the new Phaser 3 Scale Manager. It's the final system to build for V3. There are more features to complete, such as Pointer Lock support and Tilemap collision, but the Scale Manager is the final system to actually develop. With that in place it will give us the rest of the year to hammer through tests, docs and examples, ready for the New Year.
Phaser 3 Labs
Phaser 3 Beta 12 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!