As I spend more and more time on the PushButton Engine Forums, it’s funny how often the same topic seems to come up. Today a topic showed up again, regarding running Flash swf files locally. You see this same topic in many different flavors…

• 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.

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.

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

So I know I haven’t posted in quite some time. Between work, BugQuash, MAX, contributing to PushButton Engine, my country’s 500th anniversary to plan, my wedding to arrange, my wife to murder and Guilder to frame for it, I’ve been swamped.

But tonight… I break my blog silence. As I just mentioned, I’ve been contributing to the PushButton Flash Game Engine. I’m now going to show you how to set up Flex Builder 3 or Flash Builder 4 in a way that allows you to develop games on PushButton Engine, as well as how to work on the core engine itself. I’m breaking this down into very small pieces so that everyone can follow along. So it’s going to be a long post with lots of pretty pictures.

After writing this post, it ended up being longer than I hoped. So I’m going to write a series of posts about developing games using PushButton Engine. This post will focus only getting set up inside Flash and Flex Builder. The plan is to add other IDEs in as well, for example FlashDevelop, FDT, etc…

Step 1 : Download the PushButton Engine source code.

[note]
If you are not familiar with Subversion or you need a primer to the basics of contributing to or working with open source projects please check out my “Getting Dirty with the Flex SDK” post, more specifically the TechWed Presentation.
[/note]

WARNING!! For these steps to work, you must use at least revision 602 of the PushButton Engine.

Download the PushButton Engine core from Google Code. Since I am a developer in the engine, I have checked out trunk and all of the branches. My working copy is located in /pbe (or C:/pbe on Windows). I will use that location throughout the rest of this post. Make sure that if you choose a different location that you sub it in wherever I use “/pbe”.

So on OS X, to checkout the source code, open up Terminal and type in the following lines:

cd /
svn checkout http://pushbuttonengine.googlecode.com/svn/ pbe

Step 2 : Import the PBEngine Library project within Flex/Flash Builder.

Open up Flex Builder (or Flash Builder), right click in the Flex Navigator and choose Import. (You can also use File > Import > Other).

Open up the “General” folder and choose “Existing Projects into Workspace” and click “Next”.

Click the “Browse” button next to “Select root directory”.

In revision 600 of the PushButton Engine I added “FB3″ and “FB4″ directories underneath “trunk/development”. These directories have a Flex Library project skeleton within them that can be imported directly into Flex Builder.

If you are using Flex Builder 3, use the FB3 directory, and if you’re using Flash Builder 4, use the FB4 directory.

Click Finish.

You will see a Flex Library project in the Flex Navigator now. You will also have an error, don’t worry, we’ll fix that in the next step.

Step 3 : Setup the a Linked Resource for PBE

So here is the error that you will see:
configuration variable ‘compiler.source-path’ value contains unknown token ‘PBE’

The project skeleton uses something called a “Linked Resource”, so that it can find the PushButton Engine source files. To set this Linked Resource, you do the following:

Open up Flex Builder’s preferences.

Under General > Workspace > Linked Resources… Click “New…”

Click on the “Folder…” button and navigate to the PushButton Engine “trunk” folder, “/pbe/trunk” (C:/pbe/trunk on Windows).

Hit “OK” and you should see PBE listed in the Linked Resources now.

Clean the project to incorporate and rebuild all of the changes.

If you see PBEngine.swc underneath the bin folder, you are good to go! Nice work!

:: UPDATE ::

There have been file renames and other changes in the PushButton engine since this post. If your SWC is failing to build do the following.

In the Flex Navigator, right click on the PBEngine Flex Library project. Click Properties. Go to “Flex Build Library Path”, under “Classes” uncheck [source path] src and recheck it. If you are using Flash Builder 4, you can simply select “Include all classes from all source paths”. Any other questions… post a comment and I’ll answer them.

Step 4 : Create your game!

For this example I’m going to create a VERY simple Hello World game to show that we have everything working correctly.

Right-click in Flex Navigator and choose “New” > “ActionScript Project”.

Give it a name of “HelloGame”, and click Finish.

Now, to use the PBEngine Library within our HelloGame project, we need to create a link between the two.

To do this, right click on the “HelloGame” project and choose “Properties”.

Choose “ActionScript Build Path” from the list, and then click on “Add Project…”

You should see “PBEngine” in the list.

If you don’t see PBEngine, or you get a message that tells you, “There are no Flex Library projects in your workspace”, make sure that a) you have created a PBEngine Library by following the previous steps and b) the project is not closed.

Select “PBEngine” and click “OK”. You will now see PBEngine listed in the Build path libraries box.

Now that the two projects are linked, you can start using classes right out of the PushButton Engine. Code completion works, and everything compiles. Woot!

Great, now let’s write our impressive Hello World game.

Here is the source:

package {
	import com.pblabs.engine.PBE;
	import com.pblabs.engine.debug.Logger;
 
	import flash.display.Sprite;
 
	public class HelloGame extends Sprite
	{
		public function HelloGame()
		{
			PBE.startup(this);
			Logger.print(this, "Hello Nate!");
		}
	}
}

