Work on Phaser 3.16.3 and the new docs site continues .
Welcome to Dev Log 142. I spent the majority of the week carrying on my work with the new docs. I'm aware they are taking a while, but it's a pretty huge and important project. However, to avoid Phaser getting stale I have split my week up to do both docs and work on the next release. Let's dive in ...
3.16.3 Development
At the moment, 3.16.3 is focusing specifically on addressing issues from GitHub, along with a handful of important features. The biggest new addition came about as a result of a side-effect from the Input Manager changes in 3.16. In order to provide the ability for Phaser to tell if you mouse up outside of the canvas, it has to listen to DOM events from outside of the canvas too. So in 3.16 it now binds itself to the window object. This works in lots of cases, but when you've got another layer in the mix, like Vue, that also intercepts DOM events, things can get a bit messy.
To address this I've made a couple of changes in 3.16.3. First, the window listeners can be disabled entirely. Use the new game config property 'input.windowEvents' and set it to false. Then the listeners won't ever be created. This is a trade-off, as it means that events like 'POINTER_UP_OUTSIDE' can never be dispatched, either. Yet depending on your needs that might be just fine. At least you now get the choice.
Related to this, I've also changed how the Mouse and Touch managers handle window level events (if you've left them enabled). Before, they would use the same handler as the canvas events. In hindsight, this was wrong, as they need slightly different event paths and shouldn't ever fire if the event target is the actual canvas. This was causing input events to fire twice, once for the window and once for the canvas, as it flowed through the DOM. It didn't manifest in Phaser Game Objects because they were handled internally, but it was still redundant and no longer occurs.
More Tweaks
I've removed all references to Cocoon from the API, as now they have closed down it isn't worth keeping. There are (yet more) fixes for users exiting Fullscreen mode, too. There is a handy new event to tell when a Scene finishes being created, some tweaks to allow animation frames to be specified in reverse and lots of fixes and improvements to the docs.
Ideally, I'll get 3.16.3 out before the end of the month, but it depends entirely on how testing goes, so it may need to slip into early March. Either way, it won't be long before it's out and then I can focus on 3.17. If you'd like to help test you can find the latest version in GitHub master branch, like usual.
Translation Help Needed
Last week I wrote that I would love to have the Phaser getting started guides translated into languages other than English. Thank you to those who have stepped forwards! So far, we've got translations into Bulgarian, Czech, Greek, Spanish, German, Turkish, French and Chinese. This is an amazing start!
Are you able to help translate the guides into a language not already covered? If so, please email me (rdavey@gmail.com) and I'll send you the details. The guides are plain markdown files and quite short, so hopefully won't take too much of your time.
You will be credited as the translator which can include a link to whatever site you like (your own site, a game you've released, etc). These guides have a lot of monthly readers so it'll be brilliant to offer them in languages other than English.
Phaser 3 Docs Work
Last Dev Log I talked about the work I was doing on the Phaser docs. I alluded to how it's entirely unglamorous, but essential, which seemed to resonate with a number of you. If you didn't read it, please do so here before continuing.
I carried on refining the JSON to SQL process and I'm now happy that it has every feature I currently need, so the majority of the work was spent on the actual docs interface. I've been a big fan of Bootstrap for years, so it made sense to utilize it for the docs. I spent a lot of time working on the layout, refining it, improving and tweaking all over the place. Here's a screen shot of a class method in the new layout (click the shot for a larger version):
Because I have 100% control over the template I can decide which parts of the docs are most important. I can give priority to certain elements, such as method signatures, while making features such as the link to the source code line number less visually important, while still keeping them. Each method has its own unique URL, too, which means I'll be able to deep-link direct to a method and have just that appear on the page, without any extra content around it that may otherwise be confusing, which is will be especially helpful for beginners guides.
I've also built in an option for you to toggle inherited methods and properties on and off. Most Game Objects, for example, inherit a whole bunch of properties from the components, and you can now hide them all to see exactly just what that Game Object does on its own.
Methods and Properties can also be hidden at will and easily searched, data types are links to details about that type, source code is properly formatted and colored and everything just has better spacing and alignment than before.
Another feature that's only possible because of the move to SQL is the ability to compare docs between versions. Every property and method in the API has, since the very first 3.0.0 version, been marked to say when it was added. This means it's possible to show the evolution of a class, or part of one, by comparing version numbers. Automatic lists of things that were deprecated or added is now possible without needing to consult the Change Log. It's the sort of feature that is only useful to a select number of devs, but I'm one of those, so you all get to benefit from it :)
One thing that I'm keen to do, once the new docs are live, is to go through and link docs to source code examples. JSDoc actually has a tag for this built-in, so we can make use of it to provide direct links from methods to code showing how to use them. There is also the ability to link methods to tutorials and long-form content, the sort of content too large to have in JSDoc blocks directly, but can be held elsewhere. Obviously, there are lots of methods across the whole API, so it will take ages to do them all, but I feel it's the sort of endevor that can be chipped away at, bit by bit, over the rest of the year and beyond.
For now, I'm heading off back into the depths of CSS and coming up for breath by tackling more GitHub issues. If you'd like to help, please test the master branch or submit PRs (especially ones that help complete docs). Until next issue, keep coding actual games, you lucky people!
Welcome to Dev Log 142. I spent the majority of the week carrying on my work with the new docs. I'm aware they are taking a while, but it's a pretty huge and important project. However, to avoid Phaser getting stale I have split my week up to do both docs and work on the next release. Let's dive in ...
3.16.3 Development
At the moment, 3.16.3 is focusing specifically on addressing issues from GitHub, along with a handful of important features. The biggest new addition came about as a result of a side-effect from the Input Manager changes in 3.16. In order to provide the ability for Phaser to tell if you mouse up outside of the canvas, it has to listen to DOM events from outside of the canvas too. So in 3.16 it now binds itself to the window object. This works in lots of cases, but when you've got another layer in the mix, like Vue, that also intercepts DOM events, things can get a bit messy.
To address this I've made a couple of changes in 3.16.3. First, the window listeners can be disabled entirely. Use the new game config property 'input.windowEvents' and set it to false. Then the listeners won't ever be created. This is a trade-off, as it means that events like 'POINTER_UP_OUTSIDE' can never be dispatched, either. Yet depending on your needs that might be just fine. At least you now get the choice.
Related to this, I've also changed how the Mouse and Touch managers handle window level events (if you've left them enabled). Before, they would use the same handler as the canvas events. In hindsight, this was wrong, as they need slightly different event paths and shouldn't ever fire if the event target is the actual canvas. This was causing input events to fire twice, once for the window and once for the canvas, as it flowed through the DOM. It didn't manifest in Phaser Game Objects because they were handled internally, but it was still redundant and no longer occurs.
More Tweaks
I've removed all references to Cocoon from the API, as now they have closed down it isn't worth keeping. There are (yet more) fixes for users exiting Fullscreen mode, too. There is a handy new event to tell when a Scene finishes being created, some tweaks to allow animation frames to be specified in reverse and lots of fixes and improvements to the docs.
Ideally, I'll get 3.16.3 out before the end of the month, but it depends entirely on how testing goes, so it may need to slip into early March. Either way, it won't be long before it's out and then I can focus on 3.17. If you'd like to help test you can find the latest version in GitHub master branch, like usual.
Translation Help Needed
Last week I wrote that I would love to have the Phaser getting started guides translated into languages other than English. Thank you to those who have stepped forwards! So far, we've got translations into Bulgarian, Czech, Greek, Spanish, German, Turkish, French and Chinese. This is an amazing start!
Are you able to help translate the guides into a language not already covered? If so, please email me (rdavey@gmail.com) and I'll send you the details. The guides are plain markdown files and quite short, so hopefully won't take too much of your time.
You will be credited as the translator which can include a link to whatever site you like (your own site, a game you've released, etc). These guides have a lot of monthly readers so it'll be brilliant to offer them in languages other than English.
Phaser 3 Docs Work
Last Dev Log I talked about the work I was doing on the Phaser docs. I alluded to how it's entirely unglamorous, but essential, which seemed to resonate with a number of you. If you didn't read it, please do so here before continuing.
I carried on refining the JSON to SQL process and I'm now happy that it has every feature I currently need, so the majority of the work was spent on the actual docs interface. I've been a big fan of Bootstrap for years, so it made sense to utilize it for the docs. I spent a lot of time working on the layout, refining it, improving and tweaking all over the place. Here's a screen shot of a class method in the new layout (click the shot for a larger version):
Because I have 100% control over the template I can decide which parts of the docs are most important. I can give priority to certain elements, such as method signatures, while making features such as the link to the source code line number less visually important, while still keeping them. Each method has its own unique URL, too, which means I'll be able to deep-link direct to a method and have just that appear on the page, without any extra content around it that may otherwise be confusing, which is will be especially helpful for beginners guides.
I've also built in an option for you to toggle inherited methods and properties on and off. Most Game Objects, for example, inherit a whole bunch of properties from the components, and you can now hide them all to see exactly just what that Game Object does on its own.
Methods and Properties can also be hidden at will and easily searched, data types are links to details about that type, source code is properly formatted and colored and everything just has better spacing and alignment than before.
Another feature that's only possible because of the move to SQL is the ability to compare docs between versions. Every property and method in the API has, since the very first 3.0.0 version, been marked to say when it was added. This means it's possible to show the evolution of a class, or part of one, by comparing version numbers. Automatic lists of things that were deprecated or added is now possible without needing to consult the Change Log. It's the sort of feature that is only useful to a select number of devs, but I'm one of those, so you all get to benefit from it :)
One thing that I'm keen to do, once the new docs are live, is to go through and link docs to source code examples. JSDoc actually has a tag for this built-in, so we can make use of it to provide direct links from methods to code showing how to use them. There is also the ability to link methods to tutorials and long-form content, the sort of content too large to have in JSDoc blocks directly, but can be held elsewhere. Obviously, there are lots of methods across the whole API, so it will take ages to do them all, but I feel it's the sort of endevor that can be chipped away at, bit by bit, over the rest of the year and beyond.
For now, I'm heading off back into the depths of CSS and coming up for breath by tackling more GitHub issues. If you'd like to help, please test the master branch or submit PRs (especially ones that help complete docs). Until next issue, keep coding actual games, you lucky people!