The Starling Manual

Stage3D provides Starling with a rectangular area to draw into. That area can be anywhere within the native stage, which means: anywhere within the area of the Flash Player or the application window (in case of an AIR project).

In Starling, that area is called the viewPort. Most of the time, you will want to use all of the available area, but sometimes it makes sense to limit rendering to a certain region.

Think of a game designed in an aspect ratio of 4:3, running on a 16:9 screen. By centering the 4:3 viewPort on the screen, you will end up with a "letterboxed" game, with black bars at the left and right.

You can’t talk about the viewPort without looking at Starling’s stage, as well. By default, the stage will be exactly the same size as the viewPort. That makes a lot of sense, of course: a device with a display size of 1024 × 768 pixels should have an equally sized stage.

You can customize the stage size, though. That’s possible via the stage.stageWidth and stage.stageHeight properties:

But wait, what does that even mean? Is the size of the drawing area now defined by the viewPort or the stage size?

Don’t worry, that area is still only set up by the viewPort, as described above. Modifying the stageWidth and stageHeight doesn’t change the size of the drawing area at all; the stage is always stretched across the complete viewPort. What you are changing, though, is the size of the stage’s coordinate system.

That means that with a stage width of 1024, an object with an x-coordinate of 1000 will be close to the right edge of the stage; no matter if the viewPort is 512, 1024, or 2048 pixels wide.

That becomes especially useful when developing for HiDPI screens. For example, Apple’s iPad exists in a normal and a "retina" version, the latter doubling the number of pixel rows and columns (yielding four times as many pixels). On such a screen, the interface elements should not become smaller; instead, they should be rendered more crisply.

By differentiating between the viewPort and the stage size, this is easily reproduced in Starling. On both device types, the stage size will be 1024×768; the viewPort, on the other hand, will reflect the size of the screen in pixels. The advantage: you can use the same coordinates for your display objects, regardless of the device on which the application is running.

To find out the actual width (in pixels) of a point, you can simply divide viewPort.width by stage.stageWidth. Or you use Starling’s contentScaleFactor property, which does just that.

I will show you how to make full use of this concept in the Mobile Development chapter.

The platforms Starling is running on feature a wide variety of graphics processors. Of course, those GPUs have different capabilities. The question is: how to differentiate between those capabilities at runtime?

That’s what Context3D profiles (also called render profiles) are for.

Actually, Starling makes every effort to hide any profile limitations from you. To ensure the widest possible reach, it was designed to work even with the lowest available profile. At the same time, when running in a higher profile, it will automatically make best use of it.

Nevertheless, it might prove useful to know about their basic features. Here’s an overview of each profile, starting with the lowest.

My recommendation: simply let Starling pick the best available profile (auto) and let it deal with the implications.

The main idea behind Starling is to speed up rendering with its Stage3D driven API. However, there’s no denying it: the classic display list has many features that Starling simply can’t offer. Thus, it makes sense to provide an easy way to mix-and-match features of Starling and classic Flash.

The nativeOverlay property is the easiest way to do so. That’s a conventional flash.display.Sprite that lies directly on top of Starling, taking viewPort and contentScaleFactor into account. If you need to use conventional Flash objects, add them to this overlay.

Beware, though, that conventional Flash content on top of Stage3D can lead to performance penalties on some (mobile) platforms. For that reason, always remove all objects from the overlay when you don’t need them any longer.

It happens surprisingly often in an application or game that a scene stays completely static for several frames. The application might be presenting a static screen or wait for user input, for example. So why redraw the stage at all in those situations?

That’s exactly the point of the skipUnchangedFrames property. If enabled, static scenes are recognized as such and the back buffer is simply left as it is. On a mobile device, the impact of this feature can’t be overestimated. There’s simply no better way to enhance battery life!

I’m already hearing your objection: if this feature is so useful, why isn’t it activated by default? There must be a catch, right?

Indeed, there is: it doesn’t work well with Render- and VideoTextures. Changes in those textures simply won’t show up. It’s easy to work around that, though: either disable skipUnchangedFrames temporarily while using them, or call stage.setRequiresRedraw() whenever their content changes.

Now that you know about this feature, make it a habit to always activate it! In the meantime, I hope that I can solve the mentioned problems in a future Starling version.

