Welcome to Issue 119 of Phaser World

Transcription

1 Welcome to Issue 119 of Phaser World Hello! It's been a couple of weeks since issue 118 because we've been utterly snowed-under with work on Phaser. You can read all about that in this issues

2 Dev Log. This issue is a special double-length edition to make up for missing a week, with a huge and exclusive tutorial on Phaser 3 Scenes, news on docs, TypeScript, a double-dose of articles and more! Until next issue, keep on coding. Drop me a line if you've got any news you'd like featured by simply replying to this , messaging me on Slack, Discord or Twitter. The Latest Games Game of Week Exocraft Design unique exocraft and build your fleet of drones to battle and mine for resources in this massively multiplayer action strategy set in an alien wasteland. Staff Pick Breaking Bricks It's breakout in overdrive! Up to 4 local players, 13 boss battles, 198 levels, gamepad support and superb graphics and sound.

3 Wedding Run Creating to celebrate a wedding this is a fun platformer. Collect coins and avoid bunnies! Source code also available. BeFive Dealer Ginjirou A classic betting game given a nice visual twist. Bet your (virtual) credits on an odd or even outcome and win big, or go home shirtless. Whippy Chute A cute little free Android game, just tap to change direction of your chute. What's New? Phaser Released

4 The latest update to Phaser 3 is out and contains no less than 100 enhancements across API. From new camera effects to bug fixes, development continues at a rapid pace. Phaser CE v Released This new point release fixes an issue with Cocoon packaging of Phaser games. Ercraft Trading, Crafting, and Dungeon Crawling on blockchain. A decentralized RPG running on Ereum Blockchain. Dungeon Escape A cute time killer game template with full source, easy to reskin and export to mobile. How to Create a Game with Phaser 3 A comprehensive new tutorial from Game Dev Academy, with full source and assets included.

5 Pathfinding and Phaser 3 An A to Z guide to pathfinding with Easystar and Phaser 3. TexturePacker and Phaser 3 Tutorial A tutorial with examples on how to create sprite sheets for Phaser 3 with TexturePacker. Game Distribution API Tutorial A guide on integrating your game with Game Distribution API to take advantage of ir services. Thank you to our awesome new Phaser Patrons who joined us this week: rex colbydude Melissa Sorrells also thank you to Paul for donation. We are currently 94% of our way to next funding goal: "We will publish an

6 exclusive Phaser 3 code example once per month. Patrons get to vote on topic y'd like to see covered in example." Patreon is a way to contribute towards Phaser project on a monthly basis. This money is used entirely to fund development costs and is 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. Dev Log #119 It's been a couple of weeks since last Dev Log and reason for this is that so much has been happening that I really struggled to find time to write. It takes a lot of effort, many hours of work, to create newsletter each week. I personally write all articles on site. I grab screenshots, play games, source links and put it all toger. Then I write Dev Logs as well. In a typical week, it takes around 1.5 days to do all of se tasks, which is time I've been spending working on Phaser instead. I've tried getting people to help in past, but even when offering to pay m y rarely last more than a few weeks and n I'm back to doing it on my own. However, I know it's main way in which you all read about what is happening, so I'll try to make sure we get back to being weekly again soon. I guess a little news often, is better than large dumps of news more sporadically. And a heck of a lot has been happening. Massive amounts of work on API Docs, TypeScript defs, 3.3 release and all work put into 3.4 release

