Hello AIRmobile – Your First AIR Android App

Introduction

A few days ago, I had absolutely no experience with ActionScript3 or the AIR runtime. It became necessary for me to learn the technology, so I jumped into the cold water. It took me three days of stupid mistakes to even know what mistakes I was even making in the first place, so hopefully this tutorial will accelerate your understanding enabling you to get up and running even faster then I did.

This tutorials goal is to walk you through how to do it so you do it right the first time. Even if you are not a programmer, you should be able to follow along. At the end there is a compilation of links I have found helpful.

Environment Installation

First thing we need to do is install the environment. This is fairly straight forward

Environment Setup:

1. Install Java and the JDK.  The docs for the ActionScript & MXML extension state at least Java 1.8, but we also need the JDK for keytool .
2. Install Visual Studio Code and understand the basics of vsCode (https://www.teotigraphix3d.com/2020/03/11/visual-studio-code). Afterwards install the following extensions:
3. Install the FeathersSDK from https://feathersui.com/learn/as3-starling/sdk/installation-instructions/. The SDK can be anywhere, just remember where you put it so you can add it as the working SDK later.  Its not necessary to add anything to your path but if you really want to the /bin/ folder holds the tools.
4. Install the Android SDK, make sure you can compile a native hello world app and run it on android.  This is something I’m not going to bother going in detail, this is the only part of this process that has been documented to death, and if you’re a Android dev you’ve already done that.

Installing the VSCode Extensions

In the extensions pane, search for ActionScript and MXML and install the extension by Bowler Hat LLC

Creating a New Project

This is a bit of a pain to do initially, no wizards!

Making the root folder

This is going to be your project folder. Make a new directory with nothing in it somewhere on your hard drive. Then in visual studio code, open the folder (file – open), navigate into the empty folder, and hit open.

Configuring asconfig.json

The root directory of your project needs a file called asconfig.json This file is used to configure the VScode project.

Paste this base configuration in:

{
	"config": "airmobile",
	"compilerOptions": {
		"source-path": [
			"src"
		],
		"output": "bin/Main.swf"
	},
	"mainClass": "Main",
	"application": "src/Main-app.xml"
}

This sets up the project as a AIRmobile project. “source-path” is the root folder of the project(in this example called src, we will make this folder in a second). “output” is where the output locations are(in this instance bin/Main.swf), “mainClass” sets which class is the entry point to the application, and “application” element points to the AIR application descriptor. Obviously all file paths are local. Creating a folder for /bin/ is unnecessary, as it will be created on the first compile.

/src/ folder

In the root directory create a folder called src, this is going to be your source code folder.

Creating Main.as/Configuring the working SDK

We set Main.as is the entry point, but it doesn’t exist. Time to make it.

package
{
	import flash.display.Sprite;
	import flash.text.TextField;

	public class Main extends Sprite
	{
		public function Main()
		{
			var tf:TextField = new TextField();
			tf.text = "Hello World";
			addChild(tf);
		}
	}
}

This code is just a super basic helloworld.

After you make a ActionScript file, you should see the bottom bar in vsCode turn from purple to blue. This means that the plugin has been loaded and knows that its editing ActionScript. At this point it’s probably complaining no SDK is loaded, so to fix that tell the Plugin where you installed the FeathersSDK. Feathers includes the AIRSDK, the SterlingFramework, and FeatherUIs. We wont be using FeathersUI in this tutorial.

Configuring the AIR application descriptor

This is a file that tells the compiler how to configure itself. Copy the xml, create a file named Main-app.xml, and paste it in. This is going to go where you said Main-app.xml is in as

<?xml version="1.0" encoding="utf-8" ?>
<application xmlns="http://ns.adobe.com/air/application/24.0">
    <id>com.example.Main</id>
    <versionNumber>0.0.0</versionNumber>
    <filename>Main</filename>
    <name>MainApp</name>
    <initialWindow>
        <renderMode>direct</renderMode>
        <content>[Path to content will be replaced by Visual Studio Code]</content>
        <visible>true</visible>
    </initialWindow>
</application>

This is essentially the same file as the one thats on the GitHub.

<application xmlns=”http://ns.adobe.com/air/application/32.0″>

This tag tells AIR what version you’re using. If you installed feathers from the installer, the version of AIR will be 32.0, which is the last adobe supported version of AIR. In the future this may be a higher number, as harmon has released AIR 33 with 64 bit support.

Change the 24.0 to XML I had you copy to 32.0. If you skip this step, it will not compile.

<renderMode>direct</renderMode>

If we want gpu acceleration we need to change the renderMode to direct. We do this by specifying <renderMode> in the <initialWindow> tag. This is already in the xml I had you copy, so its unnecessary to add it, but its something to keep in mind when you create a new project down the road.

Creating Launch.json

We’re almost to the point where we can make a .swf and see if it runs. Go over to the debug tab in VSCode and click on create launch.json. There will be a drop down menu in the terminal bar, make sure you select SWF, and it should generate something that looks like this.

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "swf",
            "request": "launch",
            "name": "Launch SWF"
        }
    ]
}

We will add to this later to we can debug with android, but for now this is enough to get a simple swf running.

Sanity Check!

First we need to compile the swf. To do this, simply press command + shift + P(Ctrl + Shift + P)on Windows, search for run task, press enter when you see run task, then select Compile Debug from the list.

That will compile without issue if everything is set up correctly. Now we just need to launch the swf.

Launching the Swf.

If it works that’s great. You should get something that looks like below.

Remaining Configuration For Android/Android Build Debugging