When developing an application, you want as much information as possible about what’s going on. That way, you will be able to spot problems early and maybe avoid running into a dead end later. The statistics display helps with that.

What’s the meaning of those values?

You might notice that the background color of the statistics display alternates between black and dark green. That’s a subtle clue that’s referring to the skipUnchangedFrames property: whenever the majority of the last couple of frames could be skipped, the box turns green. Make sure that it stays green whenever the stage is static; if it doesn’t, some logic is preventing frame skipping to kick in.

All elements that appear on screen are types of display objects. The starling.display package includes the abstract DisplayObject class; it provides the basis for a number of different types of display objects, such as images, movie clips, and text fields, to name just a few.

The DisplayObject class provides the methods and properties that all display objects share. For example, the following properties are used to configure an object’s location on the screen:

Other properties modify the way the pixels appear on the screen:

Those are the basics that every display object must support. Let’s look at the class hierarchy around this area of Starling’s API:

You’ll notice that the diagram is split up in two main sub-branches. On the one side, there are a couple of classes that extend Mesh: Quad, Image, and MovieClip.

Meshes are a fundamental part of Starling’s rendering architecture. Everything that is drawn to the screen is a mesh, actually! Stage3D cannot draw anything but triangles, and a mesh is nothing else than a list of points that spawn up triangles.

On the other side, you’ll find a couple of classes that extend DisplayObjectContainer. As its name suggests, this class acts as a container for other display objects. It makes it possible to organize display objects into a logical system — the display list.

The hierarchy of all display objects that will be rendered is called the display list. The Stage makes up the root of the display list. Think of it as the literal "stage": your users (the audience) will only see objects (actors) that have entered the stage. When you start Starling, the stage will be created automatically for you. Everything that’s connected to the stage (directly or indirectly) will be rendered.

When I say "connected to", I mean that there needs to be a parent-child relationship. To make an object appear on the screen, you make it the child of the stage, or any other DisplayObjectContainer that’s connected to the stage.

The first (and, typically: only) child of the stage is the application root: that’s the class you pass to the Starling constructor. Just like the stage, it’s probably going to be a DisplayObjectContainer. That’s where you take over!

You will create containers, which in turn will contain other containers, and meshes (e.g. images). In the display list, those meshes make up the leaves: they cannot have any child objects.

Since all of this sounds very abstract, let’s look at a concrete example: a speech bubble. To create a speech bubble, you will need an image (for the bubble), and some text (for its contents).

Those two objects should act as one: when moved, both image and text should follow along. The same applies for changes in size, scaling, rotation, etc. That can be achieved by grouping those objects inside a very lightweight DisplayObjectContainer: the Sprite.

So, to group text and image together, you create a sprite and add text and image as children:

The order in which you add the children is important — they are placed like layers on top of each other. Here, textField will appear in front of image.

Now that those objects are grouped together, you can work with the sprite just as if it was just one object.

In fact, DisplayObjectContainer defines many methods that help you manipulate its children:

Every display object has its own coordinate system. The x and y properties, for example, are not given in screen coordinates: they are always depending on the current coordinate system. That coordinate system, in turn, is depending on your position within the display list hierarchy.

To visualize this, imagine pinning sheets of paper onto a pinboard. Each sheet represents a coordinate system with a horizontal x-axis and a vertical y-axis. The position you stick the pin through is the root of the coordinate system.

Now, when you rotate the sheet of paper, everything that is drawn onto it (e.g. image and text) will rotate with it — as do the x- and y-axes. However, the root of the coordinate system (the pin) stays where it is.

The position of the pin therefore represents the point the x- and y-coordinates of the sheet are pointing at, relative to the parent coordinate system (= the pin-board).

Keep the analogy with the pin-board in mind when you create your display hierarchy. This is a very important concept you need to understand when working with Starling.

I mentioned this already: when you create an application, you split it up into logical parts. A simple game of chess might contain the board, the pieces, a pause button and a message box. All those elements will be displayed on the screen — thus, each will be represented by a class derived from DisplayObject.

Take a simple message box as an example.

That’s actually quite similar to the speech bubble we just created; in addition to the background image and text, it also contains two buttons.

This time, instead of just grouping the object together in a sprite, we want to encapsulate it into a convenient class that hides any implementation details.

To achieve this, we create a new class that inherits from DisplayObjectContainer. In its constructor, we create everything that makes up the message box:

