The Starling Manual

In all honesty: I admire this game. It demonstrates that it’s often the most simple ideas that provide the most fun. Yes, it might be argued that it’s not the most original game. Without question, though, it is definitely challenging and addictive!

If you haven’t played it before, here’s what Flappy Bird is about.

As simple as this sounds, it’s actually damn hard to score just a few points — and that’s what this game is all about: the challenge is to stay focused and concentrated as long as possible, without making an error.

There’s nothing else: no growing difficulty curve, no fancy graphics; it’s just you and the bird. And since each session just takes a few seconds, it’s perfect for a mobile game.

Furthermore, it’s a game about a bird right? That’s reason enough to make this the perfect example for our jump into Starling!

It’s time to look at the root object that is going to host Flappy Starling.

As you can see, there isn’t that much going on yet. All we are doing at the moment is storing a reference to the AssetManager instance that’s passed to us from the startup class.

At this state, our AssetManager instance already contains all the assets we need. The startup class (FlappyStarling) made those preparations for us.

Time to add some content to our game! I’m getting bored of this empty blue canvas. Modify the start method like this:

When you type that code, be careful when you come to the Texture keyword. There are several classes named Texture, and your IDE will probably ask you which one you want to import.

When working with Starling, you will usually need to pick a class from the starling package. Otherwise, the IDE will import the wrong class, and you will run into weird errors. If you accidentally picked the wrong class, it’s easy to fix: just delete that import statement at the top of the file and try again.

When done right, your IDE will add the following import at the top of the file:

Finally, we have drawn something to the screen! But how did we do that?

It might be necessary to clarify how we moved the texture to the bottom of the screen. The x- and y-coordinates control the position of an object relative to its parent. If we left both coordinates at 0, the image would appear at the top left. That’s because in Starling, the coordinate system looks like this:

We also accessed the stage object and queried its height. The Stage describes the area to which everything is rendered; it is the very root of Starling’s display list (and parent of the Game instance we are working with right now).

You have already seen this class before: our Game class is extending Sprite. This class is one of the most important building blocks within Starling. It’s a container that can group together multiple elements.

Here’s a simple example showing a typical use-case of a sprite:

The bird object now contains body, tail and beak, grouped together in one object. When you want to move around the bird, you just have to change the x- and y-coordinates of the bird instance; all child elements will move with it.

If you want the bird sprite to be reusable, you could also use the following approach:

That’s a very common pattern when working with Starling. One might even argue that this is your main task as a developer: to organize your display objects hierarchically by grouping them into sprites (or other containers), and to write the code that glues everything together.

As mentioned above, the Game class is our top-level sprite. It’s going to be the controller that manages what’s going on at the highest level. The other elements will follow the lead; one of them is the World class.

The World class is going to deal with the actual game mechanics. When the Game tells it to launch the bird, it will do just that; and when the bird crashes into an obstacle, it will notify the Game and will wait for instructions about how to go on.

For starters, create that new class and add the following code:

What’s left to do, of course, is to reference this new class from Game.as. Here’s how it should look like now:

Compile and run to check if everything worked out. Except for the two inconspicuous new clouds, it should look just like before.

To do that, we first create a Vector of Textures that references the frames of our animation.

The textures we are looking for are named bird-1, bird-2, and bird-3. To get those textures from the AssetManager, the getTextures method comes in handy; it returns all textures with a name that starts with a given string (sorted alphabetically). The middle frame is supposed to be reused for the upward-movement of the wing, so I added another reference to that texture to the very end of the vector.

To actually display those animation frames, let me introduce you to the MovieClip class. It works very similar to an Image (it extends that class), with the difference that it changes its texture over time.

Let’s try this out in our World class. Make the following modifications:

As you can see, the creation of the MovieClip is quite straight-forward; you simply pass the Vector of textures to its constructor.

Run the project now to see the bird airborne!

Something seems to be wrong, though: there is no flapping animation, just a static image!

That’s because the MovieClip doesn’t have any information about the passage of time yet; and without that information, it will simply stick to the very first frame.

In this case, we want to have full control over the bird’s animation, so we will update it manually once per frame. Let’s do this by adding the following method to the World class:

The advanceTime method moves the playhead forward by the given time. Thus, we want this method to be called once per frame, and the passedTime parameter needs to contain the time passed since the previous frame. Sounds like a job for our Game class, right? Open it up and add the following code:

This code introduces a concept that hasn’t been mentioned before: events. We will look into that topic in detail a little later, but that code should be rather intuitive. We listen to an ENTER_FRAME event, which is a standard event that’s dispatched once per frame to every display object. As a result, the method onEnterFrame (the event handler) will be called repeatedly.

The event handler also contains an argument called passedTime, which is just what we need in the advanceTime method we just defined on World.

Which means that everything is in place to get that bird flapping! Compile and run the code now to see it in action.

That’s all still a rather static business, though. Instead, we want to create the impression that the camera is following a bird that’s flying to the right. To do that, we will move the ground slowly to the left, just like an endless ribbon.

Had we built the ground from separate images, this would be quite painful.

You might run into that situation one day — it’s rare that the ground is built from just a single tile. However, in this situation, with our tileGrid in place, it’s much simpler: we let Starling do the work for us.

Our task:

Our existing advanceTime method will pull that off.

There really isn’t much to it: all that we are doing is reducing the value of tileGrid.x a little in each frame. The result is a neat, endless animation of the ground ribbon.

A bird that flies in the air is constantly being pulled down by gravity. What does that mean?

Gravity changes the velocity of an object: push a stone off a cliff and its velocity will rise from "zero" (the moment it loses contact) to …​ well, "very fast" before it hits the ground. The higher the cliff, the faster it will be on impact. Each instant it falls, it will be faster than the instant before.

So we make a mental note that we need to store our bird’s current velocity somewhere, as well as the acceleration imposed on it by gravity.

The other force acting on the bird is — the player. When he or she touches the screen, the bird is catapulted upwards, i.e. the velocity is set to a fixed value.

Let’s incorporate all that into our World class:

You might ask why birdVelocity is a scalar, not a vector. That’s because our bird actually only moves along the y-axis (i.e. vertically). There is no horizontal movement — that’s just an illusion we created by moving the ground to the left!

The next step is to update birdVelocity each frame, and to move the bird by that velocity.

That’s actually all our physics code. You probably agree that adding a full-fledged physics library would have been an overkill in this situation!

There’s one more step to do: allowing the player to control the bird, i.e. to call that new flapBird method. Please open up the Game class and make the following modifications:

Just like we were notified of the passing of time via the ENTER_FRAME event, there is an event that’s dispatched when the user’s finger touches the screen: the TOUCH event. When such a touch occurs, we let the bird flap upwards.

Start the game to check out if everything works. The bird will start to fall downwards immediately, and you can bring it up again by clicking on the screen repeatedly. Finally, this is starting to feel like a real game, right?

What’s a little annoying, though, is that when you’re not careful, the bird falls off the bottom of the screen, and it’s quite an effort to bring it back up again.

So I’d like to fix that before moving on, even though I’m getting a little ahead of myself. What we’re going to do is implement the first part of the collision detection logic, a topic we will soon come back to.

Just like the physics code, this needs to be part of the World class.

That makes playing around with our prototype much easier! Granted: when we hit rock bottom, it should actually mean "game over", but the bird just moves on. That’s the topic of the next chapter!

I wrote earlier that the Game class should act as a high level controller that manages all the components of the game. Now that a collision has occurred, there is some management to do: for example, we might want to save the score and display a "Game Over" screen. The World class wouldn’t be the correct place for these tasks.

However, in order to do anything about it, Game needs to know that a collision occurred. How can we tell it about the crash?

The natural thing to do would be to call a method on the Game instance; however, we don’t have such a reference within World.

This is a quite common scenario, actually, and the reason why there are events, at all.

In this case, the event type is the String stored in the static constant BIRD_CRASHED. We dispatch an event with this type when we encounter a collision; that’s done via the line

For this to be of any use, somebody must listen to this event, of course. So that’s how the Game class will become aware that a collision has occurred — it simply listens to the BIRD_CRASHED event. Open it up and make the following modifications:

That’s not so complicated, right? Now, the method onBirdCollided acts as event listener; it will be called whenever the event occurs.

Let me tell you a little more about the delayCall method you just encountered in the event listener. When the bird crashes, we don’t want to restart the game right away; instead, we want the player to have a little time to realize what just happened.

For this reason, we are not restarting the game right away; instead, we wait a short moment before calling the restart method. The delayCall instance on Starling’s Juggler is the preferred way of doing this.

When the application starts, we are in the IDLE phase. The actual game session is supposed to start when the user touches the screen. That’s the final step we need to make in order for our phase-system to work.

Update the onTouch event handler inside the Game class like this:

Start up the game now. If everything went right, the whole thing should feel much more like a game already! We’re now switching properly between the IDLE, PLAYING, and CRASHED phases, and you’ve got the chance to restart properly after a crash. Not bad!

We could treat each obstacle simply as two separate images; on the other hand, the two trunks will always move along together, so it will quickly pay off to group them in a custom class. This will also simplify the collision detection code we need to implement in the next chapter.

Create a new class called Obstacle that extends Sprite.

The basic setup is pretty straight-forward, obviously. So let’s deal with the code marked as TODO: adding trunk images.

Basically, we just need to add two images with the textures referenced at the top of the constructor. But how exactly should we best position them within the sprite?

I decided that the following setup would make most sense:

You see that the sprite’s origin is in the center and the trunk images extend upwards and downwards. The bird must be guided through the empty gap, so it’s important that it’s always in the visible area of the stage. With the origin right at the center of the gap, it will be easy to place the obstacle within the World later. The two trunk textures are very long; they will always exceed the stage bounds from this point.

The following code (to be added to the Obstacle constructor) sets up the sprite like that.

Do you remember the pivotX and pivotY properties we used when we created the bird object? Here they are again! This time, we move the pivot points of the top and bottom images to the center of the circular shape that terminates them. We could have placed the images without changing the pivot point, of course — but I find this setup easier to handle.

Now that the basic building block is ready, we can integrate obstacles into the actual gameplay. As a first step, let’s add some constants that we’re going to need later. Add the following definitions somewhere near the top of the World class.

The first two of those values actually make up the difficulty of the game. The values I used are educated guesses; later, when we fine-tune the game, we can always modify them until they feel right.

We are also going to need a few additional member variables. Add them to the others we already defined at the top of the class.

With that out of the way, let’s move to some basic setup procedures. For example, the container that will take up the obstacles needs to be initialized.

Furthermore, when the game session starts or ends, we need to reset some values:

Agreed: this was a lot of rather boring stuff. We are done with that, though: time to actually add some obstacles to the screen.

Since the obstacles are constantly moving, that logic must be triggered once per frame. We already have a method that fits that description, right? Exactly: I’m talking about advanceTime. Make the following modifications to the part that deals with PHASE_PLAYING:

Most of the task is actually forwarded to the advanceObstacles method. It needs to handle several things:

Translated to actual AS3 source code, this means:

Pay special attention to the part where we modify the obstacles sprite while iterating over it. If we hadn’t fixed the loop variables accordingly, this would have lead to an exception. That’s easy to overlook!

I know it’s been quite a while since we could actually run our application without an error. Bear with me — we are almost there!

All that’s left to do now is implementing the addObstacle method we just called. What exactly must this method achieve?

Finally, we can compile and start the game again! Do just that and give it a try.

This is starting to make fun, right? Don’t get overly confident if you feel invincible when playing the game, though: that’s probably because we didn’t implement collision detection yet. Oops!

In any case, as soon as you click once to start the game, the obstacles should start moving in from the right. When they move out on the left, they are automatically removed from the display list. Looking good!

The first step: check if the bird overlaps the vertical stripe made up by the obstacle, at all.

Remember, we centered the trunk images horizontally in the coordinate system of the Obstacle class. Furthermore, the bird’s pivot point is exactly at the center of its circular body. This pays off now: it allows us to directly use bird and obstacle coordinates for our checks.

We just subtract (or add) the radius from the current x coordinate of the obstacle to get to the left (or right) bounds. If the bird is outside this range, there cannot possibly be any collision with this obstacle, so we exit the method right away.