7 being worked on at moment. Plus we've Containers up and running too. So it's safe to say that if we skip a week for newsletter it's literally only because Phaser itself is being advanced at such a rate. Thank you to everyone who supports Phaser. We're nearly at end of funding received from Mozilla, so every little bit we get from Patreon and donations helps right now. If you can't contribute financially n please perhaps help with finding bugs, helping with docs or just spreading word about Phaser to your peers. It all helps :) API Docs and TypeScript Defs I've spent many days over past couple of weeks working on v3 documentation. This has entailed fixing no less than 1034 data-types, creating typedefs, refactoring way certain classes export and endlessly testing, and re-testing jsdoc export. It's a truly tireless task. Progress has been great though and a couple of really good things have come out of this effort. First, I published Phaser 3.3 API docs and y're now hosted on GitHub Pages, so you can browse m online: Phaser 3 API Documentation This is using foodoc template, which isn't perfect but is much better than alternatives. The downside is it takes just over 1 hour to generate html, which is highly frustrating. I'm working hard on our own SQL based template, so you can do proper searches and cross-indexes and that will be presented on our web site. For now, though, GitHub version is better than nothing. And at least all of returns and data-types are accurate. My thanks to community member orblazer for helping with so much of this work. As a result of our combined effort, Peter was finally able to complete his TypeScript Definitions generator. It took a lot of trial and error but we're now generating fully-compiling TypeScript defs direct from Phaser source code. You can download TypeScript Definitions here. This is our first pass at defs. There are improvements to be had, but at least you can download m and use m in your projects. We will not be adding m in to package until y are more robust. We have also published source code to our TS Defs Generator (which itself is written in TypeScript) and you can find it, along with tests in Phaser 3 Docs

8 repo. See README for more details. If you would like to help refine TS defs, or docs, n please do. I often get asked by people "when will docs be ready?" but truth of matter is that, as of today, re are still over 7000 items in API that need documenting. If you search v3 source for string '[description]', that is tag we use to indicate that docs need to be written for that item. It may be a property, or a method, or a return statement or a function, but if it has that tag it means we've completed data-type for it, but not explanation as to what it is or does. Some are more obvious than ors - if you come across one that you feel you could accurately describe n we would love a pull request from you to add it. So, when will docs be 100% complete? I don't really know. If we work toger n perhaps quite soon. If I have to do m all on my own, n it's going to take several months at least. In meantime, please stop asking, I'm afraid re is no magical docs fairy to write m for us, it's going to take hard work and nothing less. Phaser 3.3 Release Phaser was released on March 20th and represented 10 days worth of development since previous version. I'm sure you'll agree Change Log is pretty epic given quite short amount of time. There are 32 new features in and here are some of highlights: Lots of

9 new Game Configuration properties which are passed to renderer, including power preferences, antialiasing, drawing buffer preservation and more. Arcade Physics can now wrap physics bodies around world. Camera shake, fade and flash all now have optional callbacks that can be invoked when

10 effect completes. Camera fadein and Camera fadeout are two new methods to help with scene transitions (also with callbacks) Groups now listen for destroy event coming from children and automatically purge m from Group if received. re is a new MatterGameObject which allows you

11 to bind a Matter Physics body with any renderable Game Object, such as Text, Bitmap Text or TileSprite (see labs for examples) Sound Manager has new chainable setrate and setdetune methods. Remember, se are just new features. There are also 21 bug fixes and 47 updates. Lots of those updates introduce new features too but in a non-invasive (to API) way. Containers Felipe has been working on implementing Containers into core API. These are ir own special kind of Game Object that can support having children. Modify container and children are all updated immediately. A lot of effort has been spent ensuring that process of merely adding containers into API didn't adversely affect anything else. For those of you who don't need to use

12 m, we were adamant that you shouldn't have to pay any processing cost for making that choice. Only those who actively create containers will get overhead required to process m added to ir games. This took quite a bit of research. However, we're now happy y are working and rendering correctly as you can see in demo below. Containers support any type of rendering Game Object as a child, including or Containers. If Container is on root display list (i.e. not nested within anor) n you can apply a Bitmap Mask to it and it'll mask Container and all its children. If you would like to experiment with Containers you can checkout containers branch of Phaser repo. Once Phaser 3.4 is released we will merge this branch into master ready for version 3.5, which is estimated to be a couple of weeks away. A Guide to Scenes I've seen a lot of people asking about Scenes. What y are, how to use m and how to get two scenes to talk toger. In this tutorial, I'm going to cover all of se topics. This tutorial will also be published to Phaser website, but for

