The Starling Manual

At the time of its introduction, AIR was part of a trend summarized under the term "Rich Internet Applications" (RIA) — a buzzword that was all the rage in the late 2000’s. There was a fierce competition between Adobe’s AIR and Microsoft’s Silverlight (as well as Sun’s JavaFX). Fast forward to the present day, though, and it’s apparent that the tides have turned. The winner is clearly HTML5/JavaScript, which is now the most popular technology stack when building applications with web technologies.

The most prominent victim of this rivalry is the Flash plugin. For years, it played a major role in moving the web platform forward; however, it rapidly lost relevance in the 2010s and was officially laid to rest in early 2021. It’s now difficult to even display legacy Flash content – which is sad for all the great content created by developers over the last decades.

Make no mistake, though: that’s the Flash plugin we’re talking about here. AIR is still seeing solid commitment, with regular releases and feature updates throughout each year. Mind you: as of June 2019, that commitment is no longer coming from Adobe — but from Harman. They have taken on the platform support and feature development of AIR and are providing new versions on a commercial basis (with a free version available for smaller companies).

Granted, it may no longer be the "cool kid" in town, but AIR is still an extremely attractive platform to build software with:

Talking about Starling …​ how does it fit into this picture?

As outlined above, Starling’s API is very similar to the native Flash API, namely: the flash.display package. So you might ask: why go to all that effort to recreate Flash inside …​ err, Flash?

The reason is that the original flash.display API, with its flexible display list, vector capabilities, text rendering, filters, and whatnot, was designed in an era of desktop computers. Those computers had powerful CPUs, but (by modern standards) primitive, fixed-logic graphics hardware. Today’s mobile hardware, on the other hand, has an almost reversed setup: a weak (i.e. battery-conserving) CPU with a very advanced graphics chip.

The problem: it’s extremely difficult (if not impossible) to change an API that was designed for pure CPU rendering to suddenly use the GPU efficiently. Thus, such attempts failed spectacularly, and the Flash plug-in is nowadays completely gone from browsers on phones and tablets.

To its credit, Adobe was very aware of this issue. That’s why, back in 2011, they introduced a low level graphics API called Stage3D. That API is decidedly low-level; it’s basically a wrapper of OpenGL and DirectX, allowing developers to access the raw power of the GPU.

The problem: such a low-level API didn’t help users of the classic display list much, at least not right away. The Stage3D API is as low-level as it gets, so it’s nothing a typical developer can (or should!) directly work with when creating an app or game. Clearly, Adobe needed a more high-level API, built on top of Stage3D, but as easy to use as flash.display.

Well …​ this is where Starling enters the stage (pun intended)! It was designed from ground up for Stage3D, while mimicking the classic Flash API as much as possible. This makes it possible to fully leverage today’s powerful graphics hardware, while using concepts countless developers are already familiar with.

Adobe could have made such an API themselves, of course. However, monolithic APIs built by big companies have the tendency to become big and inflexible. A small open source project, on the other hand, powered by a community of equal-minded developers, can act much more swiftly. That’s the insight that led Thibault Imbert, product manager of the Flash and AIR platforms in 2011, to initiate the Starling project.

To this day, Starling is funded and supported by Adobe.

One of the core aims of Starling was to make it as lightweight and easy to use as possible. In my opinion, an open source library should not only be easy to use — it should also encourage diving into the code. I want developers to be able to understand what’s going on behind the scenes; only then will they be able to extend and modify it until it perfectly fits their needs.

That’s why Starling’s source is well documented and surprisingly concise. With a size of just about 15k lines of code, it’s probably smaller than most games that are written with it!

Another important goal of Starling is, of course, its close affinity to the display list architecture. That’s not only because I really like the whole idea behind the display list, but also to make it easy for developers to transition to Starling.

Nevertheless, I was never trying to create a perfect duplicate. Targeting the GPU requires specific concepts, and those should shine through! Concepts like Textures and Meshes aim to blend in seamlessly with the original API, just as if it had always been designed for the GPU.

