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.

Today I found a cool button that I wanted to use in my Flex application.

The button (roll your mouse over me):

The thing about this button is that it has complex roll over and roll out animations. Of course we could create the same thing within Flex using an ActionScript tween class… but some things are better left to the Flash timeline.

So how do we get our button into Flex, with all of its animation and interactivity intact? The answer, my friends, is to use Adobe’s Flex Component Kit.

Doing some research online, it’s not really clear where to get it, or how to use it. According to labs, it’s released within Flex 3… but I don’t have a clue where. So we’re going to do this my way…

Step 1 : Install Adobe Extension Manager 2.1

Obviously, you can skip this step if you already have Extension Manager 2.1 installed.

If you didn’t install the Adobe Extension Manager when you installed your copy of CS4, you can download it here —> Download Adobe Extension Manager

If you already had Adobe Extension Manager installed… just be sure it has been updated to version 2.1.

Download and open up Setup.app

Click Next

Let it run

You’re welcome Adobe

Extension Manager > About Extension Manager

Says 2.1… cool, we’re ready to move on to step 2.

Step 2 : Install the Flex Component Kit

Now we need to go download the extension —> Download the Flex Component Kit (you need an adobe.com account)

All the way at the bottom you’ll find the extension we’re looking for… Flex Component Kit for Flash CS3 Professional (I know it says CS3 and we’re working in CS4, don’t worry)

Once downloaded, unzip and double-click FlexComponentKit.mxp

Read this whole agreement and only if you agree the terms click “Accept”

…how many of you read that?

Okay, you should see this now.

Documentation for this component can be found here —> FCK Docs

Onward!

Step 3 : The Flash Side

Let’s take our button and load it into Flash. We’re going to name it “MyButton”.

Create an AS3 class to handle all of the button interactions we need

package {
	// MyButton
	import mx.flash.UIMovieClip;
	import flash.events.MouseEvent;
 
	public class MyButton extends UIMovieClip
	{
		public function MyButton()
		{
			super();
 
			buttonMode = true;
			useHandCursor = true;
 
			addEventListener(MouseEvent.MOUSE_OVER, onOver);
			addEventListener(MouseEvent.MOUSE_OUT, onOut);
		}
 
		public function onOver(event:MouseEvent):void
		{
			gotoAndPlay(1);
		}
 
		public function onOut(event:MouseEvent):void
		{
			gotoAndPlay("end");
		}
 
	}
}

Make sure you have MyButton selected in the Library, and then use Commands > Convert Symbol to Flex Component.

Your output panel will let you know the command worked properly.

Test the movie by pressing ⌘ + enter (ctrl + enter on the PC).

Publish the movie, which creates both a SWF and a SWC file.

Now that we have our SWC file, we’re ready to move into Flex Builder.

Step 4 : The Flex Side

Copy our newly create SWC file into our libs directory.

With the SWC in our libs directory, it will automatically be included in the classpath of our Flex application (see this tip for more information on the libs directory).

The SWC file includes the MyButton class, so we can now write our code:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
	xmlns:local="*" 
	layout="absolute" backgroundColor="0x000000" backgroundGradientAlphas="[0,0]" 
	creationComplete="onReady()">
	<mx:Script>
		<![CDATA[
			private function onReady():void
			{
				// How to use the custom button in ActionScript 
				/*
				var button:MyButton = new MyButton();
				button.x = 35;
				button.y = -10;
 
				addChild(button);
				*/
 
				// And just for fun				
				makeGrid();
			}
 
			private function makeGrid():void
			{
				var pad:int = 35;
				var gridWidth:int = 10;
				var gridHeight:int = 10;
				var yOffset:int = -45;
				var xOffset:int = -25;
 
				for(var h:int=1; h<=gridHeight; h++) {
					for(var w:int=1; w<=gridWidth; w++) {
						var button:MyButton = new MyButton();
						button.x = w*pad+xOffset;
						button.y = h*pad+yOffset;
						myPanel.addChild(button);
					}
				}
 
			}
		]]>
	</mx:Script>
	<mx:Panel id="myPanel"
		layout="absolute" left="10" right="10" top="10" bottom="10" 
		backgroundColor="#1D1D1D" title="Hey look, I'm a Flex Panel"/>
 
	<!-- How to use the custom button in MXML -->
	<!--<local:MyButton x="-5" y="-10" />-->
</mx:Application>

And here’s what it looks like:

Weeeeee…. that’s fun, you can download the source here.

The source there is an Archived Flex project, all you need to do is Import it into Flex Builder and you’re good to go.

That was a long tip, any questions please post them.

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.

Maybe you’re one of those people who say to themselves, I simply don’t have enough time to screw around with my own stuff… I’m way too busy… I need my insulin… I don’t know anything about math or physics. Well, cut the excuses and make the time! All it take is twenty minutes a day. Twenty minutes a day turns into more than 3 full work weeks a year. Don’t believe me? Here is the math:

20 minutes * 365 days / 60 hours / 8 hour work day = 15.2083 work days

If you’re like me, once you start experimenting those 20 minutes fly by, and before you know it your significant other is yelling at you that dinner is ready.

