ShiVa Flash: ActionScript 3 Interaction

Project Builds

With the latest Unified Authoring Tool 1.4, you gain the ability to generate project builds. Those will give you a lot more control over your source code files and allow you to modify them to fit your needs. With Flash project builds in particular, you can now edit .as documents. This opens the gates to a lot of fun… Let’s have a look at it!

ShiVa Setup

For our little demo scene, we have added a small HUD overlay with two buttons to the projector demo. Here is how they are arranged:

Now we need two handlers in the main AI that pick up the event:

The core function here is system.callClientFunction. The first argument, “onEngineEvent”, is mandatory – this will be the function in the ActionScript file we will change later. It is predefined. All other arguments can be chosen freely.

UAT Project Build

Export your game as STK and load it into the the UAT. in “Step 2″, choose “Project”:

Fun with ActionScript

You should now have a $mygame.as file in your protect directory. Open it up with a text editor of your choice.

Scroll down to the function onEngineEvent. The interesting part is highlighted in the next picture:

Have a good look at the comments in this file, they do explain a lot.

Adding Functionality

For this demo, we want to use AS3 to load an external picture onto our stage as well as create a button. First, we need to capture the event that we send from ShiVa. Let’s remember our system calls:

system.callClientFunction ("onEngineEvent", "as3button", "image")

And the other one:

system.callClientFunction ("onEngineEvent", "as3button", "button")

onEngineEvent is predefined and thus does not count. Both calls use as3button as first argument, they only differ in the second argument: button or image.

onEngineEvent expects its arguments in pairs. For instance, _args[0] and _args[1] both define the first argument, in our case, “as3button”. _args[0] holds the argument type (nil, number, string, boolean), while _args[1] holds its value (“as3button”). So, in order to solve our “button” and “image” problem, we need to look at _args[2] and _args[3], since we are dealing with the second argument of onEngineEvent.

if ( _args[2] == kVarTypeString )
{
    if ( _args[3] == "image" )
    {
    //...
    } 

    if ( _args[3] == "button" )
    {
    //...
    }
}
}

If we were to return values, this scheme would apply to _returns:Array as well.

You can look up the code for displaying an image in the .as file that comes with the sources for this demo. It is important to remember that you have to draw your new image onto the stage using

stage.addChild

Most AS3 resource sites will suggest addChild or this.addChild to you, which most likely will not work; use stage.*

In order to make the button change its state, we had to introduce a number of new functions into the AS3 file. Those are defined outside onEngineEvent, but inside the main class (in this case: public class FlashInteractionDemo_20120624)

		private function as3buttonClickHandler(event:MouseEvent):void
		{
			turnButtonGreen();
		}

               //...

		private function turnButtonGreen():void
		{
			as3demobutton.graphics.beginFill(0x008000);
			as3demobutton.graphics.drawRect(550, 300, 300, 80);
			as3demobutton.graphics.endFill();
		}

These functions are responsible for changing the button color and managing its states. They can be found at the end of the .as file.

The image button uses a method called URLRequest. Compiling the script now will cause an error. You need to import the library that includes this method first. Therefor, in the top of the file, define

import flash.net.*;

right under all the other includes that are already present.

The button sprite requires a variable declaration, you can find it on top of the main class.

private var as3demobutton:Sprite;

Building

To compile and build your application, simply execute the BAT file that is provided in your project directory.

The CMD window closes as soon as the build is completed. Sadly, it also closes as soon as it encounters an error and does not give you enough time to read the error message. To fix this problem, open a CMD window from the Windows Start Menu, CD to your project directory, and drag the BAT file into this CMD window.

Demo Time

Your project is now ready to go! Let’s have a look at the demo (click on the image to open a new tab):

One more thing…

Don’t forget to AZOTH your projects! Azoth is a Windows console (Win32 command-line) application that lets you replace method calls to a certain AS3 class (included with Azoth) with equivalent Alchemy opcodes in a SWF file. This provides superior performance for your game! Simply drag your game SWF onto the Azoth.exe binary and let it do its magic…