Now you have a simple class that contains a background image, two buttons and some text. To use it, just create an instance of MessageBox and add it to the display tree:

You can add additional methods to the class (like fadeIn and fadeOut), and code that is triggered when the user clicks one of those buttons. This is done using Starling’s event mechanism, which is shown in a later chapter.

When you don’t want an object to be displayed any longer, you simply remove it from its parent, e.g. by calling removeFromParent(). The object will still be around, of course, and you can add it to another display object, if you want. Oftentimes, however, the object has outlived its usefulness. In that case, it’s a good practice to call its dispose method.

When you dispose display objects, they will free up all the resources that they have allocated. That’s important, because many Stage3D related data is not reachable by the garbage collector. When you don’t dispose that data, it will stay in memory, which means that the app will sooner or later run out of resources and crash.

To make things easier, removeFromParent() optionally accepts a Boolean parameter to dispose the DisplayObject that is being removed. That way, the code from above can be simplified to this single line:

Pivot Points are a feature you won’t find in the traditional display list. In Starling, display objects contain two additional properties: pivotX and pivotY. The pivot point of an object (also known as origin, root or anchor) defines the root of its coordinate system.

Per default, the pivot point is at (0, 0); in an image, that is the top left position. Most of the time, this is just fine. Sometimes, however, you want to have it at a different position — e.g. when you want to rotate an image around its center.

Without a pivot point, you’d have to wrap the object inside a container sprite in order to do that:

Most long-time Flash developers will know this trick; it was needed quite regularly. One might argue, however, that it’s a lot of code for such a simple thing. With the pivot point, the code is reduced to the following:

No more container sprite is needed! To stick with the analogy used in previous chapters: the pivot point defines the position where you stab the pin through the object when you attach it to its parent. The code above moves the pivot point to the center of the object.

Now that you have learned how to control the pivot point coordinates individually, let’s take a look at the method alignPivot(). It allows us to move the pivot point to the center of the object with just one line of code:

Handy huh?

Furthermore, if we want the pivot point somewhere else (say, at the bottom right), we can optionally pass alignment arguments to the method:

That code rotates the object around the bottom right corner of the image.

A texture is just the data that describes an image — like the file that is saved on your digital camera. You can’t show anybody that file alone: it’s all zeros and ones, after all. You need an image viewer to look at it, or send it to a printer.

Textures are stored directly in GPU memory, which means that they can be accessed very efficiently during rendering. They are typically either created from an embedded class or loaded from a file. You can pick between one of the following file formats:

The starling.textures.Texture class contains a number of factory methods used to instantiate textures. Here are few of them (for clarity, I omitted the arguments).

Probably the most common task is to create a texture from a bitmap. That couldn’t be easier:

It’s also very common to create a texture from an embedded bitmap. That can be done in just the same way:

However, there is a shortcut that simplifies this further:

Another feature of the Texture class is hidden in the inconspicuous fromTexture method. It allows you to set up a texture that points to an area within another texture.

What makes this so useful is the fact that no pixels are copied in this process. Instead, the created SubTexture stores just a reference to its parent texture. That’s extremely efficient!

Shortly, you will get to know the TextureAtlas class; it’s basically built exactly around this feature.

We’ve got a couple of textures now, but we still don’t know how to display it on the screen. The easiest way to do that is by using the Image class or one of its cousins.

Let’s zoom in on that part of the family tree.

While all of these classes are equipped to handle textures, you will probably work with the Image class most often. That’s simply because rectangular textures are the most common, and the Image class is the most convenient way to work with them.

To demonstrate, let me show you how to display a texture with a Quad vs. an Image.

Personally, I’d always pick the approach that saves me more keystrokes. What’s happening behind the scenes is exactly the same in both cases, though.

It’s important to note that a texture can be mapped to any number of images (meshes). In fact, that’s exactly what you should do: load a texture only once and then reuse it across the lifetime of your application.

Almost all your memory usage will come from textures; you will quickly run out of RAM if you waste texture memory.

In all the previous samples, we loaded each texture separately. However, real applications should actually not do that. Here’s why.

By using a texture atlas, you avoid both the texture switches and the power-of-two limitation. All textures are within one big "super-texture", and Starling takes care that the correct part of this texture is displayed.

