v3 Input Manager Updates.
We're currently working on sprints of around 1 week for all of the Phaser 3 work. This fits in well with the newsletter as when a bunch of new features land I can write about them in the following issue. However, it's not always possible to fit the work into nice 5 day chunks and sometimes it just takes longer or needs more time to complete. The Input Manager is one such area.
Since the last issue, it has gone through some significant internal revisions. The API has changed dramatically even compared to that from a week ago and is still changing even now.
It was inevitable that at some point we would have a Dev Log that was going to talk about the process rather than show off any demos and I'm afraid that is what will happen this issue.
Input Scaling
On a positive note, the Input Manager is now handling canvas resizing, position and scaling properly. In the previous demos if you were to scroll the page with the canvas on it would mess up all of the input coordinates. Or if you scaled the canvas. These are now factored in. This means v3 demos using input can be placed anywhere within the web page and work. This wasn't something I was going to handle until starting the new Scale Manager but it felt too important to leave to them, so I bought that task forward. It will also be a good feature to have in place with the Alpha release.
Input Updates
Internally the Input Manager has gone through a lot of changes over the past week. While the previous iteration worked it wasn't set-up to handle multi-pointer input. For example, if you were to touch down on a sprite with one finger, then touch it with another finger and then release the first finger, the sprite would have thought it had entered an 'up' state (because a previously active pointer had left it). This is fine for desktops with mice, less so for touch screens. Although the number of mobile games that use multiple inputs on a single sprite is really low it was time to address this lingering v2 issue and put it to bed for once and all.
So I had to modify both the data structures for the interactive objects and also the input manager itself to cope with this. It does mean you could do some cool things now though: for example, you could have a sprite that looks like a Christmas cracker and pull it apart by dragging from each end of it with two fingers. This is something not possible in v2 without using two different sprites.
Move Events
Also new in v3 are move events. These events are dispatched whenever a pointer is in the processing of moving across an interactive object. It doesn't have to be pressed down or dragging, it just has to be moving. As part of the event you are sent the local coordinates of the pointer within the sprite. So you could use it for a 'sliding' UI element that you control by just sliding a finger up and down it, such as a volume meter.
Callbacks and Events
In v2 nearly all input was handled via Signals. You'd listen to a signal bound to a specific sprite to know if the pointer was pressed down on it.
In v3 you can use both callbacks and events. The events belong to the Input Manager itself, not the game objects. So, you could listen for a Pointer Down event from the Input Manager. As part of the event properties you are given a list of all the Game Objects that the pointer went down on, as well as the top-most one in the display list.
The callbacks, however, belong to the Game Objects. You can set a callback for every type of input event: over, down, up, out, move and the drag events: start, drag and end. Callbacks are invoked on a per-Game Object basis and are sent a bunch of useful arguments as well. Depending on the type of game you're building you may favour one approach over the other, or maybe just out of personal preference too. By having both options available though it gives you the flexibility to decide, rather than enforcing it upon you.
Top Most Game Objects
Part of the reason for the refactor last week was to implement a new feature across all of the input events. The feature was the ability for the Input Manager to process either just the top-most Game Object in the display list or all of them.
For example, if you had 3 overlapping Sprites and each of them is set to be interactive, then you can now set a toggle in the Input Manager as to how it should deal with them. The default setting is that if you were to click on the top-most sprite then it, and only it, would have its callbacks fired and appear in the event. The other two, being lower than it, would be skipped.
This is how browsers work and how the DOM works. If you have 2 DIVs above each other then only the top-most one gets any input events. So it's how Phaser 3 is going to work by default too. However, it's often very useful to be able to get every Game Object the pointer just pressed down on, or moved over, or dragged, so now you have the ability to do that as well.
Onwards to the Alpha
I spent this morning updating the v3 progress chart, marking off the things we've done and moving other tasks around. I still need to spend several days on the Input Manager and then will look at preparing the Alpha release of v3. part of the release process will be authoring a Getting Started guide, so you can pick it up and have a play without using the API docs (because they don't exist yet!). We're still on schedule to release the Alpha on Monday 31st July, which is the same day as the next newsletter.
I need to start looking at how to handle the API docs very soon. I want to use JSDoc again because it's so common and IDEs support it so well, but without using the same template as v2 has. So it's going to take a while to do some R&D to work out the best approach here. If you've any recommendations for decent documentation tool chains then please let me know!
Tinted Bitmap Text
I couldn't go a whole Dev Log without at least one new example :) The other week Felipe added in the ability to set the vertex colors in the Bitmap Text renderer. I finished that off by implementing the Tint component and hooking it into both the Static and Dynamic Bitmap Text objects. This means you can now tint text:
And also change the tint in the dynamic texts callback by just modifying the data object like usual:
Just a little tweak, but one that opens up a lot of display options in your games. You can now color text without having to use more textures. And it also works on Retro Fonts too :)
Phaser 3 Labs
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. The group is for anyone who wishes to discuss what the Phaser 3 API will contain.
We're currently working on sprints of around 1 week for all of the Phaser 3 work. This fits in well with the newsletter as when a bunch of new features land I can write about them in the following issue. However, it's not always possible to fit the work into nice 5 day chunks and sometimes it just takes longer or needs more time to complete. The Input Manager is one such area.
Since the last issue, it has gone through some significant internal revisions. The API has changed dramatically even compared to that from a week ago and is still changing even now.
It was inevitable that at some point we would have a Dev Log that was going to talk about the process rather than show off any demos and I'm afraid that is what will happen this issue.
Input Scaling
On a positive note, the Input Manager is now handling canvas resizing, position and scaling properly. In the previous demos if you were to scroll the page with the canvas on it would mess up all of the input coordinates. Or if you scaled the canvas. These are now factored in. This means v3 demos using input can be placed anywhere within the web page and work. This wasn't something I was going to handle until starting the new Scale Manager but it felt too important to leave to them, so I bought that task forward. It will also be a good feature to have in place with the Alpha release.
Input Updates
Internally the Input Manager has gone through a lot of changes over the past week. While the previous iteration worked it wasn't set-up to handle multi-pointer input. For example, if you were to touch down on a sprite with one finger, then touch it with another finger and then release the first finger, the sprite would have thought it had entered an 'up' state (because a previously active pointer had left it). This is fine for desktops with mice, less so for touch screens. Although the number of mobile games that use multiple inputs on a single sprite is really low it was time to address this lingering v2 issue and put it to bed for once and all.
So I had to modify both the data structures for the interactive objects and also the input manager itself to cope with this. It does mean you could do some cool things now though: for example, you could have a sprite that looks like a Christmas cracker and pull it apart by dragging from each end of it with two fingers. This is something not possible in v2 without using two different sprites.
Move Events
Also new in v3 are move events. These events are dispatched whenever a pointer is in the processing of moving across an interactive object. It doesn't have to be pressed down or dragging, it just has to be moving. As part of the event you are sent the local coordinates of the pointer within the sprite. So you could use it for a 'sliding' UI element that you control by just sliding a finger up and down it, such as a volume meter.
Callbacks and Events
In v2 nearly all input was handled via Signals. You'd listen to a signal bound to a specific sprite to know if the pointer was pressed down on it.
In v3 you can use both callbacks and events. The events belong to the Input Manager itself, not the game objects. So, you could listen for a Pointer Down event from the Input Manager. As part of the event properties you are given a list of all the Game Objects that the pointer went down on, as well as the top-most one in the display list.
The callbacks, however, belong to the Game Objects. You can set a callback for every type of input event: over, down, up, out, move and the drag events: start, drag and end. Callbacks are invoked on a per-Game Object basis and are sent a bunch of useful arguments as well. Depending on the type of game you're building you may favour one approach over the other, or maybe just out of personal preference too. By having both options available though it gives you the flexibility to decide, rather than enforcing it upon you.
Top Most Game Objects
Part of the reason for the refactor last week was to implement a new feature across all of the input events. The feature was the ability for the Input Manager to process either just the top-most Game Object in the display list or all of them.
For example, if you had 3 overlapping Sprites and each of them is set to be interactive, then you can now set a toggle in the Input Manager as to how it should deal with them. The default setting is that if you were to click on the top-most sprite then it, and only it, would have its callbacks fired and appear in the event. The other two, being lower than it, would be skipped.
This is how browsers work and how the DOM works. If you have 2 DIVs above each other then only the top-most one gets any input events. So it's how Phaser 3 is going to work by default too. However, it's often very useful to be able to get every Game Object the pointer just pressed down on, or moved over, or dragged, so now you have the ability to do that as well.
Onwards to the Alpha
I spent this morning updating the v3 progress chart, marking off the things we've done and moving other tasks around. I still need to spend several days on the Input Manager and then will look at preparing the Alpha release of v3. part of the release process will be authoring a Getting Started guide, so you can pick it up and have a play without using the API docs (because they don't exist yet!). We're still on schedule to release the Alpha on Monday 31st July, which is the same day as the next newsletter.
I need to start looking at how to handle the API docs very soon. I want to use JSDoc again because it's so common and IDEs support it so well, but without using the same template as v2 has. So it's going to take a while to do some R&D to work out the best approach here. If you've any recommendations for decent documentation tool chains then please let me know!
Tinted Bitmap Text
I couldn't go a whole Dev Log without at least one new example :) The other week Felipe added in the ability to set the vertex colors in the Bitmap Text renderer. I finished that off by implementing the Tint component and hooking it into both the Static and Dynamic Bitmap Text objects. This means you can now tint text:
And also change the tint in the dynamic texts callback by just modifying the data object like usual:
Just a little tweak, but one that opens up a lot of display options in your games. You can now color text without having to use more textures. And it also works on Retro Fonts too :)
Phaser 3 Labs
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. The group is for anyone who wishes to discuss what the Phaser 3 API will contain.