If the method is executed further, we know that the bird is horizontally within the obstacle bounds. This means that if the bird is too far up or down (above or below the semi-circular end pieces), there must be a collision.

On the other hand, if the bird is vertically in-between those two areas, we need to proceed to the final step.

Both the bird and the end pieces of the obstacle trunks are circular. The final step is to test if those circles intersect one another. Thankfully, the math to test if two circles intersect is rather simple:

A little geometry reminder: to calculate the distance vector between two points A and B, you simply subtract the coordinates of A from B:

To get the length of this vector, good old Pythagoras comes to the rescue:

We already know the center of the bird circle (birdX and birdY) and the positions of the end pieces (x and topY / bottomY). The remaining code simply needs to insert those values into the formulas from above.

That’s it! Our collision detection method is finished. Since it’s not called from anywhere yet, though, there is no change in gameplay yet.

We already have a method called checkForCollisions in the World class. Right now, it only checks if the bird hits the ground, but it was always destined for more! With the collision detection code prepared, it’s just a matter of iterating over our obstacles and testing each of them.

Now that was easy, wasn’t it? If you give the game a try now, you can reap the benefits of our hard work. The basic gameplay mechanisms are all in place!

Before we move on, I’d like to take care of one more thing, though. In the same method (checkForCollisions), please add the following code into the for loop (somewhere after assigning the obstacle variable).

The player’s score is going to be measured by the number of obstacles he manages to pass. The Game class is supposed to take care of that — so it needs to be notified whenever we pass an obstacle. That’s best done by dispatching an appropriate event.

In order to not count one obstacle twice, we are also enabling the passed property. If you wondered all along what that property was for, here is your answer!

In Starling, the TextField class is responsible for displaying text. It populates a rectangular area with the letters of a String — quite simple, actually.

Naturally, we first have to decide which font we want to use. Starling supports two types of fonts:

The advantage of TrueType Fonts is that they are very easy to use; however, changing the displayed text is somewhat expensive. For text that changes often, Bitmap Fonts are better suited. Besides, you can pre-bake them with decorations like outlines or color gradients, which is great for games like Flappy Bird.

If you look into the folder assets/fonts within our project, you’ll see that I already included one such bitmap font called "Brady Bunch". It is based on a TrueType font available on dafont.com (a great resource if you are looking for fancy fonts).

Just like all the other textures we have been using so far, this font is already loaded by the AssetManager by the code we used as our starting point. We can make use of it without any further preparations.

The TextFormat class is used to set up the exact style you want text to be rendered with. It goes hand in hand with the TextField class.

Open up the Game class (all edits in this section are done in this class) and add the following static definition to the top:

This TextFormat instance describes the font settings we want to use for the score label.

The Game class needs to display the score, but it also needs to keep track of it. That means that we have to add two member variables.

Creating the actual TextField is best done in the start method. Add the following setup code (e.g. right below the code that sets up the World instance).

We are now in a situation that deserves special attention: there are two member variables that are storing a representation of the current score (an Integer and a TextField). Those two objects must always be in sync: when you change one, you need to change the other.

I know myself: if I don’t take special measures right now, I’m bound to forget changing one of the two member variables some time in the future. To make sure that can’t happen, I recommend adding a property that takes care of any score changes. We can even make it private, since it’s only meant for internal use:

This lays the groundwork for our score display. All of this was done to be able to keep track of the player’s score — so let’s do just that!

Do you remember? Each time the bird passes an obstacle, the World class dispatches a suitable event. That’s our signal to increment the score.

We are almost ready. All that’s left to do is making the score label visible when the game starts, and hiding it after an error. This means some small modifications to existing methods.

Again, we finished a major stepping stone of our game production! Start the game to watch the score display in all its glory.

While the player now sees his current score while playing, the top score is not stored yet. As part of the title screen (which will be created in the next section), I’d like to display the current record. Let’s prepare that before moving on.

What’s special about the top score is that it should be persistent, i.e. it must outlive an application restart. Typically, this means we have to write the respective value into a file on the disk.