The trick is to have Stage3D use this big texture instead of the small ones, and to map only a part of it to each quad that is rendered. This will lead to a very efficient memory usage, wasting as little space as possible. (Some other frameworks call this feature Sprite Sheets.)

The RenderTexture class allows creating textures dynamically. Think of it as a canvas on which you can paint any display object.

After creating a render texture, just call the drawObject method to render an object directly onto the texture. The object will be drawn onto the texture at its current position, adhering its current rotation, scale and alpha properties.

Drawing is done very efficiently, as it is happening directly in graphics memory. After you have drawn objects onto the texture, the performance will be just like that of a normal texture — no matter how many objects you have drawn.

If you draw lots of objects at once, it is recommended to bundle the drawing calls in a block via the drawBundled method, as shown below. This allows Starling to skip a few rather costly operations, speeding up the process immensely.

You can use any display object like an eraser by setting its blend mode to BlendMode.ERASE. That way, you can selectively remove parts of the texture.

To wipe it completely clean, use the clear method.

Starling makes it easy to display dynamic text. The TextField class should be quite self explanatory!

Once created, you can use a TextField just like you’d use an image or quad.

Per default, Starling will use system fonts to render text. For example, if you set up your TextField to use "Arial", it will use the one installed on the system (if it is).

However, the rendering quality of that approach is not optimal; for example, the font might be rendered without anti-aliasing.

For a better output, you should embed your TrueType fonts directly into the SWF file. Use the following code to do that:

After embedding the font, any TextField that is set up with a corresponding font name (font family) and weight will use it automatically. There’s nothing else to set up or configure.

Using TrueType fonts as shown above is adequate for text that does not change very often. However, if your TextField constantly changes its contents, or if you want to display a fancy font that’s not available in TrueType format, you should use a bitmap font instead.

A bitmap font is a texture containing all the characters you want to display. Similar to a TextureAtlas, an XML file stores the positions of the glyphs inside the texture.

This is all Starling needs to render bitmap fonts. To create the necessary files, there are several options:

The tools are all similar to use, allowing you to pick one of your system fonts and optionally apply some special effects. On export, there are a few things to consider:

The result is a .fnt file and an associated texture containing the characters.

To make such a font available to Starling, you can embed it in the SWF and register it at the TextField class.

Once the bitmap font instance has been registered at the TextField class, you don’t need it any longer. Starling will simply pick up that font when it encounters a TextField that uses a font with that name. Like here:

The event mechanism is a key feature of Starling’s architecture. In a nutshell, events allow objects to communicate with each other.

You might think: we already have a mechanism for that — methods! That’s true, but methods only work in one direction. For example, look at a MessageBox that contains a Button.

The message box owns the button, so it can use its methods and properties, e.g.

The Button instance, on the other hand, does not own a reference to the message box. After all, a button can be used by any component — it’s totally independent of the MessageBox class. That’s a good thing, because otherwise, you could only use buttons inside message boxes, and nowhere else. Ugh!

Still: the button is there for a reason — if triggered, it needs to tell somebody about it! In other words: the button needs to be able to send messages to its owner, whoever that is.

I have something to confess: when I showed you the class hierarchy of Starling’s display objects, I omitted the actual base class: EventDispatcher.

This class equips all display objects with the means to dispatch and handle events. It’s not a coincidence that all display objects inherit from EventDispatcher; in Starling, the event system is tightly integrated with the display list. This has some advantages we will see later.

Events are best described by looking at an example.

Imagine for a moment that you’ve got a dog; let’s call him Einstein. Several times each day, Einstein will indicate to you that he wants to go out for a walk. He does so by barking.

You just saw the three main components of the event mechanism:

From time to time, your aunt takes care of the dog. When that happens, you don’t mind if the dog barks — your aunt knows what she signed up for! So you remove the event listener, which is a good practice not only for dog owners, but also for Starling developers.

So much for the bark event. Of course, Einstein could dispatch several different event types, for example howl or growl events. It’s recommended to store such strings in static constants, e.g. right in the Dog class.

Starling predefines several very useful event types right in the Event class. Here’s a selection of the most popular ones:

Dogs bark for different reasons, right? Einstein might indicate that he wants to pee, or that he is hungry. It might also be a way to tell a cat that it’s high time to make an exit.

Dog people will probably hear the difference (I’m a cat person; I won’t). That’s because smart dogs set up a BarkEvent that stores their intent.