Run or Debug the game. At first you will see a blank screen, that is expected… Press the ~ (tilde or `) key, and the PushButton Console should come up.

The console has some commands by default: help, version, showFps and verbose (1 || 2)

You can add your own custom commands to the console to assist you while developing your games… but that is a post for another time.

Any questions, be sure to hit us up over on the PushButton Engine Forums or in the freenode IRC channel: #pbengine.

I have an extensive background using the Microphone class within Flash Player. Anytime you try to connect to a user’s microphone, Flash Player displays a privacy dialog box that alerts the user to choose whether to allow or deny access to the microphone.

I’m sure you’ve seen it, this is what it looks like:

You widget (or app) MUST be a minimum of 216 x 138 (some people will argue you can do 215 wide, but in my testing sometimes 215 pixels wide can cause issues). When the player window is too small, the settings panel will either:

1. Not show up at all, or
2. Show up clipped and in some browsers mouse events will not register in Flash

You cannot disable the settings panel.

Here are a few helpful tips that I have figured out:

• The widget needs to be 216 x 138 ONLY when you’re asking for permission to the microphone. If you have control of Javascript on the page, you can change the size of the flash object on the page temporarily while you show the settings panel.
• You can use “Security.showSettings(SecurityPanel.PRIVACY);” to control when you want the settings panel to show up. Using the Security.showSettings method is helpful because there is a Remember button on that panel. If the user chooses “Remember”, then you never have to show the Settings panel again.



• The Microphone status events get dispatched when a user changes a Microphone setting within the settings panel. ( _mic.addEventListener(StatusEvent.STATUS, onMicStatus); )
• On your Microphone class, the “muted” property will tell you if you have access to the microphone or not.

These tips can be adapted for the camera settings panel as well.

A little while ago I posed the following question to the flexcoders mailing list,

I just wanted to ping everyone and get their opinion on something. Why would anyone ever want to use the include directive? I’ve recently been working on poorly designed project where at the top of every module there is an “include Header.as” statement that has 30 include statements within it. To give a datagrid additional functionality, you give it an id=”myDataGrid”, and the include statement takes care of the rest. It’s really bad.

I just don’t see a good use for the include statement anymore. In my opinion, it just promotes bad programming practices.

I mean, can’t everything be taken care of using OOP methodologies? Thoughts?

I’d like to thank everyone who responded, you all gave me quite a bit of insight.

After thinking about this for a while now, here is my list of the common reasons people incorrectly use include (include directive).

I have common functionality that I want shared across multiple components.

That’s great that you’re using DRY philosophy! However, it’s much better to combine the DRY philosophy with object-oriented programming practices. Instead of using the include directive, abstract out common functionality into a parent class. Then you can create children of your parent component, and add additional functionality as needed.

I’m building a framework.

Great… don’t use include. See above reason.

I want to use Code-Behind.

Ted Patrick wrote a wonderful post on Code-Behind in Flex 2. He accomplishes Code-Behind, and does so in an object-oriented manner without using include statements.

Adobe doesn’t natively allow multiple inheritance in AS3, and using the include directive is the only way to fake it.

Frankly, if you understand that statement… you’re advanced enough to know what you’re doing, and you don’t need this tip.

== Conclusion ==

There are rare occasions where include is exactly what you need. However, if you still feel you have a valid reason to use the include directive on a regular basis, please leave a comment below and explain yourself.

A wise Adobean once told me to use try / catch / finally statements sparingly. It didn’t mean much to me at the time since I honestly don’t use them very often. Instead, I opt to check conditions prior to executing “at risk” statements.

So… here’s my advice that when it comes to try / catch statements.

Preventing errors from occurring is far better than generally handling them.

Take a look at this example.

var goodObj:Object = {foo: "bar"};
var badObj:Object = null;
 
tryErrors(goodObj);
tryErrors(badObj);
 
function tryErrors(obj:Object):void {
 
	// DO THIS
	if(obj)
		trace(obj.foo);
	else
		trace("doing something else");
 
	// NOT THIS
	try {
		trace(obj.foo);
	} catch (e:TypeError) {
		trace("error occurred");
	}
 
}
 
/*** OUTPUT ***************
bar
bar
doing something else
error occurred
***************************/

Do not use blanket try / catch statements.

You gain nothing by catching an exception that your application can’t deal with at that point.
For example, if you’re trying to convert a string to a number, and you know it might fail, but you have a default value, you should catch the exception, set the default value, and allow execution to continue.

Another example, if you try to call a Web Service and the call fails, and that particular call isn’t critical to your application, you could catch the exception, warn the user that some information is not available, and continue execution.

Only use try / catch when you have to.

I don’t have any specific benchmarks, but I do know that using excessive try/catch statements will degrade performance of your flash application. Probably because Flash Player is single threaded, but an Adobe person would probably have more information on that than I do.

An application I worked on a while ago used a try catch block around every single function… not my fault, it’s code that I inherited… anyways, it’s performance and execution times were horrendous.

Mike Chambers has a blog post asking, “How can adobe make the as3 learning curve easier”?

As I talked about in my Why YOU should contribute to Flex post, Adobe wants our input. Here they are again asking the community, “What do you think”?

I commented on Mike’s post.

I think that a more centralized component library and delivery system would make the lives of many developers much easier.

Take RubyGems for example. It’s extremely easy for developers to benefit from the work of others. This has increased the value of Ruby in my eyes tenfold.

As a developer, there isn’t a uniform place that I can go check to see if someone has done this before. So I have to scour the net for a while trying to find a solution by looking through blogs, articles, googlecode, etc…

I know there are a few places out there that make this easier. RIAForge, Adobe Developer Connection, Project Sprouts, Adobe TV, flexcoders.

Most of these sites (blogs especially), have a way to externally interact with them. I think that an Adobe sponsored site or program that would allow a developer to quickly see what’s out there would be an amazing asset to brand new ActionScript developer and veterans alike.

However, I didn’t realize until now, that Adobe is already doing this. This dream “site or program” does exist as the Tour de Flex. Which if you haven’t installed yet, I highly recommend it.

As the title of this post says, it’s no rubygems (not yet anyways)… but it’s a start. Go Adobe!