The Starling Manual

The ByteArray class represents one of the lower level APIs available within the ActionScript core libraries. It allows to store data in a very efficient way, with total control over the actual bits of memory.

When working with the Stage3D API, this efficiency is very important. For example, the fastest way to upload data to the GPU is via byte arrays; thus, you’ll find them very often within the Starling source code.

If you have never used them before, here is a simple example. We are storing a couple of values and retrieving them afterwards:

You might have worked with streams in other programming languages; the ByteArray class works similar to those. There is a pointer to the current position, and whenever you read or write data, that pointer moves according to the data type. It’s your own responsibility not to read beyond the array’s current length.

Of course, for a simple list of numbers, we could also simply use an Array or a Vector. However, byte arrays have some advantages:

Thus, the class can be really useful in some situations. However, if the main reason to use it is to save memory, you need to be really careful: its memory management strategy is rather non-intuitive.

The support of touch input was arguably one of the main reasons for the success of the original iPhone back in 2007. Today, interacting with mobile phones with our fingers feels so natural that it’s hard to imagine it could ever have been different. Single- and multi-touch gestures have become second nature to most of us.

Since Starling applications can run on both desktop and mobile devices, it made sense to unify mouse and touch input. In both cases, you rely on the TouchEvent class, which works quite intuitively.

The TouchEvent and Touch classes provide all the information you need to handle any possible input. However, Starling does not have a concept of gestures or other high-level input events. You have to implement that yourself.

In the end, it’s really not very complicated, though. Below, I will guide you through the creation of a sprite that can be moved around, rotated, and scaled by the user.

First, make sure that multi-touch is enabled; without it, all but one finger will be ignored. During development, it’s also useful to enable the multi-touch simulation. That way, you can use the Ctrl / Cmd and Shift keys to simulate two touch points. A huge time saver!

As for the actual class, let’s make it a simple sprite that’s set up with a TouchEvent handler.

To work with this class, you will need to add some content, of course. Otherwise, there is nothing for the user to touch and move around. For example, you could add an image:

Aliasing is one of those annoying topics that always pop up once in a while when you deal with computer graphics. Shapes with mathematically exact bounds need to be approximated with the limited numbers of pixels on a computer screen — and that leads to jagged edges.

The problem has become less pressing in recent years, though, since the density of today’s screens has reached a very high level (especially on mobile). For some reason, however, the big screens of desktop computers follow suit only very slowly. Thus, it’s still important to be familiar with some strategies around this issue.

As a Starling user, you have several options.

We just saw that the FragmentFilter class can be used for selectively applying anti-aliasing to an object. Actually, for a class that doesn’t seem to do anything on first glance, there are a lot of creative ways to make use of it! I’d like to show you two more.

Many 2D games contain big maps, like the levels in a platformer or a territory of a real-time strategy title. Most of the time, those maps are assembled from lots and lots of small tiles — rectangular textures that can be seamlessly put next to each other.

The traditional approach to implement such a tilemap would be to simply use an Image instance for each tile. If you add all tiles to a single Sprite, you’ll have a handy and easy to use object representing the whole map.

That works well, and it’s even the preferred approach for small maps. It’s straight-forward, flexible, and comfortable to use.

Performance-wise, though, it’s not ideal. The flexibility of the display list comes at a price; when the number of tiles grows too big, performance will suffer.

However, Starling allows you to side-step the display list. You can create a single display object that’s composed of all your tiles but is rendered in a single step. The class that can pull this off is called MeshBatch.

When using the MeshBatch, think of it as an object similar to a RenderTexture. You can add ("draw") an almost endless number of other meshes to it (up to 16k quads). However, whereas the RenderTexture stores the pixels that are the result of this operation, the MeshBatch stores the actual geometry. Thus, a MeshBatch requires only very little memory, and adding additional geometry is much cheaper.

Enough theory: let’s look at how to create a big tilemap with the MeshBatch class.

What may be surprising about this code is that a single Image instance (tile) is added to the MeshBatch over and over. You couldn’t do that with a regular container (e.g. a Sprite): it can pick up a single image once and only once.

When you add an object to a MeshBatch, its geometry and other properties are simply copied over; the object acts only as a blueprint or stamp. That’s exactly what distinguishes this class.

You probably won’t be shocked to hear that this performance benefit comes at a price, and that’s a set of rather strict limitations.