The dog can now use this custom event when barking:

That way, any dog owners familiar with the BarkEvent will finally be able to truly understand their dog. Quite an accomplishment!

Agreed: it’s a little cumbersome to create that extra class just to be able to pass on that reason string. After all, it’s very often just a single piece of information we are interested in. Having to create additional classes for such a simple mechanism feels somewhat inefficient.

That’s why you won’t actually need the subclass-approach very often. Instead, you can make use of the data property of the Event class, which can store arbitrary references (its type: Object).

Replace the BarkEvent logic with this:

The downside of this approach is that we lose some type-safety. But in my opinion, I’d rather have that cast to String than implement a complete class.

Furthermore, Starling has a few shortcuts that simplify this code further! Look at this:

We got rid of quite an amount of boiler plate code that way! Of course, you can use the same mechanism even if you don’t need any custom data. Let’s look at the most simple event interaction possible:

In our previous examples, the event dispatcher and the event listener were directly connected via the addEventListener method. But sometimes, that’s not what you want.

Let’s say you created a complex game with a deep display list. Somewhere in the branches of this list, Einstein (the protagonist-dog of this game) ran into a trap. He howls in pain, and in his final breaths, dispatches a GAME_OVER event.

Unfortunately, this information is needed far up the display list, in the game’s root class. On such an event, it typically resets the level and returns the dog to its last save point. It would be really cumbersome to hand this event up from the dog over numerous display objects until it reaches the game root.

That’s a very common requirement — and the reason why events support something that is called bubbling.

Imagine a real tree (it’s your display list) and turn it around by 180 degrees, so that the trunk points upwards. The trunk, that’s your stage, and the leaves of the tree are your display objects. Now, if a leaf creates a bubbling event, that event will move upwards just like the bubbles in a glass of soda, traveling from branch to branch (from parent to parent) until it finally reaches the trunk.

Any display object along this route can listen to this event. It can even pop the bubble and stop it from traveling further. All that is required to do that is to set the bubbles property of an event to true.

Anywhere along its path, you can listen to this event, e.g. on the dog, its parent, or the stage:

This feature comes in handy in numerous situations; especially when it comes to user input via mouse or touch screen.

While typical desktop computers are controlled with a mouse, most mobile devices, like smartphones or tablets, are controlled with your fingers.

Starling unifies those input methods and treats all "pointing-device" input as TouchEvent. That way, you don’t have to care about the actual input method your game is controlled with. Whether the input device is a mouse, a stylus, or a finger: Starling will always dispatch touch events.

First things first: if you want to support multitouch, make sure to enable it before you create your Starling instance.

Note the property simulateMultitouch. If you enable it, you can simulate multitouch input with your mouse on your development computer. Press and hold the Ctrl or Cmd keys (Windows or Mac) when you move the mouse cursor around to try it out. Add Shift to change the way the alternative cursor is moving.

To react to touch events (real or simulated), you need to listen for events of the type TouchEvent.TOUCH.

You might have noticed that I’ve just added the event listener to a Sprite instance. Sprite, however, is a container class; it doesn’t have any tangible surface itself. Is it even possible to touch it, then?

Yes, it is — thanks to bubbling.

To understand that, think back to the MessageBox class we created a while ago. When the user clicks on its text field, anybody listening to touches on the text field must be notified — so far, so obvious. But the same is true for somebody listening for touch events on the message box itself; the text field is part of the message box, after all. Even if somebody listens to touch events on the stage, he should be notified. Touching any object in the display list means touching the stage!

Thanks to bubbling events, Starling can easily represent this type of interaction. When it detects a touch on the screen, it figures out which leaf object was touched. It creates a TouchEvent and dispatches it on that object. From there, it will bubble up along the display list.

In some game engines, you have what is called a run-loop. That’s an endless loop which constantly updates all elements of the scene.

In Starling, due to the display list architecture, such a run loop would not make much sense. You separated your game into numerous different custom display objects, and each should know for itself what to do when some time has passed.

That’s exactly the point of the EnterFrameEvent: allowing a display object to update itself over time. Every frame, that event is dispatched to all display objects that are part of the display list. Here is how you use it:

The method onEnterFrame is called once per frame, and it’s passed along the exact time that has elapsed since the previous frame. With that information, you can move your enemies, update the height of the sun, or do whatever else is needed.

