Phaser 3.13 Released, Camera Shaders and all about the Phaser Doc Jam.
Welcome to a new Dev Log. The first announcement is, of course, the release of Phaser 3.13. This was the culmination of several weeks worth of updates, as well as the introduction of some features that have been in development for a month or so.
The headline features are the new Facebook Instant Games Plugin (more on that in Dev Log 130), the introduction of the new Shape Game Objects, as featured in depth in Dev Log 128, some significant updates to Pointer Events with the way the events flow, and the introduction of support for Camera specific shaders.
Read all about what's new in Phaser 3.13. Of course, there is the comprehensive Change Log as usual. Thank you to everyone who helped out with this release, either by opening issues, contributing to the code via pull requests or helping complete the documentation.
Development of 3.14 has begun already. What? You didn't think I actually get a break, did you? :) There are a couple of high priority issues I need to focus on first, including a degenerative bug in Graphics objects rendered to textures and an issue with certain static tilemap layers having tiles skipped during rendering. Depending on how complex they are to solve I may release a 3.13.1 update to address just those two.
I have some clear goals in mind as to what 3.14 will contain, which I outlined in the previous Dev Log. However, I also want to spend some time knocking the GitHub issues list in to shape and working on more of the documentation. And it's the documentation I'm going to discuss this Dev Log. I've been thinking that if I was to hold a 'Documentation Jam' and provide some easy way for you all to contribute that perhaps we could blast through it in no-time at all together? So, that is what's going to happen!
Phaser 3 Doc Jam
Right now there are 3,452 items left to document in Phaser 3. You can see these when looking at the docs and seeing the text [description] instead of something useful. It's a placeholder tag, meaning the description is yet to be written and was put in there so I could easily search for them in the future and fill them in.
When 3.0 was released there were over 15,000 descriptions left to write. Since, then I've steadily been chipping away (and some of the community too, thank you) so now we're at a fraction of that total. Equally, every new feature I have added to Phaser 3 has been fully documented from the start. Literally hundreds of new properties and methods getting documented. As I worked on large areas, such as the Camera system, I documented them too.
Even so, there are still those frustrating 3,452 left to go. Ironically, there is 3 times that number of you reading this newsletter. Add in those who visit the Dev Logs on the site and there are tens of thousands of us in total. So between us, we definitely have the numbers to be able to utterly smash the docs in a very short space of time. The problem is facilitating this. As it stands, in order to contribute to the docs right now you'd have to fork the main phaser repo, clone it down locally, search the code for a \[description\] tag, figure out what it does, fill it in and then submit a pull request. If this is a process you're used to doing all the time then it doesn't seem that complex. Yet for a lot of you, that's a huge amount of effort required. The barrier to entry is simply too high.
So I built a web-based interface to remove this barrier and hopefully make it more approachable. Welcome to the Phaser Doc Jam.
All you need to do to take part is point your browser to docjam.phaser.io. When the page loads it will randomly pick one of the descriptions that needs writing.
The source code is displayed and the description line highlighted. Take a look at it. Can you figure out what should be written? Maybe it's a property that needs describing? Or perhaps a return value from a method? Look at the surrounding code and see if you can infer the meaning of what's going on. There's a link to open the file on GitHub if you'd like a better look at it.
If you feel comfortable writing a description then go ahead and put it into the text area below the code. The more detailed, the better. Also, please take advantage of the spell-checker built into your browser :) If you need to include a property in the description then wrap it in backticks. This will ensure it is properly formatted when the docs are generated.
You can also use basic Markdown if you need. Be careful here, as most the time it isn't needed. But there are certainly cases when it is, such as linking to support material, or showing embedded code.
Once you're happy with what you've written, enter your name. This is the name that will appear in the Phaser Change Log, where we thank and credit contributors. So feel free to use either your real name, or a GitHub or Twitter handle.
Finally, you can enter your email address. You don't have to, it's entirely optional, but in order to incentivise you to take part, I'm turning this into a prize draw :)
Write Docs. Win Prizes!
Everyone who contributes a description, which I then approve, will be automatically entered into a prize draw. You get one entry into the draw for every description that is approved.
At the end of November, I will pick 6 winners. The first two will win a $100 Amazon gift voucher each. The remaining 4 will each win a $50 gift voucher. The vouchers will be sent digitally, in time for you to spend on Christmas presents :)
If by some magic we manage to complete all of the docs before the end of November then I'll run the draw early. After the draw is complete the database holding your email address will be erased. It won't be used for anything other than contacting you if your entry is selected. The winners will be announced in this newsletter.
As mentioned, this is entirely optional. If you'd like to just help for the sake of helping, then you don't need to give your email address at all. However, I feel it should make what is quite an ardous task at least a little more fun.
What makes a good description?
A good description is clear, concise and informative. If it relates to another part of the class, for example, a property that has an associated 'set' method, then it's always helpful to mention this, such as below:
Depending on what the description is, depends on how much detail is required. In the above example, the lerp property is quite a significant one in the Camera class, so it has been given a lot of detail. However, here is the description of a private internal value:
As you can see, it's much more concise. Unlike lots of frameworks Phaser documents all properties and methods, both public and private.
The vast majority of the missing descriptions are for method parameters. These generally don't require as much information. For example, look at the example below for the Camera.fadeIn method:
In most cases, the description simply reinforces what you can generally infer from the parameter name itself. It's always helpful to state the range of a value if it's important. Such as maximum values for color channels, or the unit of a parameter, like mentioning that the duration is in milliseconds.
The biggest and most time-consuming things to document are classes themselves. They generally require a lot more work to be meaningful and useful. I have factored this in to the prize draw. So, if you spend time writing a really detailed and useful class description, then I can choose to make it worth multiple entries in the draw at my discretion.
If you've any questions about writing the docs or how to use the web site then please let me know. You can either reply to this email or ping me on Slack or Discord.
Right now, I'm going to venture back to 3.14 development and will be using the doc jam website myself to pop new descriptions into Phaser now and again. I really hope to see your contributions in the approval list :) I know not everyone is able to participate but this has to be worth trying at least!
Welcome to a new Dev Log. The first announcement is, of course, the release of Phaser 3.13. This was the culmination of several weeks worth of updates, as well as the introduction of some features that have been in development for a month or so.
The headline features are the new Facebook Instant Games Plugin (more on that in Dev Log 130), the introduction of the new Shape Game Objects, as featured in depth in Dev Log 128, some significant updates to Pointer Events with the way the events flow, and the introduction of support for Camera specific shaders.
Read all about what's new in Phaser 3.13. Of course, there is the comprehensive Change Log as usual. Thank you to everyone who helped out with this release, either by opening issues, contributing to the code via pull requests or helping complete the documentation.
Development of 3.14 has begun already. What? You didn't think I actually get a break, did you? :) There are a couple of high priority issues I need to focus on first, including a degenerative bug in Graphics objects rendered to textures and an issue with certain static tilemap layers having tiles skipped during rendering. Depending on how complex they are to solve I may release a 3.13.1 update to address just those two.
I have some clear goals in mind as to what 3.14 will contain, which I outlined in the previous Dev Log. However, I also want to spend some time knocking the GitHub issues list in to shape and working on more of the documentation. And it's the documentation I'm going to discuss this Dev Log. I've been thinking that if I was to hold a 'Documentation Jam' and provide some easy way for you all to contribute that perhaps we could blast through it in no-time at all together? So, that is what's going to happen!
Phaser 3 Doc Jam
Right now there are 3,452 items left to document in Phaser 3. You can see these when looking at the docs and seeing the text [description] instead of something useful. It's a placeholder tag, meaning the description is yet to be written and was put in there so I could easily search for them in the future and fill them in.
When 3.0 was released there were over 15,000 descriptions left to write. Since, then I've steadily been chipping away (and some of the community too, thank you) so now we're at a fraction of that total. Equally, every new feature I have added to Phaser 3 has been fully documented from the start. Literally hundreds of new properties and methods getting documented. As I worked on large areas, such as the Camera system, I documented them too.
Even so, there are still those frustrating 3,452 left to go. Ironically, there is 3 times that number of you reading this newsletter. Add in those who visit the Dev Logs on the site and there are tens of thousands of us in total. So between us, we definitely have the numbers to be able to utterly smash the docs in a very short space of time. The problem is facilitating this. As it stands, in order to contribute to the docs right now you'd have to fork the main phaser repo, clone it down locally, search the code for a \[description\] tag, figure out what it does, fill it in and then submit a pull request. If this is a process you're used to doing all the time then it doesn't seem that complex. Yet for a lot of you, that's a huge amount of effort required. The barrier to entry is simply too high.
So I built a web-based interface to remove this barrier and hopefully make it more approachable. Welcome to the Phaser Doc Jam.
All you need to do to take part is point your browser to docjam.phaser.io. When the page loads it will randomly pick one of the descriptions that needs writing.
The source code is displayed and the description line highlighted. Take a look at it. Can you figure out what should be written? Maybe it's a property that needs describing? Or perhaps a return value from a method? Look at the surrounding code and see if you can infer the meaning of what's going on. There's a link to open the file on GitHub if you'd like a better look at it.
If you feel comfortable writing a description then go ahead and put it into the text area below the code. The more detailed, the better. Also, please take advantage of the spell-checker built into your browser :) If you need to include a property in the description then wrap it in backticks. This will ensure it is properly formatted when the docs are generated.
You can also use basic Markdown if you need. Be careful here, as most the time it isn't needed. But there are certainly cases when it is, such as linking to support material, or showing embedded code.
Once you're happy with what you've written, enter your name. This is the name that will appear in the Phaser Change Log, where we thank and credit contributors. So feel free to use either your real name, or a GitHub or Twitter handle.
Finally, you can enter your email address. You don't have to, it's entirely optional, but in order to incentivise you to take part, I'm turning this into a prize draw :)
Write Docs. Win Prizes!
Everyone who contributes a description, which I then approve, will be automatically entered into a prize draw. You get one entry into the draw for every description that is approved.
At the end of November, I will pick 6 winners. The first two will win a $100 Amazon gift voucher each. The remaining 4 will each win a $50 gift voucher. The vouchers will be sent digitally, in time for you to spend on Christmas presents :)
If by some magic we manage to complete all of the docs before the end of November then I'll run the draw early. After the draw is complete the database holding your email address will be erased. It won't be used for anything other than contacting you if your entry is selected. The winners will be announced in this newsletter.
As mentioned, this is entirely optional. If you'd like to just help for the sake of helping, then you don't need to give your email address at all. However, I feel it should make what is quite an ardous task at least a little more fun.
What makes a good description?
A good description is clear, concise and informative. If it relates to another part of the class, for example, a property that has an associated 'set' method, then it's always helpful to mention this, such as below:
Depending on what the description is, depends on how much detail is required. In the above example, the lerp property is quite a significant one in the Camera class, so it has been given a lot of detail. However, here is the description of a private internal value:
As you can see, it's much more concise. Unlike lots of frameworks Phaser documents all properties and methods, both public and private.
The vast majority of the missing descriptions are for method parameters. These generally don't require as much information. For example, look at the example below for the Camera.fadeIn method:
In most cases, the description simply reinforces what you can generally infer from the parameter name itself. It's always helpful to state the range of a value if it's important. Such as maximum values for color channels, or the unit of a parameter, like mentioning that the duration is in milliseconds.
The biggest and most time-consuming things to document are classes themselves. They generally require a lot more work to be meaningful and useful. I have factored this in to the prize draw. So, if you spend time writing a really detailed and useful class description, then I can choose to make it worth multiple entries in the draw at my discretion.
If you've any questions about writing the docs or how to use the web site then please let me know. You can either reply to this email or ping me on Slack or Discord.
Right now, I'm going to venture back to 3.14 development and will be using the doc jam website myself to pop new descriptions into Phaser now and again. I really hope to see your contributions in the approval list :) I know not everyone is able to participate but this has to be worth trying at least!