Flash Builder is the official IDE from Adobe; you might also know it under its former name Flex Builder. You can either purchase it as a standalone version (in a standard and premium edition) or get it as part of a Creative Cloud subscription.

Built upon Eclipse, it is a very powerful piece of software, supporting all the features you’d expect, like mobile debugging and refactoring. The premium edition even includes a very useful performance profiler.

Personally, I used Flash Builder for a very long time, and the Starling download even comes with suitable project files. However, there is one caveat: Flash Builder has apparently been abandoned by Adobe. The last update (version 4.7) was released in late 2012, and it wasn’t particularly stable. There are no indications that this situation will change anytime soon.

Thus, I can only recommend it if you are a Creative Cloud user anyway (because then, you’ll get it for free), or if you’ve got an old license lying around somewhere. Don’t get me wrong: it has a great set of features, and you will get stuff done with it. But you will have to live with occasional crashes, and updating the AIR SDK is a chore.

The next candidate might be called "the IDE to rule them all", because IDEA supports a plethora of languages and platforms. AIR support is handled via the plug-in "Flash/Flex Support".

I’ve been using IDEA for quite a while, and I really like it (especially for its powerful refactoring features). Feature-wise, it feels just like it was built for AS3; all the important parts are in place.

Different to Flash Builder, the IDE receives regular updates. Unfortunately, that’s not the case for the Flash plug-in in particular, though. There are some (minor) deficits that have been waiting for a fix for quite a while.

That’s all just nitpicking, though. It’s an excellent IDE, and it’s my recommendation if you’re on macOS. The only caveat might be that JetBrains recently switched to a subscription based pricing model, which might not be attractive for everybody.

There’s also a free community edition of IDEA, but unfortunately it doesn’t include the Flash/Flex Support plug-in.

As much as I love working on macOS, here’s an area where I occasionally envy Windows users: they have access to an excellent free (open source) IDE for Starling development: FlashDevelop. It has been around since 2005 and is still seeing updates on a regular basis. If you’re into Haxe, it has you covered, as well.

Since I’m primarily using macOS, I don’t have very much first-hand experience with FlashDevelop; but from countless posts in the Starling forum, I’ve heard only good about it. Some people are even using it on the Mac via a virtual machine (like Parallels).

Just like Flash Builder, FDT is built on the Eclipse platform. Thus, it’s a great choice when moving away from Flash Builder, since it all looks and feels very similar. You can even import all your Flash Builder projects.

FDT does improve on Flash Builder in several areas; for example, you can easily change the type of an existing project from Flash to AIR — something that is impossible in Flash Builder. It also supports several additional languages, like HTML5/JavaScript, Haxe and PHP.

All in all, it’s a very solid IDE. If you like Eclipse, you can’t go wrong with FDT!

Visual Studio Code is a lightweight but powerful source code editor that’s available for all major desktop operating systems. While it does not support ActionScript out of the box, there is an extension that makes it a viable (and free!) alternative to the other IDEs.

The ActionScript & MXML extension is being developed by Josh Tynjala, who has also brought you the fantastic Feathers user interface components. It turns Visual Studio Code into a full-fledged ActionScript development environment, including code intelligence features like auto-completion, automatic class imports, comfortable debugging, etc.

You’ll be a little bit closer to the metal than with the other IDEs when it comes to configuring your build process, but that’s not a bad thing! I highly recommend giving it a try.

If you’re a designer or a developer who has been using Flash for a very long time, you might wonder where Adobe Flash Professional is coming up in this list. Well, here it is! If you’re not recognizing it, that’s because Adobe recently renamed it to Adobe Animate. That actually makes a lot of sense, since the new name reflects a major change in its focus. Animate is now a general-purpose animation tool, supporting output not only to Flash, but also HTML5, WebGL, and SVG formats.