The power behind this event is that you can do completely different things each time it occurs. You can dynamically react to the current state of the game.

For example, you could let an enemy take one step towards the player; a simple form of enemy AI, if you will!

Now to predefined animations. They are very common and have names such as movement, scale, fade, etc. Starling’s approach on these kinds of animations is simple — but at the same time very flexible. Basically, you can animate any property of any object, as long as it is numeric (Number, int, uint). Those animations are described in an object called Tween.

Enough theory, let’s go for an example:

This tween describes an animation that moves the ball object to x = 20, scales it to twice its size and reduces its opacity until it is invisible. All those changes will be carried out simultaneously over the course of half a second. The start values are simply the current values of the specified properties.

This sample showed us that

Apropos: since scaling, fading and movement are done so frequently, the Tween class provides specific methods for that, too. So you can write the following instead:

An interesting aspect of tweens is that you can change the way the animation is executed, e.g. letting it start slow and get faster over time. That’s done by specifying a transition type.

The following example shows how to specify such a transition and introduces a few more tricks the class is capable of.

We just created and configured a tween — but nothing is happening yet. A tween object describes the animation, but it does not execute it.

You could do that manually via the tweens advanceTime method:

Hm, that works, but it’s a little cumbersome, isn’t it? Granted, one could call advanceTime in an ENTER_FRAME event handler, but still: as soon as you’ve got more than one animation, it’s bound to become tedious.

Don’t worry: I know just the guy for you. He’s really good at handling such things.

The juggler accepts and executes any number of animatable objects. Like any true artist, it will tenaciously pursue its true passion, which is: continuously calling advanceTime on everything you throw at it.

There is always a default juggler available on the active Starling instance. The easiest way to execute an animation is through the line below — just add the animation (tween) to the default juggler and you are done.

When the tween has finished, it will be thrown away automatically. In many cases, that simple approach will be all you need!

In other cases, though, you need a little more control. Let’s say your stage contains a game area where the main action takes place. When the user clicks on the pause button, you want to pause the game and show an animated message box, maybe providing an option to return to the menu.

When that happens, the game should freeze completely: none of its animations should be advanced any longer. The problem: the message box itself uses some animations too, so we can’t just stop the default juggler.

In such a case, it makes sense to give the game area its own juggler. As soon as the exit button is pressed, this juggler should just stop animating anything. The game will freeze in its current state, while the message box (which uses the default juggler, or maybe another one) animates just fine.

When you create a custom juggler, all you have to do is call its advanceTime method in every frame. I recommend using jugglers the following way:

That way, you have neatly separated the animations of the game and the message box.

By the way: the juggler is not restricted to Tweens. As soon as a class implements the IAnimatable interface, you can add it to the juggler. That interface has only one method:

By implementing this method, you could e.g. create a simple MovieClip-class yourself. In its advanceTime method, it would constantly change the texture that is displayed. To start the movie clip, you’d simply add it to a juggler.

This leaves one question, though: when and how is an object removed from the juggler?

Technically, we have now covered all the animation types Starling supports. However, there’s actually another concept that’s deeply connected to this topic.

Remember Einstein, our dog-hero who introduced us to the event system? The last time we saw him, he had just lost all his health points and was about to call gameOver. But wait: don’t call that method immediately — that would end the game too abruptly. Instead, call it with a delay of, say, two seconds (time enough for the player to realize the drama that is unfolding).

To implement that delay, you could use a native Timer or the setTimeout method. However, you can also use the juggler, and that has a huge advantage: you remain in full control.

It becomes obvious when you imagine that the player hits the "Pause" button right now, before those two seconds have passed. In that case, you not only want to stop the game area from animating; you want this delayed gameOver call to be delayed even more.

To do that, make a call like the following:

The gameOver function will be called two seconds from now (or longer if the juggler is disrupted). It’s also possible to pass some arguments to that method. Want to dispatch an event instead?

Another handy way to use delayed calls is to perform periodic actions. Imagine you want to spawn a new enemy once every three seconds.

To abort a delayed call, use one of the following methods:

You might have noticed the MovieClip class already when we looked at the class diagram surrounding Mesh. That’s right: a MovieClip is actually just a subclass of Image that changes its texture over time. Think of it as Starling’s equivalent of an animated GIF!