We’re almost there on the configuration end! We don’t need any more lines of ActionScript to get this text on a Android Screen.

ADT options(“airOptions”)

The Air Development Tool(ADT) is what packages your AIR application into many different formats. We want to configure it to package a .apk for use on our android device. To do this, we need to add an airOptions parameter to asconfig.json.

.json Editing in VSCode with ActionScript & MXML tutorial

Time for a little tutorial on how to edit the .json(I know this sub tutorial came out of nowhere. If you already know this skip ahead.

Add a comma to the end of line ten to show that the property is complete, then add a newline under line 10. Start to open some quotes, and you should see that autocomplete kicks in with suggestions. If you do not put in a comma, the quotes will be red instead of blue.

We want "airOptions", so press enter after its been selected. When it’s been selected expand the curly brackets, and add another object.

To a .json, "foo":{} is a object, and "foo" : "bar", is property foo with value bar. I will use Object and Property to refer to the .json elements from now on.

Add a android object inside the airOptions object. Next create a signingOptions object. Add property storetype with value pkcs12, and property keystore with value android.p12. android.p12 is the file that will be used to sign the app. Creating a .p12 is easy, we will do that in the next step.

Your completed asconfig.json should look like this:

{
	"config": "airmobile",
	"compilerOptions": {
		"source-path": [
			"src"
		],
		"output": "bin/Main.swf"
	},
	"mainClass": "Main",
    "application": "src/Main-app.xml",
    "airOptions": {
        "android": {
            "output" : "bin/Main.apk",
            "signingOptions" :{
                "storetype": "pkcs12",
                "keystore" : "test123.p12"
            }
        }
    }
}

Creating a .p12

A .p12 is a portable certificate that has both public keys and private keys. We need to create a .p12 to sign our Android app. This tutorial is going to show you how to make a dummy key just so we can sign the app, this is not a real key.

This is pretty self explanatory. All we need to do is open a terminal in the root directory of the project, and run the keytool command with those parameters:

keytool -genkey -v -keystore test123.p12 -storetype pkcs12

The signing information is irrelevant, we just need a .p12 key we have the password to.

Adding a debugging profile to launch.json

We’re almost to the point where we can test our test HelloWorld on android! This isn’t the real HelloWorld though, we’ll have something more exciting on screen then text today.

To let VSCode know that we want to launch our app on android, we need to add a android debug configuration. Simply go into the launch.json file(if its not open already it lives in /.vscode/ in your project) and press the add configuration button on the bottom left.

A dropdown will pop up, with different targets, select Install & Attach Adobe AIR (Android) . Now launch.json should now look something like this(comments omitted):

{
    "version": "0.2.0",
    "configurations": [

        {
            "type": "swf",
            "request": "attach",
            "name": "Install & Attach Adobe AIR (Android)",
            "connect": true,
            "platform": "android"
        },
        {
            "type": "swf",
            "request": "launch",
            "name": "Launch SWF"
        }
    ]
}

Now we have the option to install and launch our app on our android device. Unfortunately we still aren’t there yet! We have one last thing to do, which is to enable tethered USB debugging. By default AIR debugs wireless, which is really neat, but we want the USB.

Add a property listen to airOptions. Set listen to true. Your airOptions object should now look something like this:

    "airOptions": {
        "android": {
            "output" : "bin/Main.apk",
            "signingOptions" :{
                "storetype": "pkcs12",
                "keystore" : "android.p12"
            },
            "listen": true
        }
    }

This is telling air to listen through USB. This should be enough for us to compile our HelloWorld text to an apk. Lets try it.

Will it build?

The finial checkpoint is making sure that it will install to android. Its time to see if we can build an apk. Press Control + Shift + P, go to Run Task, and then Go to compile to android debug. Put in the password to your key, and it should compile your apk.

Finial step is plugging in your android device, making sure ADB recognizes it( adb devices in the terminal), changing the run and debug parameter from SWF to Install and Attach Adobe Air(Android) and pressing launch. If you did everything right, you should see the HelloWorld text on your mobile device. If it did, you can go to the next step. If it didn’t, you can troubleshoot 😉

Congratulations if it compiled, now its time to do the Starling helloWorld, which will give us something a little bit more interesting then just text on the screen!

Starling Helloworld!

Up until now we’ve been using flash’s APIs, (eg. flash.text.TextField). This is good, but there’s nothing special about it. This is where we call in Starling, Starling allows us to use the GPU to draw to canvas.

The starling HelloWorld displays a red box on the screen. This code is ripped right out of the Starling manual(https://manual.starling-framework.org/en/)

Change Main.as to this:

package
{
    import flash.display.Sprite;
    import starling.core.Starling;

    [SWF(width="400", height="300", frameRate="60", backgroundColor="#808080")]
    public class Main extends Sprite
    {
        private var _starling:Starling;

        public function Main()
        {
            _starling = new Starling(Game, stage);
            _starling.start();
        }
    }
}

Create a new file for a class called Game.as . Game.as should contain this code:

package
{
    import starling.display.Quad;
    import starling.display.Sprite;
    import starling.utils.Color;

    public class Game extends Sprite
    {
        public function Game()
        {
            var quad:Quad = new Quad(200, 200, Color.RED);
            quad.x = 100;
            quad.y = 50;
            addChild(quad);
        }
    }
}

Now rebuild, and run. You should get a red box on the screen. And just like that, its that easy to get multiplatform accelerated graphics!

Conclusion

I hope this tutorial was helpful for most, and to much information for others.