13 now, newsletter readers get it exclusively. There's a lot of information coming up, so get comfy and settle in. What is a Scene? In Phaser 2 re was concept of a Game World and States. A State allowed you a view into Game World and only one State could ever be running at once. The State had access to all kinds of systems, such as a Camera, Tweens and Game Object Factory. When you used a command like `this.add` from within a State, you were talking to global Game Object Factory. Once you were done with a State you moved to next one. States were often split up into logical sections, such as a Preloader State, a Main Menu State and so on. In Phaser 3 we changed our approach to this entirely. The first change was that States were renamed to Scenes. This was to avoid ambiguity with 'state machines', which are commonly used in games. The global State Manager was also replaced with a Scene Manager. The changes were not just in naming of classes though, y run much deeper than this. Rar than Phaser managing one 'Game World' re is now no World object at all. Instead of Scenes just having references to all of systems that Phaser.Game instance owns, y now own m mselves. You can think of Scenes as being almost entirely self-contained Game Worlds in ir own right. They manage ir own input, tweens, game objects, display list, cameras and more. A Tween created in Scene A is completely separate to one created in Scene B. Scenes now control everything using ir own instances of plugins. In fact, only thing that Game itself is responsible for is passing on global DOM-based events to Scenes, such as when to update (from RequestAnimationFrame) or core input events from Input Manager. The handling of se events is done by Scenes mselves though. What does Game still control? There are a few systems which are inherently global in ir nature and refore belong to Game instance. These are: Renderer. There is only

14 one instance of eir Canvas or WebGL Renderer per Game, and it's a property of Game object. Animation Manager. Animations in Phaser 3 are global and no longer bound to a specific Game Object. You can create many different animations, which are all

15 stored in Animation Manager, and n any Game Object, in any Scene, can use m without duplicating lots of data and wasting memory. Cache. When files are loaded by a Scene y are placed into a global cache. So if Scene A loads an

16 XML file, that XML data can be retrieved by any Scene as cache is global. Registry. Every Scene has its own instance of DataManager, but Game also has one which you can reference from a Scene via property `registry`. This allows

17 for easy cross- Scene data exchange (as we'll see later in this guide) Input Manager. The Input Manager does very little in Phaser 3. It just monitors and processes DOMlevel input events, such as those raised from pointers, gamepads or keyboard. Every Scene

18 has its own Input Plugin, which is what does all of real work with events, and is what you interface with when calling `this.input` from a Scene. Scene Manager. Responsible for creating, managing and updating all of Scenes in your game.

19 Device Inspector. Allows you to poll for features supported by browser and hardware your game is running on. The Device class is actual a singleton and only runs once per browser, so isn't directly bound to your Game instance (i.e. if you had 2 game

20 instances running on same page, y would share global Device inspector) Sound Manager. Like rendering, sounds are managed by a global system in Phaser 3. You can create Sound objects, markers, and so on from your Scenes, but re is only one manager

21 running at once to avoid resource allocation issues. TimeStep. This plugin manages Request Animation Frame loop and updates core Game, causing it to step. You rarely need to interact with this directly. Everything else, such as Tweens, Physics, Game Objects and Input handling are all managed through Scene level plugins. The Game is now only used for timestep and systems that are truly global, which wouldn't have made sense to duplicate per Scene. What happens when you create a Scene There are lots of different ways to create a Scene but fundamental approach is same in all of m. A Scene consists of a Scene Configuration object and

22 a bunch of functions. Here we'll create an example Scene using an ES6 approach: We extend `Phaser.Scene` object and give it a unique key (in this case `MyFirstScene`) in constructor. There are two methods: `preload` and `create`. The first loads an image, second displays it. You don't have to have a `preload` method, only requirement to be a valid Scene is a `create` method as this is global entry-point of all Scenes in Phaser 3. Here is exact same thing using ES5: Creating Scene on its own isn't enough though, it also needs to be added to

23 Game. You can do this when Game is created, using game config like this: The Scene has been passed in via `scene` property. This can also be an array of Scenes if you have more than one. This is exactly same regardless of ES5 or ES6. If you've looked at any of Phaser 3 examples you'll probably have seen a completely different method of creating a Scene that looks more like this: So hang on a minute, in ES6 and ES5 Scenes we passed an instance of m in game config, but in above code we're passing an actual object