The ActionScript API provides a very flexible mechanism that does just that: the SharedObject. The advantage: it works both for AIR applications and within the Flash Player. Furthermore, it’s really easy to use.

Still in the Game class, create a new member variable and instantiate it in the constructor.

A local shared object is identified by a simple string (in this case, flappy-data). Contrary to what the name suggests, only the current application can access that object. Behind the scenes, the runtime saves its data in a local file.

You can think of a shared object as a persistent Dictionary object. To access the top score easily, we wrap access to this dictionary in a new property.

This is actually all we need for our data storage needs. Of course, we also have to make use of this property somewhere. The method onBirdCollided is a good candidate for that.

Easy, right?

Create a new class called TitleOverlay. Add the following contents:

This procedure starts to become second nature, right? You create a custom Sprite and add a number of display objects that make up its contents. You do that over and over when working with Starling.

So let’s create those three elements.

In the Game class, we create a member variable for our new TitleOverlay and instantiate it inside the start method.

When you start the game now, the overlay will already be visible. It just doesn’t go away when a game session starts, which is a little annoying.

Up until now, we didn’t bother where the game’s assets actually come from; we simply used what was available in the repository’s starting point. Now, for the first time, we need to add additional files.

Find the class EmbeddedAssets. It already contains several Embed statements that make sure that the textures and fonts are baked right into the SWF file during compilation. The sound files will join them! Add the following code:

The AssetManager will automatically pick up those new references and will make them available under the names "flap", "pass" and "crash".

All that’s left for us to do is to actually start playback at the appropriate times. Again, the Game class seems like the appropriate spot for that logic. The method onBirdCollided will trigger the crash sound.

Passing an obstacle triggers an appropriate event handler, as well — do you remember?

The flapping sound can be added to the onTouch event handler.

Note that we are starting the flap sound only when a touch occurs during PHASE_PLAYING. Otherwise, you would hear it also when the player touches the screen during the short time when we are waiting for the game to be reset (PHASE_CRASHED). It doesn’t make much sense in that phase.

Compile and run the game to make a proper sound check!

Believe it or not, this was the last missing piece of the Flappy Starling puzzle. The game is ready to be played and published!

Up until now, we only compiled in debug mode, i.e. we created a non-optimized SWF file including debug information. That’s super useful in the development phase, but not what you want for the actual release.

Whenever you want to test the performance of a game, or if you want to release it to the public, it’s important to make a release build. When using Starling, it makes a massive difference if a project is compiled in debug or release mode. Don’t draw any conclusions about performance if you are not running the code with the optimal settings and in the optimal environment!

Unfortunately, creating a release build is different in each IDE you use. Make sure to familiarize yourself with the process.

In the past, embedding Flash content inside a website could prove surprisingly difficult. Different browsers preferred different HTML elements and attributes; you needed to check if the user has a sufficient version of the Flash plugin installed, etc. Thus, most Flash developers used the JavaScript library SwfObject to work around these issues.

Today, the process has thankfully become a little easier; modern browsers essentially all support the object element to embed Flash content. Thus, I’m typically favoring that simple approach nowadays.

Let’s start with a basic HTML5 scaffold:

In the body element, embed the SWF file like this:

Save this file as index.html and store it in the same directory as the SWF file. You can now copy it to a web server or launch it right from your local disk.

While all the code we wrote so far was targeting the Flash plugin, it’s actually not much work to adapt the game for mobile devices. All the essential game code stays exactly the same; only the startup phase (when Starling is initialized and the assets are loaded) needs to be changed. Now it pays off that we didn’t hard-code any positions, but placed all objects relative to the stage size!

The main challenge of the mobile version is that most mobile screens have a much higher pixel density than typical desktop screens. For this reason, I prepared high resolution versions of all the game’s textures.

Depending on the device the game is running on, we need to load the correct set of textures. Furthermore, instead of embedding all the assets, the mobile version will load them from the disk. That way, only the assets we really need will end up in memory.

We will look in detail at how all this is done in the Mobile Development chapter. If you can’t wait any longer, though, simply check out the head revision of the Flappy Starling project on GitHub. It contains a new build target for mobile devices (iOS and Android).