Starling 2.4 features a new, much enhanced AssetManager. All the code examples that follow were written with this new version in mind.

The new AssetManager class can be found in the starling.assets package. For compatibility reasons, the old version is still available at its previous location (in starling.utils), but it’s now marked as deprecated. Upgrading to the new version should be really painless — the changes in the public API were kept at a minimum. In exchange, you can profit from the new version’s much higher flexibility.

The first step is to enqueue all the assets you want to use. How that’s done exactly depends on the type and origin of each asset.

Now that the assets are enqueued, you can load all of them at once. Depending on the number and size of assets you are loading, this can take a while.

The loadQueue method accepts up to three different parameters, with separate callbacks for completion, error handling and progress. Only the first parameter (onComplete) is obligatory.

With an enabled verbose property, you’ll see the names with which the assets can be accessed.

Finally: now that the queue finished processing, you can access your assets with the various get…​ methods of the AssetManager. Each asset is referenced by a name, which is the file name of the asset (without extension) or the class name of embedded objects.

If you enqueued a bitmap font along the way, it will already be registered and ready to use.

Out of the box, Starling comes with a few very useful filters.

I mentioned it above: while the GPU processing part is very efficient, the additional draw calls make fragment filters rather expensive. However, Starling does its best to optimize filters.

Would you like to know how to create your own filters? Don’t worry, we will investigate that topic a little later (see Custom Filters).

In the meantime, you can try out filters created by other Starling developers. An excellent example is the filter collection by Devon O. Wolfgang.

Working directly with VertexData and IndexData would be quite bothersome over time. It makes sense to encapsulate the code in a class that takes care of setting everything up.

To illustrate how to create custom meshes, we will now write a simple class called NGon. Its task: to render a regular n-sided polygon with a custom color.

We want the class to act just like a built-in display object. You instantiate it, move it to a certain position and then add it to the display list.

Let’s look at how we can achieve this feat.

Like all other shapes, our regular polygon can be built from just a few triangles. Here’s how we could set up the triangles of a pentagon (an n-gon with n=5).

The pentagon is made up of six vertices spanning up five triangles. We give each vertex a number between 0 and 5, with 5 being in the center.

As mentioned, the vertices are stored in a VertexData instance. VertexData defines a set of named attributes for each vertex. In this sample, we need two standard attributes:

The VertexData class defines a couple of methods referencing those attributes. That allows us to set up the vertices of our polygon.

Create a new class called NGon that extends Mesh. Then add the following instance method:

Since our mesh has a uniform color, we assign the same color to each vertex. The positions of the edge vertices (the corners) are distributed along a circle with the given radius.

That’s it for the vertices. Now we need to define the triangles that make up the polygon.

Stage3D wants a simple list of indices, with each three successive indices referencing one triangle. It’s a good practice to reference the indices clockwise; that convention indicates that we are looking at the front side of the triangle. Our pentagon’s list would look like this:

In Starling, the IndexData class is used to set up such a list. The following method will fill an IndexData instance with the appropriate indices.

This is actually all we need for our NGon class! Now we just need to make use of the above methods in the constructor. All the other responsibilities of a display object (hit testing, rendering, bounds calculations, etc.) are handled by the superclass.

That’s rather straight-forward, isn’t it? This approach works for any shape you can think of.

Wouldn’t it be nice if we were able to map a texture onto this polygon, as well? The base class, Mesh, already defines a texture property; we’re only lacking the required texture coordinates.

Through texture coordinates, you define which part of a texture gets mapped to a vertex. They are often called UV-coordinates, which is a reference to the names that are typically used for their coordinate axes (u and v). Note that the UV range is defined to be within 0 and 1, regardless of the actual texture dimensions.

With this information, we can update the createVertexData method accordingly.

When a texture is assigned, the rendering code will automatically pick up those values.

If you look closely at the edges of our n-gon, you will see that the edges are quite jagged. That’s because the GPU treats a pixel either within the n-gon, or outside — there are no in-betweens. To fix that, you can enable anti-aliasing: there’s a property with that name on the Starling class.

The value correlates to the number of subsamples Stage3D uses on rendering. Using more subsamples requires more calculations to be performed, making anti-aliasing a potentially very expensive option. Furthermore, Stage3D doesn’t support anti-aliasing on all platforms.