All in all, the MeshBatch is not the silver bullet for all performance-problems, but it’s a great tool for very specific use-cases. For example, Starling uses them internally for bitmap fonts.

If you followed the last section and just created your tilemap, you might have run into a problem: in some situations, the tile edges become visible. Like here:

It doesn’t seem to make any sense, because you perfectly aligned the objects next to each other, and each tile ends with the same flat color. Still, in some moments, the edges become visible — how can that be?

That’s an issue you will run into with almost all GPU-powered graphics engines. To get to the root of the problem, let’s look at the edge of a single tile in great magnification. We should also turn off textureSmoothing.

On the left, you see a corner of the magnified tile with texture smoothing disabled, making the actual pixel bounds visible. On the right, the same corner is drawn with the default texture smoothing (BILINEAR). The actual pixel bounds are highlighted with a grid.

As you can see, the further you get to the edges, the brighter the pixels become. That’s exactly the reason our tiles do not line up seamlessly! Where is that light green color coming from?

By default, Starling uses "bilinear filtering" for all texture lookups. That means that each time the GPU samples a texture, it takes four of its pixels into account.

For example, in the corner area, each texture lookup will combine all texels marked with "×". This means that we are actually reaching beyond the bounds of the tile! Since the tile was probably taken from a texture atlas, we’re talking about empty space or even adjacent tiles.

Don’t think that you’re safe if you don’t magnify the tiles, by the way. If the tiles are not perfectly aligned with the screen pixels, the same problem will occur.

However, now that we know what’s causing the problem, we can do something about it. Here are a few workarounds that will fix your tile maps.

That should do it!

When an app or game uses just a moderate number of textures, you can load everything at launch (maybe while showing a short loading animation). Often, though, the size and amount of textures will be too big to fit everything into memory simultaneously. In that case, you have to load textures on demand, right when you need them.

The problem: by default, loading happens synchronously, causing a hiccup while the texture is being uploaded to graphics memory. Especially when the texture is big (think: texture atlas), that pause will be noticeable.

The solution is to load textures asynchronously instead. That way, the runtime will create the texture in a separate thread, leaving Starling in a responsive state.

As discussed in previous chapters, the ATF format provides a practical way to reduce the memory consumption of your assets. Typically, you create the ATF files during the build process of your game and then load them at runtime. What’s not so well known is that you can also create compressed textures at runtime — albeit only on desktop platforms (at the time of this writing).

Most of the time, you will still want to compress your textures beforehand — simply because it is faster and allows for more control. In some situations, on the other hand, this feature can turn out really useful, e.g. when creating textures dynamically from vector art.

Here is a source code sample showing how it’s done.

Quite simple, right? The parameter that’s interesting is the last one; for compressed textures, you can choose between the format COMPRESSED and COMPRESSED_ALPHA. As the names suggests, only the latter will include an alpha channel.

I couldn’t find any information about the actual format that is used for the compression, but it’s likely to be either DXT1 (no alpha) or DXT5 (alpha), since those are available on all desktop computers.

You are probably using the AssetManager to load your textures, right? In that case, you can activate texture compression by simply assigning the appropriate format before enqueuing:

If you wonder how long the compression takes, fear not: it’s definitely within an acceptable range. I made some tests with a MacBook Pro from 2015, which compressed a 2048×2048 texture in less than 100 milliseconds. Even on a low-end Windows Netbook, the process took only about 300 milliseconds. For the occasional dynamic utility texture, that will do!

Starling’s AssetManager includes support for all the asset types needed in a typical app, like textures, sounds, JSON data — you name it. However, it also allows adding your own asset types — after all, every project is different.

Let’s look at a real life example.

Per default, the AssetManager throws the BitmapData of all textures away after loading — to save memory. Sometimes, however, you need this data, e.g. to be able to look up individual pixels of a texture. So let’s create a custom AssetManager that

Most games count the player’s score in some way. By awarding points, the player gets a sense of achievement and progress; add a leader board, and players can compete with each other.

To keep the player informed about the current score, there is probably a TextField somewhere on the stage. When the score changes, some code similar to the following will be executed:

That works, but it’s also a little dull. Since the score changes in an instant, it’s likely that the player does not even notice the change.

If the score would be raised in small steps, over the course of (say) a second, the change would be much more gratifying. The player could literally watch the additional points appear on the counter. But how best to achieve that?

The easiest way to animate things in Starling is, of course, to use a tween. A tween, however, can only animate numerical properties; that rules out the text property (a String), right?

