JSDocs update and Phaser 3 Particle Emitter.
First of all, Phaser 3 Beta 7 is out. This includes a bunch of PRs from various contributors (thank you!) - one of which should get Phaser 3 running on older browsers that don't support the URL API. It also fixes a bug introduced in the Origin component which broke Text rendering and other things in Beta 6. You can download pre-built files from GitHub or get it from npm.
There's a Doctor in the House
In issue 100 I talked about how I had been building tools to help with the documentation process. And last week I put those tools to the test in earnest. I literally spent days adding JSDoc blocks into the Phaser 3 source. It's still taking ages, not least because there is simply so much to document. By way of example: there are 1,111 source files that need documenting across the whole API. By the end of Friday, I had managed to complete the docblocks for 508 of them, which is 46% complete.
Out of curiosity, I installed a sloc package into the repo and as of now, we've 46,161 lines of source in Phaser 3 and 15,046 lines of comments.
Truth be told, it's quite a painful process, even with my new tools. They absolutely speed things up but it's the mental overhead of having to process every file, check all of the data-types, ensure the return types match and the namespaces are correct, and then repeat through hundreds upon hundreds of files. It's mentally exhausting. On Friday I put the entire Armin van Buuren 5.5 hour Untold Festival set on and listened to the whole thing while working on the docs. Trance is easily one of my go-to genres of music when it comes to repetitive tasks :) Armin is doing a special 836 minute long set this week as part of his podcast, so I may be needing that to get more docs done!
I've also been tidying up the global API structure as I go. Some areas have been consolidated into others to try and bring the size of the top-level hierarchy down to just the core. I've also removed some modules that aren't needed for launch and generally have been tidying up a lot as I go.
This week I will carry on with the documentation. I'd love to get the API to at least 75% complete by the next issue. I'm going to have to take a little break out to work on something more creative as I go, because I'm worried I can't mentally sustain 5 solid days of intense doc work, but just know that progress is great and we will get there soon!
It's Party Time
A few issues ago I mentioned that we had added a new Particle Emitter into Phaser 3. I wanted to show it off then, but I knew that during the time I was working on the docs there would be nothing fun to show you. As important as jsdoc blocks are, they're hardly visually stimulating. So, this issue I'm going to share some of the work we've done with particles. First, a demo:
Have a good play with the interface to get a feel for what the new particle system can do.
In Phaser 2 particles were essentially just Arcade Physics bodies spawned in a Group, with some extra properties to handle lifespan, scale and so on. This was good in that it meant you could collide with particles, or collide particles with things like Tilemaps. But otherwise, was pretty bad in every other sense. In most games the particles are visual effects, things that reinforce the story or urgency of a situation - such as a stack of coins flying into the air from a loot drop, or an alien ship exploding into a hundred pieces. They're not usually actual gameplay elements that you interact with, but rather are the byproduct of having done such an action.
For Phaser 3 it was important we moved the particles back to being visual effects first and foremost, with the ability to become more if you required it, not the other way around. Felipe worked on a brand new rendering system for them and implemented WebGL and Canvas renderers using a new customised batch. In short, they're fast. Very fast. And are optimized to offer speed first, allowing you to blast them all over your game without having to worry too much. Here's a fun little particle trail that follows the mouse position:
Emitter Properties
If you've played with the demo above you'll see that particles have various inbuilt properties such as the angle of emission, gravity, velocity, scale, alpha, rotation and the ability to define eases for the most common of these. In order to keep them fast, a single emitter is locked to a single texture, that is, it cannot switch texture part-way through rendering a batch. However, it can emit any frame of a texture, meaning if you bundle all your particles together in a single atlas it can batch the lot. Here's an example of several emitters running in parallel:
The use of a blend mode really adds to this example. You're not just limited to emitting particles from a point though. We also added the ability to emit from anywhere in a given shape. In the following example move the mouse around and click to change the shape:
Combining shapes with emitters is always great fun. Here is what happens if you rotate a Line shape while using it as the source of an emitter:
Emitters and Paths
Being able to emit from a shape is great - but you can also emit from a Path too. There are several options here. For example, you could release a follower along a Path (see Dev Log 99 for more) and then attach an emitter to it. Or, you could get the points on a path and then emit a particle from each one. This opens up all kinds of possibilities for visual effects. Have a play with this spline curve that has an emitter bound to it. Drag the nodes around and see it update in real-time:
As of Beta 7 the new Particle Emitter is implemented and working. You can find a load of examples to play with. However, I'll warn you now, the API is going to be changing in the coming weeks. Not dramatically, but at the moment things like the particle physics step is calculated in the emitter rather than the particle, which will make it very hard for you to extend and adapt. So I'm going to be shifting things around and delegating tasks out more to the Particle itself, and leaving the emitter as being in charge of the rendering and parenting. Fundamentally, what you see today will remain, it's just internally things with need tidying up.
Please have a play though. I'd love to see someone try to work particles into a little game and report back to me if you find anything that needs tweaking.
Phaser 3 Labs
Phaser 3 Beta 7 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!
First of all, Phaser 3 Beta 7 is out. This includes a bunch of PRs from various contributors (thank you!) - one of which should get Phaser 3 running on older browsers that don't support the URL API. It also fixes a bug introduced in the Origin component which broke Text rendering and other things in Beta 6. You can download pre-built files from GitHub or get it from npm.
There's a Doctor in the House
In issue 100 I talked about how I had been building tools to help with the documentation process. And last week I put those tools to the test in earnest. I literally spent days adding JSDoc blocks into the Phaser 3 source. It's still taking ages, not least because there is simply so much to document. By way of example: there are 1,111 source files that need documenting across the whole API. By the end of Friday, I had managed to complete the docblocks for 508 of them, which is 46% complete.
Out of curiosity, I installed a sloc package into the repo and as of now, we've 46,161 lines of source in Phaser 3 and 15,046 lines of comments.
Truth be told, it's quite a painful process, even with my new tools. They absolutely speed things up but it's the mental overhead of having to process every file, check all of the data-types, ensure the return types match and the namespaces are correct, and then repeat through hundreds upon hundreds of files. It's mentally exhausting. On Friday I put the entire Armin van Buuren 5.5 hour Untold Festival set on and listened to the whole thing while working on the docs. Trance is easily one of my go-to genres of music when it comes to repetitive tasks :) Armin is doing a special 836 minute long set this week as part of his podcast, so I may be needing that to get more docs done!
I've also been tidying up the global API structure as I go. Some areas have been consolidated into others to try and bring the size of the top-level hierarchy down to just the core. I've also removed some modules that aren't needed for launch and generally have been tidying up a lot as I go.
This week I will carry on with the documentation. I'd love to get the API to at least 75% complete by the next issue. I'm going to have to take a little break out to work on something more creative as I go, because I'm worried I can't mentally sustain 5 solid days of intense doc work, but just know that progress is great and we will get there soon!
It's Party Time
A few issues ago I mentioned that we had added a new Particle Emitter into Phaser 3. I wanted to show it off then, but I knew that during the time I was working on the docs there would be nothing fun to show you. As important as jsdoc blocks are, they're hardly visually stimulating. So, this issue I'm going to share some of the work we've done with particles. First, a demo:
Have a good play with the interface to get a feel for what the new particle system can do.
In Phaser 2 particles were essentially just Arcade Physics bodies spawned in a Group, with some extra properties to handle lifespan, scale and so on. This was good in that it meant you could collide with particles, or collide particles with things like Tilemaps. But otherwise, was pretty bad in every other sense. In most games the particles are visual effects, things that reinforce the story or urgency of a situation - such as a stack of coins flying into the air from a loot drop, or an alien ship exploding into a hundred pieces. They're not usually actual gameplay elements that you interact with, but rather are the byproduct of having done such an action.
For Phaser 3 it was important we moved the particles back to being visual effects first and foremost, with the ability to become more if you required it, not the other way around. Felipe worked on a brand new rendering system for them and implemented WebGL and Canvas renderers using a new customised batch. In short, they're fast. Very fast. And are optimized to offer speed first, allowing you to blast them all over your game without having to worry too much. Here's a fun little particle trail that follows the mouse position:
Emitter Properties
If you've played with the demo above you'll see that particles have various inbuilt properties such as the angle of emission, gravity, velocity, scale, alpha, rotation and the ability to define eases for the most common of these. In order to keep them fast, a single emitter is locked to a single texture, that is, it cannot switch texture part-way through rendering a batch. However, it can emit any frame of a texture, meaning if you bundle all your particles together in a single atlas it can batch the lot. Here's an example of several emitters running in parallel:
The use of a blend mode really adds to this example. You're not just limited to emitting particles from a point though. We also added the ability to emit from anywhere in a given shape. In the following example move the mouse around and click to change the shape:
Combining shapes with emitters is always great fun. Here is what happens if you rotate a Line shape while using it as the source of an emitter:
Emitters and Paths
Being able to emit from a shape is great - but you can also emit from a Path too. There are several options here. For example, you could release a follower along a Path (see Dev Log 99 for more) and then attach an emitter to it. Or, you could get the points on a path and then emit a particle from each one. This opens up all kinds of possibilities for visual effects. Have a play with this spline curve that has an emitter bound to it. Drag the nodes around and see it update in real-time:
As of Beta 7 the new Particle Emitter is implemented and working. You can find a load of examples to play with. However, I'll warn you now, the API is going to be changing in the coming weeks. Not dramatically, but at the moment things like the particle physics step is calculated in the emitter rather than the particle, which will make it very hard for you to extend and adapt. So I'm going to be shifting things around and delegating tasks out more to the Particle itself, and leaving the emitter as being in charge of the rendering and parenting. Fundamentally, what you see today will remain, it's just internally things with need tidying up.
Please have a play though. I'd love to see someone try to work particles into a little game and report back to me if you find anything that needs tweaking.
Phaser 3 Labs
Phaser 3 Beta 7 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!