While you can use Animate for Starling, I wouldn’t recommend it. It’s a fantastic tool for designers, but it simply wasn’t built for writing code. You’ll be much better off using it just for the graphics, and writing the code in one of the other mentioned IDEs.

If you have picked and installed your IDE, the next step is to download the latest version of the AIR SDK. Each new release typically contains several important bug-fixes, which is especially important to maintain compatibility with the latest mobile operating systems. Thus, it’s recommended to always use the very latest version, and to keep an eye on the latest release notes.

Beginning with version 33, AIR is being developed and supported by Harman. You can find it here: Download AIR SDK from Harman.

After the "death" of Flash Player, you technically don’t need the Flash Player Projector any longer. That’s a standalone version of the plugin that doesn’t require a browser to run Flash content.

However, it’s still a great way to play around with ActionScript and Starling without the hassle of setting up a complete AIR project. Furthermore, you can use the projector to view legacy Flash content ("SWF movies", as they called them), so I recommend you grab a copy before Adobe removes it altogether!

Downloads for all operating systems are available here (look for the "projector content debugger"): Adobe Flash Player Debug Downloads

Your IDE might need to know how to find the correct player. For example, in IDEA, this setting is part of the debug configurations screen; other IDEs might simply use the system default. In any case, it’s important to always use a player version that’s equal to or higher than the AIR SDK version you compiled the SWF with.

Now all that’s left to download is Starling itself. You can choose between two ways of doing that.

The advantage of the former is that it comes with a precompiled SWC file (found in the folder starling/bin) that is easily linked to your project. However, you’ll always only get the stable releases this way, which means you’re missing out on the latest hot updates and fixes! For this reason, I’d rather advocate using Git.

Going into depths about Git would exceed the scope of this manual, but you’ll find lots of great tutorials about it on the web. Once installed, Git can clone the complete Starling repository to your disk with the following command:

This will copy Starling to the folder Starling-Framework. Look for the actual source code inside the sub-folder starling/src. All of the mentioned IDEs support adding this folder as a source path to your project, which will make Starling part of your project. That’s not any more complicated than linking to the SWC file; and as a neat side effect, you will even be able to step into Starling’s source on debugging.

But what’s best about this approach is how easy it is to update Starling to the latest version. Simply navigate into the repository’s directory and pull:

That’s much simpler than opening up the browser and manually downloading a new version, isn’t it?

The best of us get stuck sometimes. You might hit a road block because of a bug in Starling, or maybe because of a problem that seems impossible to solve. Either way, the Starling community won’t leave you alone in your misery! Here are some resources that you can go to when you need help.

Here’s a quick summary of the preparations you should already have made:

Configuring the IDE and setting up a project is done slightly different in each IDE. To help you with that, I created a specific how-to for each IDE in the Starling Wiki. Please follow the appropriate tutorial before you continue.

Create a new project or module in your IDE; I recommend you start with a Flash Player project (target platform: Web) with the name "Hello World". As part of the initialization process, your IDE will also setup a minimal startup class for you. Let’s open it up and modify it as shown below. (Typically, that class is named like your project, so exchange the class name below with the correct one.)

This code creates a Starling instance and starts it right away. Note that we pass a reference to the “Game” class into the Starling constructor. Starling will instantiate that class once it is ready. (It’s done that way so you don’t have to take care about doing stuff in the right order.)

That class first needs to be written, of course. Add a new class called Game to your project and add the following code:

The class just displays a simple red quad to see if we’ve set up everything correctly.

Now start up the project. For some of you, the output might be a little anticlimactic, because you are seeing an error message like this:

In that case, it was probably the browser that opened up instead of the standalone Flash Player. Check the run/debug configuration and make sure the Flash Player Projector (debug version) is used, not the browser. That should fix the problem.

Congratulations! You have successfully compiled and run your first Starling based project.

Seriously: the most daunting part now lies behind you. Finally, we are ready to dig into a real project!