Can I grab a version number from the app-descriptor via ant and add that to the AIR filename? Anyone know?

This is a pretty straight forward thing to do using Ant-Contrib tasks, that are publicly available.

You can download the example files –> here.

Let’s take a quick look at the ANT script.

<project name="PopulateVersion" default="populateVersion" basedir=".">
 
  <taskdef resource="net/sf/antcontrib/antcontrib.properties">
      <classpath>
          <pathelement location="./ant-contrib.jar"/>
      </classpath>
  </taskdef>
 
  <property name="app.descriptor" value="air-app.xml" />
 
  <target name="populateVersion">
 
    <echo message="Parsing application.version from ${app.descriptor}"/>
    <xmlproperty file="${app.descriptor}" prefix="airApp.appdescriptor"/>
    <propertycopy property="versionNumber" 
                  from="airApp.appdescriptor.application.versionNumber" 
                  override="true" />
    <echo message="Parsed application version: ${versionNumber}"/>  
 
    <propertyregex property="fileVersionNumber"
                  input="${versionNumber}"
                  regexp="\."
                  replace="_"
                  casesensitive="false" />
 
    <echo>Version Number: ${versionNumber}</echo>                    
    <echo>File Version Number: ${fileVersionNumber}</echo>
  </target>
 
</project>

As you can see it’s very straight forward to parse the version number out of the Application Descriptor. The only other thing we do is us RegEx to change the periods in the version number to underscores to make for more friendly file names.

Using the same concept it is very easy to also populate a Version file that gets compiled into your application which can include build numbers, or other interesting things… but we’ll save that for another day.

For example, here is Eden pulling a screen capture from HanClinto’s Platformer Starter Kit.

Really cool! However, I quickly ran into an issue when I tried to take a screen capture of a more basic game.

On the right is the game running in Flash, and on the left is the screen capture.

As you can see, my screen capture doesn’t include the green background. So what happened?

Well it turns out the background color of a SWF isn’t actually part of the stage. The background color that you set using the SWF Metadata tag, or set in Flash Professional is drawn directly by Flash Player.

package
{	
	import flash.display.Sprite;
 
	[SWF(backgroundColor="0x00FF00")] // <--- How can I get this programmatically?
	public class SwfBackgroundExample extends Sprite
	{
		public function SwfBackgroundExample()
		{
		}
	}
}

So I had a dilemma… how could I access the backgroundColor of the SWF? I scoured the API docs, I asked the Twitter-sphere, but no luck. All I learned was that the backgroundColor was hard coded into the bytes of the SWF. So I decided that’s where I needed to look for it.

SwfData to the rescue.

I read up on the Adobe SWF specification, and consulted with my good friend James Ward. He pointed me in the direction of loaderInfo.bytes, which gives us access to the bytes of the currently running SWF.

After a few hours, I had a fun little class I like to call SwfData, which parsed the background color out of the currently running SWF’s bytes… as well as some other fun things. Here’s how you use it:

package
{
	import com.zaalabs.utils.SwfData;
 
	import flash.display.Sprite;
 
	[SWF(backgroundColor="0x969696")]
	public class SwfDataExample extends Sprite
	{
		public function SwfDataExample()
		{
			var data:SwfData = new SwfData(loaderInfo.bytes);
 
			trace("version \t"+data.version);
			trace("frameRate \t"+data.frameRate);
			trace("frameCount \t"+data.frameCount);
			trace("fileLength \t"+data.fileLength);
			trace("bgColor \t0x"+data.backgroundColor.toString(16));
		}
	}
}

Using SwfData, I could now use the background color as the fill color of my BitmapData class.

Get It Here

SwfData is MIT licensed under ZaaUtils (do with it what you will). It is available on GitHub

Questions, comments, complaints are all welcome below.

== UPDATE ==

So I just found out that Claus Wahlers has an awesome, more feature complete version of an AS3 SWF parser. It’s also available on GitHub. I’m still going to keep SwfData up since it’s much more specific to getting the background color of the swf. If you need more features, use as3swf by Claus, it’s very well done.

There is now an update for Flash Builder 4 which downloads and installs the Adobe Flex 4.1 SDK. According to Renaun Erickson’s post, Flex 4.1 includes Flash Player 10.1 and AIR 2.0.