Well, not necessarily! All we have to do is create a numeric property that wraps the String access internally. For example, you could add the following property to the sprite containing the TextField:

Now we do have a numeric property, and it can be animated just like any other.

This code raises the score in small steps over the course of a second, until it settles on the new value. That’s just what we wanted, and a quick test shows that it looks really neat (especially considering the little effort it took).

You need to be aware, though, that this code may cause a subtle problem when score changes occur in quick succession.

Let’s say the player scored 100 points, and you already started a tween that raises the player’s score from 0 to 100. Now, what happens if the player scores another 100 points before that animation is finished?

Instead of a score of 200, we end up with a score of just 187! To avoid such side effects, it’s better to separate the score that’s currently displayed from the one that actually counts. My recommendation is to create a property like the following instead:

That way, you can access the actual score (this.score) separately from the one that’s currently displayed (this.displayedScore). With that strategy, you won’t run into any problems.

In the early years of the Internet, many web developers — frustrated by the limitations of early HTML — used Flash simply to show off. Even if the website itself didn’t have much content, you could be sure there was a Flash intro and some kind of animated reflection effect. Anybody with a tiny bit of self respect simply had to do it!

Thankfully, those days are long over. Nevertheless, a part of me still likes eye-candy like that. If used with care, an unobtrusive reflection might be turned into a nice special effect. So let’s look at how this can be achieved with Starling.

Are there any Super Mario fans around? I’ve been fascinated with this game series since I was a child. I must have spent hundreds of hours in the Mushroom Kingdom; I don’t think I skipped any of the major games.

The first time I played "Super Mario World" on the Super NES, with its huge, colorful sprites and bold sound effects — that was probably one of the defining moments leading to my current career. In general, the Super NES featured special effects that were ahead of its time. For example, there was a particular type of transition: the complete screen became gradually pixelated and normal again, concealing an underlying change of the scenery.

When I recently saw that again, I wondered: can this effect be reproduced in Starling? That’s what we are going to try in this section.

Here’s the battle plan:

Whenever you read "render a display object into a texture", a bell should start ringing in your head, reminding you of the FragmentFilter class. That kind of task is exactly what filters are doing very efficiently. Actually, we already used them for rendering in a very high resolution (see Anti-Aliasing Strategies); now we are going to do the opposite: rendering in a very low resolution.

The resolution into which a FragmentFilter renders the filtered object is determined by a property with the same name. A value of 1 will use the full pixel density of the screen; a value of 0.5 just half of that, etc. That property is the key to making this effect possible.

As a first test, assign a FragmentFilter to a display object and animate its resolution property. Like this:

That works, but somehow it doesn’t look all that great in practice. Somehow, the animation spends too much time with small pixels and shows big pixels only very briefly.

We can mitigate that by changing the transition type. Add the following key-value pair to the tween setup:

That’s much better!

Granted: this is not a real transition yet — we just temporarily altered the appearance of an object. What we actually need to do is change the object halfway through the animation (when the pixels are biggest). Furthermore, when the transition is finished, we need to remove and dispose the filter.

That’s easily done via the callbacks offered by the Tween class.

That does the trick!

We already learned about two techniques to add outlines to fonts:

Unfortunately, both of those techniques are not an option for TextFields using TrueType fonts. However, there is a way to add an outline at runtime to any kind of object: by "abusing" the GlowFilter slightly.

The trick is to use an alpha-value that’s higher than 1.0; much higher, in fact. The GlowFilter is implemented in a way that when alpha exceeds 1.0, it acts as a strength-multiplier, making the edges of the glow harder.

For example, to add a black outline to an object, set up the filter like this:

For reference, these are the arguments used in that sample:

The result looks like this:

Of course, that works not just for TextFields, but for any kind of display object.

Before I started working full-time for my own company, I spent several years developing casual games for coin-operated gaming terminals. Believe me, I created my share of card games!

A typical requirement in a card game: flipping cards around. Starling’s Sprite3D class is the perfect tool for this job, as it makes the cards literally pop out of the screen. It was created exactly with such simple effects in mind.

To flip a Sprite3D around, you simply animate rotationX or rotationY, like this:

There is only one problem: the back of the card looks just like the front, except that it’s mirrored. How can we change the way the card looks from behind?

I will show you two ways to achieve this result; both are educational in their own way.

