Newsletter
Welcome to Issue 100 of Phaser World
2 years ago, in October 2015, I published the first issue of Phaser World. It would be an understatement to say that a lot has happened since then! In this issue I'll explore both the old and the new, share some early concepts and run through what's involved in creating an issue.
Of course, we've got plenty of new games and tutorials this issue, just like always. Because the front cover is taken up with our birthday celebration image you'll see an enlarged screenshot of the Game of the Week below :)
If this is your first issue: Welcome! Why not have a scan through some of the previous 99 issues. If you've been here since the beginning, then thank you for sticking around. Either way, I hope you enjoy this issue. It's going to be a pretty long one, with lots of images, so if your email client cuts it off half-way, please do view the full thing.
So, until the next issue, keep on coding. Drop me a line if you've got any news you'd like featured. You can reply to this email or grab me on the Phaser Slack or Discord channels.
The Latest Games
Game of the Week
Destroy the enemy command center before they destroy yours in this incredible MOBA style future war game.
Staff Pick
Time the release of your ship from orbiting the planets well, to ensure you land on the next planet along and collect the orbs.
A vertically scrolling shootm-em-up set in the Star Wars universe.
Control the alpaca and avoid the hay and bad weather in this game created for Europe's biggest outdoor event.
Try and catch the thermals as you cross country paraglide.
What's New?
Mozilla Awards Over Half a Million to Open Source Projects, including Phaser.
Definitions, extensions and over 550 examples allowing you to use Phaser with Kotlin, a modern statically typed language.
Creating Games with Phaser Class
A free course on Phaser at Microsoft NYC offices with Adina Shanholtz (Technical Evangelist, Microsoft).
A tutorial on creating Snake mixed in with a first-time Phaser developers views and thoughts.
A free web based app to help define polygons from images for use in P2 Physics.
Multiplayer Game Tutorial Part 3
In the next part of this multiplayer game tutorial more gameplay mechanics are added allowing bigger players to eat smaller ones.
Welcome and a massive thank you to the new Phaser Patreons who joined us this week: Manuel Becker.
Patreon is a way to contribute towards the Phaser project on a monthly basis. This money is used entirely to fund development costs and is the only reason we're able to invest so much time into our work. You can also donate via PayPal.
Backers get forum badges, discounts on plugins and books, and are entitled to free monthly coding support via Slack or Skype.
The Making of Phaser World
Anyone who even slightly knows me knows I absolutely love computer magazines. It's no secret that I've always wanted to produce a printed magazine for Phaser, but the time and cost involved is prohibitive. It would be a full-time job. More importantly, things move really fast in the online world. In the time it would take to get a magazine written and published it would already be out of date. So a newsletter was the next best thing.
Many years ago I used to work for a company called The Game Creators and part of my job was producing their monthly newsletter. It was hard work but I enjoyed it. Their community was really active and it felt like a great way to celebrate that while announcing updates and new products. In 2015 Phaser was in a very similar position. Fantastic new games were released daily and the tutorials never seemed to end! I knew I had to provide a way to get this news out to you. But I also knew the amount of work that would be involved. If I was going to do a weekly newsletter then it would have to be as automated as possible. It would also have to look good.
While I got busy creating the workflow I would need, I called upon Tom to think about the design. You can see a lot of his work all over Phaser (he was responsible for creating the design of the site for example). He worked through some concept sketches for the logo and cover layout:
Two versions of the logo were created, one with the planet and one without. He also produced lots of concepts for the front cover. Notice the evolution of the designs and how we were both still assuming the image would be large and portrait size, like a proper magazine cover. Also, notice the shameless use of the awesome Wild Terra artwork to test our concept ideas on :)
In the end, it transpired that actually, the layout was too complex. It relied on a powerful background image to carry it and it would take up a lot of room in the email. Sadly, in the end, we had to drop the layout concepts above and instead focus on the smaller elements. We took the logo of course, which was excellent, and the little 'curve' shape for the issue number, and the overall colors and composition and created something far smaller and more sensible for the header.
Meanwhile, I was building tools to ease the content creation process. I had been writing news on the Phaser website since October 2013. I'd been doing this by hand. Back then the site was just a few static html files and the news was little more than a sentence and a link. The volume of news was also a lot less. January 2014 for example only had 7 news articles for the whole month. Today we'd release that many in 3 days.
There was no CMS and I honestly didn't feel the need to introduce one. I'd spent decades working on web-based backend systems by that point in my career, and I knew it was easy to over complicate things. Simple was best. So I stuck to Markdown files and static content. Even so, there were ways to streamline that.
News articles start life by being clipped to Evernote. Sometimes I pick things up on twitter (especially if they have the #phaserjs hashtag). I also check the Phaser Forum daily and look at my Google and Warble Alerts. Finally, occasionally people will email me links too. Whatever the source I end up adding it to Evernote:
I then choose which articles I want to add to the site in the coming week. I pick 5 games and 5 news items. Some things get published almost instantly, such as new releases of Phaser, or articles about conferences or date-sensitive subjects, but on the whole, I select from the news queue I have built up. I purposely try to mix the variety of content. A few tutorials, a video, a plugin release and a general news item. When it comes to selecting the games I do a similar thing. I will always plan ahead what the Game of the Week is going to be, and also my 'Staff Pick', but then I will select 3 other games to go alongside those. Again I try to keep it varied - mixing up kids games, puzzle games, IO games, arcade games, game jam entries, etc.
With those picked I then write the news articles. This involves lots of reading, playing and grabbing screen shots. They are then imported into the site via a custom front-end I built:
Once the news is added to the site I'm them in a position where I can create the newsletter. I do this every Monday. I've got tools I built that will allow me to generate everything needed for the newsletter. It exports the screenshots and text needed so I can copy and paste them into the newsletter interface. I also collect the 'Geek Links' in a separate Evernote book, and will pick 3 of those per week too. I then write the editorial, add in any new Patrons (thank you!) and finally get to work on the Dev Log. The Dev Logs are written 'fresh', directly into the newsletter (I then have more scripts I built to extract them back out again and place them on the website!)
Finally, I produce the header image, give it all a once-over and send it off to what is currently over 8500 people.
Looking back at issue 1 it's amazing to see what was going on back then. Headline features include the release of Phaser 2.4.4 and Particle Storm. There are some neat looking games including one I fondly remember playing a lot of: Space Bombers - sadly the game is no longer online though. Notice there was no concept of 'Game of the Week' back then either. Issue 1 looks somewhat sparse to me :) Even though there was quite a bit of content.
After a whole year of Phaser World, October 2016 saw Issue 50 arrive. The layout had evolved, as you'd expect, and is a lot closer to what we have today. There were some amazing games that issue, including the sublime Nearwood and I'd started writing the Dev Logs too.
I estimate it takes me at least 10 hours to select, read, play, grab and author the news articles every week. The Dev Log is another good few hours work on the top as well. Plus the act of collecting articles is constant and on-going. And still, even after 100 issues and years of hard work, I still really enjoy it. Mostly because the community continues to amaze me, producing stunning games and a never-ending flow of tutorials (thank you Emanuele!). This newsletter wouldn't exist if it wasn't for all the hard work we all put in together. It feels like a genuine celebration of the community and on that note, I look forward to the next 100 issues as well.
Dev Log #100
I know from looking at newsletter stats than when I show you lots of screenshots full of lovely eye candy, you click them in your hundreds! However, I've basically spent the past week up to my neck in the entirely unglamorous world of documentation.
If there is one thing I've learned over the years, it's that where possible, write tools to help you get stuff done. This week has been no exception. My objective was clear: I wanted to get all of the docblocks inserted into the Phaser 3 source code at 100% coverage. Every function, every class, every method, every constant, every property.
The aim was to do it in several steps. First I would add the docblocks themselves. These are the jsdoc formatted blocks that sit within the source. I wanted them to have the correct data types for every parameter and property. I also wanted all the return types to be added.
I was happy that the actual descriptions could come later. I would leave markers where the descriptions needed to be filled out, but having the actual docblocks would be a massive step in its own right. However, it is also a truly massive amount of work too.
To give you a sense of scale there are presently 1054 source files in Phaser 3 that need documenting. Some of those files (classes for instance) have hundreds of properties and methods within them. And every single piece needs covering.
It's not the sort of thing you can automate either. Sure, there are editor plugins like DocBlockr for Sublime, that will inspect your code and try its best to figure out what the arguments are. But on the whole, it struggles to infer anything beyond the basis, especially with a very function driven environment. For example, it simply cannot divine the properties of a configuration object and has no concept of any of the Phaser data types either. Plus when you're typing in hundreds of doc blocks by hand it is prone to human error. Mostly because it's such mind-numbing and repetitive work. After a few hours work your eyes start to glaze over and mistakes slip in.
Naturally, I wanted to keep mistakes to a minimum and my mind as un-numbed as possible. So I had to build a tool to help me out. Enter, Percy.
Percy Thrower
Percy is a web-based app that will scan a Phaser 3 source file and then intelligently work out how to inject docs into it. It does this because when we coded v3 we used the same structure and code syntax for all of our files. It doesn't have to analyze the code or do any AST parsing, instead it knows what to look for, and where.
It presents a long list of source files, which you can filter down by namespace, or view only those left to be documented:
Pick one and it will scan it and it'll go through the code, plucking out the functions or methods, figuring out what parameters they have. Some of these it will know based on their names, so it can pre-fill the data types. Those it can't I fill in manually, using a combination of a drop-down list of common v3 data types and a free-text area:
Once done it generates the docblock and injects it into the source. I can then save the code directly back into the v3 repo and it also keeps track of it in a local SQLite database.
There are lots of time-saving little tricks it can do. Such as knowing to use the correct glue when formatting method signatures, for example, you should use a hash # after a namespace to denote an instance method or a period for a static one. I also made the decision to make use of the @since tag so we can keep track of which version of Phaser something was added.
Most importantly of all, because the docs are being injected by code, there are no typos in the core of them. It's possible I may still type a data-type, but at least the formatting of everything will be completely consistent. And when you've got really complex configuration objects to document, like below, that's really important!
In order to retain as much of my sanity as possible while doing this work, I needed some progress charts. In short, for my own sake, I had to know how much there was left to do! As I'm logging the doc'd files to a database I now know that. Percy will happily tell me what the overall completion percentage is (as of today it's 19% - 200 files done out of 1054). And it will show me which files and sections are completed or pending.
As I mentioned at the start this is a two-step process. The first is this docblock work. Then the next stage is to go through all of the files and replace the '[description]' tags with an actual description of the property or method.
However, by completing the docblock work it means we can look at TypeScript definition generation, because for that all you need are the correct data-types in place, and we'll have those. It also means that editors that offer code completion based on JSDoc scanning, should now start to show you argument lists and the like.
Putting the actual descriptions into the source will be a large amount of work too of course. But breaking it up into steps like this makes it feel achievable. It's no longer an Everest to climb, it's now a range of smaller but more manageable peaks. I built the tools using a mixture of node scripts, plain JavaScript, a bit of jQuery (yes, yes, sue me) and Bootstrap. You can find all the tools in the phaser3-docs repo although I wouldn't even try to run them locally as they're not meant for public consumption.
The final stage is, of course, generating the actual doc files from all of this work. I've already done quite a bit of work on that and it will involve more custom tools. I'm going to be offering the full docs as a SQLite database file (as well as more traditional html format of course) which I think will be really useful for anyone wanting to build the docs into their own tools. It will also allow me to offer a really advanced documentation front-end on the Phaser web site. The ability to truly search docs, filter by data-types, expand examples in-line and directly link to related to tutorials will be great. Plus, it will open the docs up for easy translation.
Oh, and why did I name this tool Percy? It's named after Percy Thrower, who was a famous British gardener around the time of WW2. His surname means 'someone who twists fiber into yarn' - and honestly, modernizing that farming concept slightly, it feels like I'm doing that here: extracting the meaning of the code and twisting it into documentation which will tell its own story.
Phaser 3 Labs
Phaser 3 Beta 6 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!
I love browsing the Amiga Graphics Archive. Stunning pixel work on show :)
Check out this Space Walk filmed in 360! (move around anywhere you like, it's pretty neat)
Lucky enough to get your hands on a SNES Mini Classic? This guide shows you how to mod it to run pretty much any SNES game!
Phaser Releases
Phaser CE 2.9.0 released October 8th 2017.
Phaser 3 Beta 6 released October 9th 2017.
Please help support Phaser development
Have some news you'd like published? Email support@phaser.io or tweet us.
Missed an issue? Check out the Back Issues page.