For example, it’s been snowing off and on here in Seattle. As I was gazing at the window watching the snow come down, I decided to try my hand at writing particle systems. Particle systems are something that have always intrigued me but I never could “find” the time. So instead of putting particles in the back of my mind (and ultimately never getting around to them), this weekend I researched and spent a few hours learning about particle systems. And I programmed this (move the mouse around):

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.

First a little background about me.

A little while back, I worked for a small startup named Snapvine. Snapvine currently has many widget offerings, one of which still gets loaded millions of times each week. These widgets are deployed across hundreds of social networks (who knew there were so many). As the lone flash developer in the company, it was my job was to create and maintain all of these widgets.

The great thing about Snapvine was that I was surrounded by brilliant people, we discussed the Flex framework in extraordinary detail, weighing the pros and cons of using such a framework in our widgets.

So that brings me to the whole point of this blog post… pros and cons for building widgets for the Adobe Flash Platform using Flex.

[Sidenote]

My experience in widget development was mostly focused on development for social networks, so I might say some things that may not apply to other types of widget development.

[/Sidenote]

– Pros –

Flex does a lot of the work for you

Flex does so much of the heavy lifting for us. If you’re ever bored, skim through the Flex documentation. It’s not uncommon for me to find things within the framework I didn’t know existed.

Also, If you haven’t already done so, I highly recommend picking up the O’Reilly Flex 3 Cookbook, or thumbing through it at your local bookstore. I’ve found some really great things in there that I didn’t know about the Flex Framework.

Flex allows quicker development time because there is less code YOU have to write.

Once again, Thanks Adobe… for doing my work for me.

RSLs decrease frequent loading time

The use of Adobe’s Runtime Shared Library significantly reduces multiple loads of your widget. This is because parts of the Flex Framework become cached inside the Flash Player itself. One of the big benefits of the framework RSLs is that not only your widget benefit from them. The framework is cached the first time ANY Flex content, on any site, using framework RSLs is loaded.

One caveat to Runtime Shared Libraries is that you have to configure your widget to utilize them during compilation. They don’t just get used magically. This also means that when you deploy the widget on your web server, you need to also upload and distribute the RSLs.

So if a user visits Picnik, which uses the Flex framework RSLs. Then the user visits a myspace profile page with your widget on it, they wouldn’t download the framework RSLs again (if you and picnik.com are using the same version of the SDK).

Myspace wants users to use Flash Player 9 and above

A while back Adobe and MySpace scratched each other’s back a little bit. Adobe added support for MySpace to disallow navigation events from flash widgets (allowNetworking=”internal”), and MySpace in turn highly recommend users to upgrade to Flash Player 9 (I’m pretty sure they also did this for the video support in Flash Player 9). Myspace did this by prompting users to update their Flash Player if they detected version 8 and below.

That’s a BIG pro for us widget developers, because that means the majority of our widget market is using a player with loads of the features we know and love. At the time of this writing, I’m unsure if MySpace is pushing Flash Player 10, I haven’t noticed it yet.

[Rant]

I’m currently writing this post aboard an airplane at 33,000 feet. Would the person who keeps passing gas, please knock it off, this is an enclosed air system for heaven’s sake.

[/Rant]

– Cons –

Flex is huge, comparatively

300 KB is still too big for dial-up. Many people argue that if people are using MySpace on dial-up, that they’re used to slow loading times. It’s not uncommon for a MySpace profile to be littered with hundreds of 100 KB photos, music, etc… However, that brings me to one of my main points.

By keeping your widget small, It’s more than likely going to load prior to other things on the profile. This is key for getting your brand out there. In Snapvine’s case, this meant that before pictures of friends, before the music players, before the slideshows… Snapvine’s logo was spinning on the page.

Bandwidth is expensive

If your goal if for your widget to go viral, bandwidth is something you should consider. It is bandwidth which drives how much money you are going to spend.

This calculator estimates how much it would cost if you were hosting your widget on Amazon S3 (US).

If you want a direct link… Widget Bandwidth Calculator
If you are curious, you can view the source.

Why is this a con? Using the Flex framework bloats a swf’s file size, and ultimately costs you more money, even if you are using Runtime Shared Libraries.

A simple application which is JUST a combo box, is still 56 KB, even when using Runtime Shared Libraries.

Flex was built primarily for Enterprise Development

This means that lots of the components within the framework, are pretty much useless within widgets. For example, using a datagrid to show massive amounts of data… not really a good use for a widget.

Remember, we’re talking about widgets, not about widgapplications (my spellcheck doesn’t like that word). Most widgets are fairly simple apps. Examples – a music player, slideshow, awesome video slideshow, small game, etc…

Keep your widget fairly simple, if it begins to become too complex, you should probably ask yourself, “Should I be building a 3rd party application (OpenSocial or FBML) instead of a widget?”

It’s hard to selectively use pieces of Flex

I’m not going to say that it is impossible, but loads of classes in the Flex framework are dependent upon each other. Which means that if you’re going to use one Flex class within your widget, it will import ALL of it’s dependencies, whether you use them or not.

– Nate’s opinion –