24 with just a couple of properties (`preload` and `create`) instead. The reason this works is that, internally, Scene Manager does a lot to determine what's being given to it. First it looks at `scene` property of game config. If it's an array it n iterates through it, processing each entry in turn, orwise it just processes first entry found. It inspects each item given to it to see what type it is, i.e. a class, an object or a prototype function, and n turns m into full Scene objects, adding m into Scene Manager. Ultimately, it doesn't matter which approach you use to define your Scene, once Scene Manager is done with m y're all treated same internally anyway. And it's when y get turned into full Scenes that y gain several important additions such as Scene Settings and Systems, plus ability to communicate with each or. Scene Settings When your Scene is created it extracts any settings you may have defined in its config. If re aren't any, it just uses defaults. Settings are defined in a configuration object passed to Scene constructor. Here's an example of setting Scenes name and physics engine from config: The Settings object can also be used to load files. You should really only use this

25 for loading small files as no progress feedback is ever given to user. Use following syntax: The assets are loaded before your Scene Preload method is called. It's perfect for loading a very small number of graphics, i.e. a background and progress bar image, that your Preloader Scene can n display while loading all rest of game assets. Or you could use it to load your internal game config, which could be parsed before loading rest of assets. Scene Systems When Scene Manager creates your scene it installs a Scene Systems object into it. This is placed on property `sys`, meaning you should never replace or overwrite property `sys` in your game code, or very bad things will happen :) The Scene Systems class is heart of your Scene. It controls all of Scene plugins, emits events, lets you to modify Scene (such as sending it to sleep, waking it up, etc) and allows all of plugins to communicate with each or. It will automatically install 7 Core Plugins into your Scenes: An Event Emitter 2D Camera

26 Manager Game Object Creator Game Object Factory Scene Plugin Display List Update List As you can see from list above, each Scene has its own Display List, factories and Camera system. So when you issue a command like `this.add.image` you're interfacing directly with Scene based Game Object Factory, and adding resulting image to Scene level display list. These plugins are non-optional, as y all rely on each or being present. So every Scene has m. However, you can control which are exposed as properties on Scene objects via Injection Map. There are also 7 Default Plugins. These are installed into your Scenes unless you specify orwise via Scene config: 3D Camera Manager Clock Data Manager Plugin Input Plugin

27 Loader Plugin Tween Manager Lights Plugin The plugins above are all optional. As with Core Plugins you can control which ones are exposed via properties using Injection Map. Configuring Plugins Remember that Core Plugins cannot be removed. To remove all of Default Plugins you simply have to pass an empty plugins array in your scene config: If you now try and use `this.load` in your Scene, it will fail, because Loader Plugin has been excluded from this Scene. If you want just Loader and Tween plugin, but none of ors, you can specify just those:

28 If you're not sure which plugins you will need when you create your Scene you can install m via Scene Systems. This must be done in an `init` method: The call to `install` tells it to install Default Plugin `TweenManager`, allowing you to add tweens in this Scene. Scene Injection Map In Phaser 2 State Manager would create no less than 19 properties within your State, all linked to global game systems. For example, it would take your State and n add `physics` property to it, which mapped to Physics manager, `scale` mapped to Scale Manager, and so on.

