Published in Phaser World Issue 99 on 2nd October 2017 by Richard Davey   @photonstorm

Number Count Tweens, Curves, Paths and Followers.

Another week, another beta. This time Phaser 3 Beta 5. Beta 5 brings the Path and Curve functions to the party, which are the main ones we'll discuss this issue. First, a quick run-down:

Number Count Tweens

Tweens are great for, well... tweening values. The problem is that they need a target to work on. For example, if you want to tween the position of a sprite then the sprite is the target and the tween manipulations the position properties. This is all good and well, but how many times have you wished you could just tween a single local value and have found you need to first encapsulate it into an object just so you can do that?

Say hello to Number Counter Tweens. These are a slight variation on the Tween already built into Phaser 3 that are special in several ways. First of all they don't require a target. Instead, they allow you to easily tween between two numeric values, floats or integers. The default values are 0 to 1 and can be changed to anything. Here's an example:

image

You then specify a duration and can optionally add all of the usual things a tween supports, such as yoyo, repeat, delay, etc. You can retrieve the value using tween.getValue() and still have access to things like the progress and duration of the tween. It's a really quick way to create a numeric counter without making any other local objects first and will automatically clean itself up when it completes.

Extended Scenes and ES6 classes

Two small changes were made to the Scene Manager this week. The first is that you can now use native ES6 classes to define your Scenes and it doesn't require any special hacks or changes. Here's an example:

image

The second change was that if you use the anonymous object method of defining a Scene, which, for brevities sake, is the way most of our Phaser 3 Examples are written, it's now possible to extend that object with additional properties and functions as the image below shows:

image

It's a bit tricky to make out from the screenshot, as the code is quite tiny, so the image is linked to the Phaser 3 Examples editor where it should be a lot more clear. In short, though, you can define a new block in your scene config called extend and any properties added there will then be available under the scope of your Scene, meaning you can access them via 'this' and not have to go into them via the global scope.

While this won't be of much benefit to larger projects it's definitely helpful if you're throwing together a small prototype or just want to test something out quickly. This, combined with ES6 class support, completes all that we wished to do with Scenes for launch.

Let's get Curvy

I'm very pleased to say that Phaser 3 Beta 5 has all of the new Curve, Path and Path Follower classes within it. There are currently 4 types of curve available: Line, Ellipse (which can also be used to create circular paths), Spline and Cubic Bezier. A curve is essentially a connection between two or more points in space that can be defined by a continuous function. They have lots of used, but first, let's explore the 4 types available. In each example below, you can click to run the demo and then drag the curve points around to see what happens. First up, a Line Curve:

image

A Line Curve is a straight line between two points. This may seem no different to the Line geometry class already in Phaser 3 but it's an important construction piece when putting together Paths, as you'll see shortly.

image

An Ellipse Curve is the same as an Ellipse except you can control the start and end points, the angle of the ellipse and if the curve moves in a clockwise or anti-clockwise direction. If you play around with the example above, especially the 'start' and 'end' sliders, you'll see how powerful this can become. Setting the width and height to be the same values will create a circle.

image

The example above is a Cubic Bezier curve. It has a start and end point, like a Line Curve and two control points which influence the function used to plot it. If you drag either the endpoints or control points you'll see how the curve adapts to their placement. Bezier curves are fascinating. I found a great animated gif on wikipedia explaining how they work so I recreated it as a v3 demo:

image

The final type is the Catmull-Rom Spline. This is a series of n points where the line is guaranteed to pass through each of them:

image

Here is an interactive spline drawing example where you can click to add a point or drag any of the existing points to manipulate the curve in real-time.

Curves all use the same API. You can easily create them from either Vec2s or an array of number values. They can be exported to JSON and you can interrogate them easily, getting points across them - such as spaced points (i.e. a point every 32 pixels), or ranged points, or tangent vectors:

image

Curves are handy little things to have in your toolkit. And we'll add more types soon such as Quadratic Bezier and Hermite curves. Where things start to get really interesting though is when you combine them together into Paths.

Paths

A Path is the collection of two or more Curves. The Path class has the ability for you to add any curves you've created to it. The path flows along the chain of curves and you can either connect those curves together, so they form one continuous path, or you can have gaps in them. Here's an example of a Path made up of all 4 types of curve:

image

The path above was created using this code:

image

When a new curve is added to a path it carries on from the place where the previous curve ended. You can also use the method 'moveTo' to position the curve point. If your curve already exists you can just add it to the path (i.e. you don't have to create them directly like in the example above).

With a completed path you can do all kinds of neat things. For example, you could easily use it as a means to bring a game logo onto the screen in an interesting way. You could use it to define alien attack waves for a shoot-em-up. You can use it for special effects between levels, for motion paths for sprites to follow, paths for enemy AI behaviors, and so much more. Paths are also easy to create dynamically. Here's a bunch of balls falling down a zigzag path:

image

Path Followers

One thing that curves and paths are really good for is guiding Sprites. To help facilitate this I created a new PathFollower Game Object. These are essentially Sprites with some extra muscle to handle following and orientating themselves to a path. You don't have to use a follower, any object can follow a path, but they serve as a helpful addition to the API. Followers are created via the Game Object Factory like usual:

image

In the simple example above a follower is told to follow a Spline curve. The value 4000 is the duration it will take to traverse the full spline. However, you have a lot more control than just that. The API uses the same configuration object as a regular tween, allowing you to set properties such as delay, hold, repeat, yoyo, ease and all the related callbacks (onStart, onComplete, etc):

image

This gives you a lot of control over the effect, allowing for some really neat things. Here's the full version of the example above in action:

image

Path Followers also have more control over how they should rotate to face the path, if at all. A follower can just follow the path with no rotation (the default). Or it can rotate based on the angle (including an optional offset), or it can adjust the angle so that it never 'flips over', keeping itself properly upright as it tracks the curves. Here's a small example showing the path rotation in action:

image

There's an awful lot you can do with paths. I honestly think they're a really exciting addition to the API. Followers make things a lot quicker for you, but as explained they're entirely optional. You can easily construct anything to follow a path, or use the path for other means - they don't always have to be graphical (a curve could control the volume of sound playback), or provide the inputs for an AI routine.

Or, creating fuzzy alien caterpillars :)

image

That's it for this Dev Log. Feel free to look at all the examples (there are 47 of them currently). Next issue is our 100th, so there will be a slightly different Dev Log than usual, although one I hope you'll find just as interesting.

Felipe is now away for the rest of October on an extended vacation, so I'll be handling all v3 development myself - this shouldn't slow things down much as we're done with all the rendering elements. But keep reading the logs for progress updates, keep an eye on the repo and keep sending me feedback and PRs. I've had quite a few really useful PRs recently that have nearly all been merged into the codebase, so it's definitely possible to get involved if you want to!

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 or post to the Phaser 3 Forum - we'd love to hear from you!