If I’m building a widget whose soul purpose is to go viral and be loaded millions of times a day, I’m going to write it in straight ActionScript.

Sure, it will take a bit more time, but in the end I’ll save money, have more granular control over my widget, and feel good about myself.

I’ve now realized that the only reason I’ve ever found what I needed was because someone was willing to share. I know, I know… you knew that already… sometimes I’m one taco short of a combination plate.

So here are the reasons why YOU should get involved with the Flex (and flash) open source world.

• The Adobe Team
• They’re asking for help!
• Take matters into your own hands
• YOU have a say
• You don’t have to be a programmer (or an expert programmer)
• FlexCoders Mailing List
• Flash isn’t going anywhere
• Conclusion

The Adobe Team

I had the opportunity to meet some of the Flex team. And let me tell you, these guys (and girls… ahmmm.. Deepa) really care about this project. I’ve never seen a group so devoted to what they do. If you’ve had the chance to read through the specs that the team is putting online. You will see how well thought out the SDK is.

It’s also not uncommon to see the Adobe team participating within the community. If you’re subscribed to FlexCoders, you’ll frequently see members of the Flex SDK team answering questions and making comments. They also answer questions on the Adobe forums. I’m pretty sure the team at Adobe already has a full plate. Yet, they still contribute to the community. They go above and beyond the call of duty. For example, as I’m writing this post at 10pm PST on a Sunday night, I’m watching Alex Harui answering questions on the FlexCoders mailing list. Thanks Alex.

They’re asking for help!

Most people don’t realize how easy it is to get involved with open source Adobe products. Everyone can (and should) sign up for the Bug and Issue Management System. It’s quick and easy to get setup.

If you’re a developer, become a contributor and submit patches. It’s actually much more painless than I thought it would be. I faxed over my Contributor Agreement and was approved within 20 minutes.

Take matters into your own hands

One thing that I have been guilty of in the past is complaining that the Flex framework, or Flash in general, is missing what I consider no brainers. I found myself saying, “Self, why on earth would the person writing the Date class not think that someone, somewhere would want to change the timezone offset”, or other types of complaints. I soon realized that, Nate you dummy, this is an open source project. Fix it yourself! (again… sometimes I’m slow). It hit me like a ton of bricks: If you build it, they will come… errr…. include it into the framework.

It’s more likely that a feature will be put into the framework if it’s already written for them. Heck, in my previous post I was amazed by how quickly my fix was committed to the code repository. Adobe wants us to help! Which is a great place to move on to my next point.

YOU have a say

YOU have a say! It’s our framework. Sure, maybe Adobe has the final say on most of these things. And sure, Adobe may mark your feature request as deferred. But you know what, since it is open source with a public issue system, you do have a say.

Every user within the Bug and Issue Management System has the option to vote on bugs and features. This isn’t a dictatorship. Adobe has given us to right to vote on issues, and if an issue is getting lots of attention from the community, they will look at it and likely fix it.

You don’t even have to be a programmer (or an expert programmer)

I know there are some of you out there who don’t write code, or people who simply think, “I’m not a good enough programmer to contribute to the SDK”. Well good news, you can be part of the revolution too! You have the ability to contribute quality to the Flex Framework and Flash Platform. Here are few ideas: Submit bugs, submit feature requests, correct spelling mistakes in documentation. Get involved!

In regards to bugs and feature requests, I cannot stress this enough. Before you submit a bug, please… PLEASE… verify that the bug (or feature) doesn’t already exist, do some research before you just willy nilly submit feature requests and bugs. It ends up being counter productive. Other people doing the research you’ve should have done now have to spend time cleaning up the issue system because of duplicates and other issues. Having said that, another thing that helps the community is to browse through the issue tracker looking for duplicates, or general cleanup of the issue tracker. If you find something that needs to be cleaned up you can report it to Adobe and they will take care of it.

Anything that reduces the time others have to spend wading through issues is a good thing. It means that the people who are writing fixes to the issues spend less time in the bug system, and more time fixing the issues themselves.

FlexCoders Mailing List

Now I should mention, that FlexCoders is not a mailing list that is controlled by Adobe. It was started by a group of developers within the community. I’ve been following the list for a very long time, and frankly it’s kind of annoying. I’ll be in the middle of typing out a response to a question, when gmail pops up to tell me the conversation has been updated. Maybe it’s just bad timing, but it always seems that someone else beats me to the punch.

Another great thing about FlexCoders is the people that post there regularly. I usually end up laughing over some debate or a nerdy joke that someone included in their response.

Flash isn’t going anywhere

Let’s be honest here, against Silverlight… and whatever Sun, Google, Apple and everyone else is cooking up, The Flash platform is here to stay. With a ~90% client install base, and a large development following. I don’t foresee Adobe taking their ball and going home.

So what does that mean for us developers? We have a stable, time tested platform to develop on. We don’t need to worry about the Adobe going under.

Conclusion

The last point that I want to make… I’m proud to be a Flash developer. Looking at code that I submitted now being part of the Flex SDK just makes a person feel good. I’m beginning to understand why the Adobe Team puts so much dedication into this platform. And I have to admit, that dedication and devotion is contagious.