Now, if you’re like me and loathe the Adobe Updater… then you probably turned off the Adobe Updater notifications.

So here’s how to update Flash Builder to version 4.0.1 which includes the 4.1 SDK.

Go to Help > Search for Flash Builder Updates…

This will launch the Adobe Application Manager and then proceed to update your software, including Flash Builder 4.

== UPDATE ==

Once the update is completed you can see Flash Builder is now at version 4.0.1.

And you now have the option for Flex 4.1 as an installed Flex SDK. You can use Flex 4.1 to develop against Flash Player 10.1 and Adobe AIR 2.0.

This process has gotten much easier, you can now use software update to get AIR 2 as well as Flash Player 10.1 in Flash Builder… check out this post.

Adobe AIR 2 and Flash Player 10.1 were released on June 10th, 2010. It’s an exciting time. This weekend I decided to do some development on AIR 2 to try out some of the new features.

On the Adobe AIR Team blog’s post they mention that the free standalone download of the AIR 2 SDK will be available on Tuesday, June 15th… but I wanted to play with the SDK today.

So I went over to the Adobe AIR labs page and downloaded the AIR 2 Release Candidate SDK which is –> here.

You can download the released SDK from –> here

After downloading the Adobe AIR 2 SDK, I followed the directions on the release notes which explained how to overlay the AIR 2 SDK with my current version of Flex 4.

I’m on a mac, here are the commands I used in Terminal:

cd /Applications/Adobe\ Flash\ Builder\ 4/sdks/
ls
cp -r 4.0.0 4.0.0AIR2
ls
cp ~/Downloads/air2_rc1_sdk_mac_051110.tbz2 4.0.0AIR2
cd 4.0.0AIR2
tar jxvf air2_rc1_sdk_mac_051110.tbz2

I then added a new SDK to the installed SDK’s inside of Flash Builder:

Now, I already had an Adobe AIR application project set up, and I switched over to the new SDK the I installed:

However, when I tried to run my AIR application, I ran into this error:

VerifyError: Error #1014: Class IIMEClient could not be found.
 
	at flash.display::MovieClip/nextFrame()
	at mx.managers::SystemManager/deferredNextFrame()[E:\dev\4.0.0\frameworks\projects\framework\src\mx\managers\SystemManager.as:267]
	at mx.managers::SystemManager/preloader_preloaderDocFrameReadyHandler()[E:\dev\4.0.0\frameworks\projects\framework\src\mx\managers\SystemManager.as:2460]
	at flash.events::EventDispatcher/dispatchEventFunction()
	at flash.events::EventDispatcher/dispatchEvent()
	at mx.preloaders::Preloader/timerHandler()[E:\dev\4.0.0\frameworks\projects\framework\src\mx\preloaders\Preloader.as:488]
	at flash.utils::Timer/_timerDispatch()
	at flash.utils::Timer/tick()

After doing a bit of research I found out that my Adobe AIR project’s application descriptor file wasn’t using the correct namespace for the AIR 2.0 SDK. According to the Adobe AIR 2 Release Notes:

You must update your application descriptor file to the 2.0 namespace in order to access the new AIR 2 APIs and behavior. If your application does not require the new AIR 2 APIs and behavior, you are not required to update the namespace from 1.x based namespace. To update the namespace, change the xmlns attribute in your application descriptor to: http://ns.adobe.com/air/application/2.0

Sure enough, I hadn’t changed my namespace from AIR 1.5.3 to AIR 2.

I made the change in the descriptor file, and now everything works perfectly.

• When I email my game to the client it won’t run on his computer
• Playing the game only works inside my Flash Builder (or Flex Builder) project development folder
• My game worked perfectly in one folder, but no longer works when moved to another folder

These issues are all part of the same underlying problem, a misunderstanding of Flash Player Security.

The first question you should ask yourself is… what security sandbox type is my game running in?

What is a Sandbox Type?

The sandbox type indicates the type of security zone in which the SWF file is operating.

Please remember that the security sandbox is determined at runtime, not compile time!

In the PushButton Engine we make identifying the security sandbox easy. When your game starts it logs the security sandbox that your swf is currently running (you can also get this by using the built in “version” console command). It looks like this:

PBE - PushButton Engine - r841 (ZaaBot build #97) - flash - localTrusted

In this case, the game is running in “localTrusted”. Most games that you run from Flash Builder will run in the localTrusted sandbox type. This is because Flash Builder configures your system to trust files in Flash Builder project directories. This is meant to make our lives easier as Flash developers… but it can cause confusion.

You can figure out what sandbox you’re running in by checking Security.sandboxType at runtime.

So what are the types of sandboxes?

In Flash Player, all SWF files are placed into one of four types of sandbox:

remote All files from non-local URLs are placed in a remote sandbox. Basically anything loaded from the web (ex: http, https) falls into this category. There is no access to the local filesystem.

local-with-filesystem This is the default sandbox for local files. SWF files in this sandbox may not contact the Internet (or any servers) in any way. They may not access network endpoints with addresses such as http URLs.

local-with-networking A SWF file in this sandbox may communicate over the network but may not read from local file systems. It is the exact opposite of local-with-filesystem.

local-trusted This sandbox is not restricted. Any local file can be placed in this sandbox if given authorization by the end user. This authorization can come in two forms: interactively through the Settings Manager or non-interactively through an executable installer (or created manually) that creates Flash Player configuration files on the user’s computer.

I added use-network=false to the compiler / flex-config file and it fixed it!

That’s great, but you still need to understand what is happening.

When you add the “use-network=false” parameter to your compilation, you are forcing the swf into the local-with-filesystem sandbox (“user-network=true” forces local-with-networking). This may end up giving you the desired behavior that you want, a swf that will run locally when you send it to your client or friends. However, you may run into some issues later on.

What if you and your friends were competitive, and you then decided your game needs to post a high score? You would need to make a request to a server to submit the score. When running in the local-with-filesystem sandbox you are not able to make requests of any kind to the internet, and therefore you can’t post to the score board.

So what is the solution?

You could teach all of your friends how to setup their game to run in localTrusted, by configuring their security files. But there has got to be a better way.

Well there is, and it all depends on how you plan to deploy your game.

I want to distribute a local game.

The recommended way to distribute flash games to be run locally is using the Adobe AIR runtime. It’s a great platform, and gives you much more flexibility and functionality.

I want to put it on a website.

So the best way to test your game then would be, to put it on a website. Now don’t get scared, this isn’t going to change your development workflow all that much.

The simplest way to simulate a local swf running on a website would be to have a local web-server running on you box. I highly recommend WAMP for Windows, MAMP for Mac OS X and LAMP for you Linux folk.

You then build your game (setup your output directory to drop the files in the web root) and launch your web-browser. Running a game swf from http://localhost will put your swf into the “remote” sandbox. You will want to do all of your testing within this sandbox, because it best mirrors the environment when you deploy your game to the web.

More Information

This post is just a brief overview of a very complex topic, for more information check out these resources:

Flash Player Security Basics

A full hour presentation from MAX 2008 by Deneb Meketa, explaining how Flash Player Security works and why it does it that way (if you don’t want to watch the whole thing, 47:12 is where it talks about local file security). I highly recommend everyone watch it:
Understanding the Flash Player Security Model

Using the Console

The only thing you need to do to include the Console into your project is call PBE.startup().

package
{
	import flash.display.Sprite;
	import com.pblabs.engine.PBE;
 
	public class HelloConsole extends Sprite
	{
		public function HelloConsole()
		{
			PBE.startup(this);
		}
	}
}

Once your game is running, to access the console press the default hot key, which is the Tilde (~) / Grave (`) key.

As of this post, the latest revision of the PushButton Engine is revision 702. In this version there are some commands registered by default:

• help – List known commands.
• clear – Clears the console history.
• listDisplayObjects – Outputs the display list.
• showFps – Show an FPS/Memory usage indicator.
• verbose – Set verbosity level of console output.
• version – Echo PushButton Engine version information.

Quick Tricks

The console supports a few shortcuts to make your life easier:

• The console is not case-sensitive, so don’t worry if you put showFps or shOwFPS, the same command will execute.
• You can use the up and down arrows to move through your command history.
• By pressing enter on an empty command line, you can add new lines. This is helpful for adding space between commands to make it easier to read.
• You can use the “name” property on a DisplayObject to make meaningful names show up in the listDisplayObjects command.
• Different Log Levels are colored by default, to change the colors edit com.pblabs.engine.debug.LogColor.

Creating custom commands for the console

The PBE console also supports the ability for the developer to add their own commands.

package
{
	import com.pblabs.engine.PBE;
	import com.pblabs.engine.debug.Console;
	import com.pblabs.engine.debug.Logger;
 
	import flash.display.Sprite;
 
	public class ConsoleCommand extends Sprite
	{
		public function ConsoleCommand()
		{
			PBE.startup(this);
			Console.registerCommand("test", onTestCommand, "This is a test command.");
			Console.registerCommand("testStrict", onTestStrict, "Test strict parameters.");
		}
 
		protected function onTestCommand(... args):void
		{
			Logger.print(this, "onTestCommand: "+args);
		}
 
		protected function onTestStrict(str:String, num:Number):void
		{
			Logger.print(this, "You passed in the string: "+str);
			Logger.print(this, "You passed in the number: "+num);
		}
	}
}

Parameters are passed in sequence using spaces. So to run the test command, I would open the console, and then type “test a b c 1 2 3″. This would then call the onTestCommand method and pass in an array with 6 elements.

Below is an example of what using custom commands in the console looks like.

Changing the Console HotKey

Some of our good friends over in the Netherlands use different keyboard layouts, so they requested the ability to change the hot key binding to another key.

package
{
	import com.pblabs.engine.PBE;
	import com.pblabs.engine.core.InputKey;
	import com.pblabs.engine.debug.Console;
	import com.pblabs.engine.debug.Logger;
	import com.pblabs.engine.debug.UIAppender;
 
	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;
 
	public class TestConsole extends Sprite
	{
		public function TestConsole()
		{
			PBE.startup(this);
 
			UIAppender.hotKey = InputKey.C.keyCode;
			Console.registerCommand("test", onTestCommand, "My test command");
		}
 
		protected function onTestCommand(... args):void
		{
			Logger.print(this, "onTestCommand: "+args);
		}
	}
}

WARNING!!! When changing the hot key to another key, the input textfield doesn’t escape the new key binding. So you must remove focus from the input field to use the hot key to close the console.

More information on this can be found in issue 98.

What’s coming?

I do have plans on adding either tab-complete or a drop-down auto complete list into the console which will match avaliable commands.

Another thing that I’m currently working on is code-named Tumbler. It’s and Adobe AIR version of the console which has additional features to assist in debugging and troubleshooting your games.

It’s a proof-of-concept at the moment… but if there is enough interest in it… I may spend more time on it.

[Bindable] private var _skills:Array = 
[
	{label: "---", id: -1},
	{label: "1 - Newbie", id: 1},
	{label: "2 - Some Experience", id: 2},
	{label: "3 - Expert", id: 3},
	{label: "4 - I'm a baller", id: 4}
];

And then binding this data provider to a ComboBox…

<mx:ComboBox id="skillsCB" dataProvider="{_skills}" />

Well it turns out there is a much easier way of doing this that I never knew of until today. ComboBox has a “prompt” attribute that you can set. It’s so easy…

<mx:ComboBox id="skillsCB" dataProvider="{_skills}" prompt="---" />

I told you it was easy. Can’t believe I never noticed it before.

Check it out here —> Bug Quash

Please vote on the poll. We’re trying to see how much interest there is in this kind of event.

Any questions, comments, ideas, complaints, suggestions, etc… please post them below.

p.s. I know… this wasn’t really a tip… but I’m tired and it’s beddy time for Nate.

:: Update ::

New information including how to sign up for notifications —> here.

Here is the code:

function flip( display:DisplayObject, orientation:String ):void {
 
       var m:Matrix = display.transform.matrix;
 
       switch (orientation.toUpperCase()) {
 
               case "HORIZONTAL" :
                       m.a = -1;
                       m.tx = display.width + display.x;
                       break;
               case "VERTICAL" :
                       m.d = -1;
                       m.ty = display.height + display.y;
                       break;
       }
       display.transform.matrix = m;
}
 
flip(logo, "horizontal");

This tip was provided by Sidney K. Thanks Sidney!

Your tip for the day… The Flex SDK team has a guide that explains the coding conventions that they use within the SDK (for the most part).

Flex SDK coding conventions and best practices

I agree with almost all of the conventions they list here. If you’re planning on contributing the to Flex SDK, you NEED to be familiar with these conventions.