29 This was a double-edged sword. It made Phaser incredibly easy to use. There was no convoluted access required to a system, you literally just typed it out and re it was. However, you had no choice over quantity or name of properties that were injected. If you really wanted to use a local property called `world` you couldn't without literally breaking your game. If you accidentally overwrote one of 19 default properties, it would also break your game. Experienced devs learned to deal with this but we thought re was a better way for Phaser 3. To that end, we created a Scene Injection Map. This object controls which plugins are mapped to properties within your Scene, and controls exactly what those properties are called. By default all of following properties are installed into a Scene: 'anims' = Animation Manager (Global) 'cache' = Cache (Global) 'game' = Phaser.Game instance (Global) 'registry' = Game Data Manager (Global) 'sound' = Sound Manager (Global) 'textures' = Texture Manager (Global) 'add' = Game Object Factory (Local, Core) 'cameras' = 2D Camera Manager (Local, Core) 'children' = Display List (Local, Core) 'events' = Event Emitter (Local, Core) 'make' = Game Object Creator (Local, Core) 'scene' = Scene Manager Plugin (Local, Core) The following properties are installed into a Scene only if respective plugin is available: 'cameras3d' = 3D Camera Manager (Local, Optional) 'data' = Scene Data Manager (Local, Optional) 'impact' = Impact Physics (Local, Optional) 'input' = Input Plugin (Local, Optional) 'lights' = Lights Manager Plugin (Local, Optional) 'load' = Loader Plugin (Local, Optional) 'matter' = Matter JS Physics (Local, Optional) 'physics' = Arcade Physics (Local, Optional) 'time' = Time / Clock Plugin (Local, Optional) 'tweens' = Tween Manager (Local, Optional)

30 If you prefer you can choose not to have any properties added to your Scene at all: Or you can change name of property that is injected using `map` object. Here we will replace English properties with Spanish equivalents:

31 If your IDE supports it, you can even use UTF8, such as this Simplified Chinese version:

32 Cross Talk - Calling a Scene function Now we know how to create and configure Scenes, let's get m talking to each or. There are several ways to achieve this: Calling a function directly, listening for an event or exchanging data via registry. We'll cover each now: Calling a Scene Function First, we'll create two basic Scenes:

33 Here SceneA listens out for pointer events. When it receives one it calls `clickhandler` method. In here we grab a reference to SceneB. This is done using Scenes key, which is `MySecondScene`. Once we have that, we can call any public methods which it exposes. In this case we're calling `getposition`. This method returns a vec2 with a random location in it. We n add an image at that location. It's not exactly a complex example, but you should get idea: Any public function defined on a Scene can be called by any or scene.

34 Listening for Scene Events In this example instead of calling a function on SceneB directly, we're going to have it listen for events from SceneA. The set-up is same as before, but our clickhandler is different:

35 Here, when a box is clicked, we dispatch `addscore` event. Our SceneB looks like this:

36 It creates a text object to display score, gets a reference to SceneA and n listens for `addscore` events from it. When it receives one it updates local score and Text object. The advantage to this approach is that SceneA is not tightly coupled to your SceneB. As long as event names don't change, SceneA can happily sit re, dispatching events as long as it likes, knowing that any or Scenes interested in m will pick m up. However, it does mean that SceneB is coupled to SceneA, as it needs a reference to it in order to listen to its event emitter. We can avoid this entirely by using Game Registry.

37 Exchange Data via Game Registry We're going to expand upon previous example slightly. This time we will be using Game Registry, which is an instance of Data Manager Plugin, in order to exchange data. This is SceneA, our GameScene. It's same as before, except we tint every or box red. If you click a red box n you lose one of your lives. If you click a normal box, you gain a point:

38 As boxes are clicked we updated respective values in registry using `registry.set` call. Now to SceneB. This Scene is same as before, except we've added anor Text object to display lives remaining:

39 It listens out for a `changedata` event from Registry and invokes `updatedata` method if it receives one. This method is set 3 items: parent, i.e. owner of Data Manager, which in this case is Game. It n receives string-based key of entry that was changed, and n finally new value of this entry.

40 By checking key we can tell if it was score or lives that were changed and update our text objects respectively. As you can see, using Game Registry gives us a fully decoupled method of communication between multiple Scenes. In next tutorial we will look at visual aspects of Scenes - changing ir position on scenes list, and how to make m sleep and wake. This is a great article: Making computer games from scratch in When ios throttles Request Animation Frame to 30fps. ElefantaSTic by Genesis Project is a super-cute Atari ST demo, with lovely graphics and music.

41 Phaser Releases Phaser released March 22nd Phaser CE released March 21st Please help support Phaser development Have some news you'd like published? or tweet us. Missed an issue? Check out Back Issues page Photon Storm Ltd Unit 4 Old Fleece Chambers, Lydney, GL15 5RA, UK Web Version Preferences Forward Unsubscribe