Thus, it’s not an ideal solution. Luckily, however, the typical pixel-density of mobile devices is constantly on the rise. On modern, high end mobile phones, the pixels are now so small that aliasing is much less an issue than it was in the past.

You now know how to create textured meshes with arbitrary shapes. For this, you are using the standard rendering mechanics built into Starling.

However, what if you want to customize the rendering process itself? The properties and methods of the Mesh class provide a solid foundation — but sooner or later, you will want more than that.

Coming to the rescue: Starling’s mesh styles.

Styles are a brand new addition to Starling (introduced in version 2.0) and are the recommended way to create custom, high performance rendering code. In fact, all rendering in Starling is now done via mesh styles.

To teach your meshes new tricks, you can extend MeshStyle. This allows you to create custom shader programs for all kinds of interesting effects. For example, you could implement fast color transformations or multi-texturing.

To use a style, instantiate it and assign it to the style property of the mesh:

Styles are extremely versatile; their possible applications are almost without limit. And since meshes with the same style can be batched together, you do not sacrifice performance in any way. In this respect, they are much more efficient than fragment filters (which serve a similar purpose).

The main downsides of styles are simply that they can only be assigned to a mesh (not, say, a sprite), and that they can only act within the actual mesh area (making things like a blur impossible). Furthermore, it’s not possible to combine several styles on one mesh.

Still: styles are a powerful tool that any Starling developer should be familiar with. Stay tuned: in the section Custom Styles, I will show you how to create your own mesh style from scratch, shaders and all!

"This mask feature looks really nice", you might say, "but how the heck am I going to create those arbitrary shapes you were talking about?!" Well, I’m glad you ask!

Indeed: since masks rely purely on geometry, not on any textures, you need a way to draw your mask-shapes. In a funny coincidence, there are actually two classes that can help you with exactly this task: Canvas and Polygon. They go hand-in-hand with stencil masks.

The API of the Canvas class is similar to Flash’s Graphics object. This will e.g. draw a red circle:

There are also methods to draw an ellipse, a rectangle or an arbitrary polygon.

That brings us to the Polygon class. A Polygon (package starling.geom) describes a closed shape defined by a number of straight line segments. It’s a spiritual successor of Flash’s Rectangle class, but supporting (mostly) arbitrary shapes.

Since Canvas contains direct support for polygon objects, it’s the ideal companion of Polygon. This pair of classes will solve all your mask-related needs.

There are a few more things about masks I want to note:

Just like a conventional Sprite, you can add and remove children to this container, which allows you to group several display objects together. In addition to that, however, Sprite3D offers several interesting properties:

With the help of these properties, you can place the sprite and all its children in the 3D world.

As you can see, it’s not difficult to use a Sprite3D: you simply have a few new properties to explore. Hit-testing, animations, custom rendering — everything works just like you’re used to from other display objects.

Of course, if you’re displaying 3D objects, you also want to be able to configure the perspective with which you’re looking at those objects. That’s possible by setting up the camera; and in Starling, the camera settings are found on the stage.

The following stage properties set up the camera:

Starling will always make sure that the stage will fill the entire viewport. If you change the field of view, the focal length will be modified to adhere to this constraint, and the other way round. In other words: fieldOfView and focalLength are just different representations of the same property.

Here’s an example of how different fieldOfView values influence the look of the cube from the Starling demo:

Per default, the camera will always be aligned so that it points towards the center of the stage. The projectionOffset allows you to change the perspective away from this point; use it if you want to look at your objects from another direction, e.g. from the top or bottom. Here’s the cube again, this time using different settings for projectionOffset.y:

Starling is still a 2D engine at its heart, and this means that there are a few limitations you should be aware of:

However, there’s a trick that mitigates the latter problem in many cases: when the object is not actually 3D transformed, i.e. you’re doing nothing that a 2D sprite couldn’t do just as well, then Starling treats it just like a 2D object — with the same performance and batching behavior.

This means that you don’t have to avoid having a huge number of Sprite3D instances; you just have to avoid that too many of them are 3D-transformed at the same time.

I created a video tutorial that demonstrates how this feature can be used in a real-life project. It shows you how to move a 2D game of concentration into the third dimension.

In both conventional Flash and Starling, colors are specified in hexadecimal format. Here are a few examples:

The Color class contains a list of named color values; furthermore, you can use it to easily access the components of a color.