The first step, for both approaches, is to create a custom class that inherits from Sprite3D. Only a Sprite3D can be rotated in a 3D space, so this shouldn’t come as a surprise. It will contain both front and back side.

That code is mostly straight-forward; the only thing that might come as a surprise is that the back side is flipped. When you think it through, though, it makes perfect sense: the back side must be facing in the opposite direction as the front.

Now we need to decide which of the two sides is visible at any given moment.

As we explored Starling’s event system, I mentioned that the Event class contains a data property that may take up any kind of object or primitive data type. The contents of that property is then passed to an optional second parameter of the event handler.

It’s not very well documented, but most of Starling’s standard events make use of this property. This means that you often have direct access to the data you need, allowing you to simplify your event handlers slightly.

For example, in an EnterFrameEvent, you typically want to know the time that has passed since the previous frame. To do this, you can either use the property on the respective event:

Or you can let Starling populate the second parameter with the passed time.

Note that I didn’t even declare the first parameter as EnterFrameEvent; I don’t need any specific data from that object, so why bother? Here are all the data-shortcuts provided by Starling’s standard events:

In previous Starling versions, the KeyboardEvent was dispatched to all display objects. While this was very convenient, it also caused some performance issues — thus, this behavior was changed in Starling 2. Keyboard events are now only dispatched to the stage.

When you listen to an event on the stage, you need to be a little careful: you have to make sure that you remove the handler when you do not need it any longer. After all, the stage exists for the complete lifetime of the application; any event handlers on it will be kept in memory for all that time.

My recommendation: make a detour over the ADDED_TO_STAGE and REMOVED_FROM_STAGE event handlers when listening for keyboard input. A small helper method can automate the process.

Using this method, you can add a perfectly safe KeyboardEvent handler to an object like this:

That way, it’s guaranteed that the event listener doesn’t stay around longer than needed. It is only active as long as it’s part of the display list.

Of course, a similar approach can be taken for all kinds of events dispatched by the stage or any other independent object.

The Transitions class contains some standard easing functions to be used by Tweens, e.g. the standard EASE_IN / EASE_OUT or its elastic our bouncing alternatives. But did you know that you can set up your own transition methods, too?

That way, you can add more fine-grained easing equations (like quadratic or sine transitions, for example). You can even bend the whole system to your needs — who says that a tween must really end at the provided endpoint?

For example, it’s sometimes useful to highlight a button or icon by letting it jump up ("Pick me! Pick me!"). That can be implemented via a custom jump transition.

A transition method contains just one parameter: ratio. It indicates the current position within the tween and ranges from zero (animation start) to one (animation end).

The return value will tell the tween if the animated property should remain at the start value (0), the end value (1), or something in between. For example, a value of 0.5 would indicate the exact midpoint between start and end value.

For our jump animation, we simply forward ratio * π to the sine function; that will yield a simple up-and-down movement. That transition function only needs to be registered once, e.g. during application startup. With that in place, the following code lets an object jump up 100 points before falling down to its original position:

Handy, right?

While you’re at it, also check out the new BezierEasing class that was introduced in Starling 2.5. Just like its CSS sibling cubic-bezier (which web developers might recognize), it makes it really easy to create custom transitions. Use a visual tool like cubic-bezier.com or Ceaser to draw your curve; then pass the four coordinates to the new BezierEasing.create() method.

Do you want to mimic the exact easing functions used by CSS animations? BezierEasing makes it possible.

Also, if you’re creating an app that follows Google’s Material Design System, you can make sure that your tweens behave exactly as recommended. You just need to set up the appropriate transitions like this:

Since Starling 2, the difference between Quad and Image is more subtle than in the past. Previously, if you needed just a color or gradient, you used Quad; if you needed a texture, you used Image. Now, however, a Quad can be textured just the same. Thus, you actually don’t need the Image class very often.

The following two lines of code are almost equivalent:

Why is there even an Image class then? To be honest: mostly for backwards compatibility. I didn’t want to burden all Starling developers with having to exchange all of their Image instances when upgrading to version 2!

The new Image class can do more, though, as it contains two useful new properties.

You are probably wondering: when you don’t need those features, should you use Quad or Image? If you are looking for maximum efficiency, the answer is Quad, since it’s a little more lightweight.

On the other hand, the difference is so small that it will be hard to measure. Personally, I’m still sticking to Image most of the time — it’s hard to get rid of old habits, right?