wasted potential

I have known for some time that I could generate an Actionscript API Reference for my own class packages using ASDoc, but it’s a command-line tool and I haven’t done any command-line programming in about 12 years, so I didn’t want to deal with the hassle. Then, I found this blog post by Derek Griggs where he created a batch file that he could simply run when he wanted to generate the docs. Genius! And since ASDoc comes packaged with the FREE Flex SDK, anyone can do this (well, almost anyone). The following instructions are for Windows users. Sorry Apple heads.

Step 1: Download the Free Flex SDK from Adobe here

Step 2: Unzip the downloaded file and place it somewhere logical on your hard drive. I placed it in the C:/Program Files/Adobe/ folder.

Step 2.5 (Optional): open the flex config XML file found here: [flex sdk folder]/frameworks/flex-config.xml and tweak your settings. For example, you may want to set the <strict> option to false.

Step 3: Open a simple text editor like Notepad and create the following file (or download the sample packet here and use the included batch file sample):

cls
set path=C:\Program Files\Adobe\flex_sdk_4.1\bin
asdoc.exe -source-path classes -doc-sources classes -window-title "Wasted Potential Sample AS Documentation" -main-title "Sample Documentation" -footer "This is a test<br/>www.wastedpotential.com" -output docs
pause

Step 4: Save this file as “asdoc.bat” in a folder one level up from your class package(s). For example, In my Flash projects, I usually have a folder named “classes” that contains all of my class packages, so I save this batch file outside of the “classes” folder. When I run the batch file, it will create a folder named “docs.”

Step 5: Modify the file as needed. The file is simple, but I’ll explain it piece by-piece:

cls

“Clear screen” removes any other output from the terminal window.

set path=C:\Program Files\Adobe\flex_sdk_4.1\bin

This sets the path where your computer can find the executable file you wish to run. In this case, it is the location of asdoc.exe. If you placed the Flex SDK somewhere else, you will need to set this path for your configuration.

asdoc.exe

Runs the ASDoc executable

-source-path classes
-doc-sources classes

Options that tell ASDoc where to find the classes it is documenting.

-window-title "Wasted Potential Sample AS Documentation"
-main-title "Sample Documentation"
-footer "This is a test<br/>www.wastedpotential.com"

These are more options. They simply set some text in the output files.

-output docs

This option specifies the folder where your new API will be created. If it doesn’t exist yet, ASDoc will create it. There are more options than this, but these are the important ones. Click here to check out some of the other options.

pause

This simply keeps the terminal window open. Without this line, the terminal window closes and you can’t view any error messages.

Step 6: Save the file again and double-click it to run it.

Step 7: Wait a few seconds until it is done running. If your classes have errors, the script will fail. Fix the errors and try again. If it succeeds, you will now have a full set of Actionscript API docs for your classes. Open them up and check them out.

Now, you can go add valid Javadoc-style comments to your classes and you will have a professional API reference for your project. Sweet! Don’t know how to add Javadoc comments? Well, I created a sample class package and batch file for you to play with. You can download the sample here. There are also lots of resources on the web for how to write Javadoc comments.

IMPORTANT: ASDoc is a bit touchy and fails A LOT when trying to generate an API. Here are a few caveats:

• Your classes must not have any compiler errors or ASDoc will fail.
• Your javadoc comment syntax must be correct or ASDoc will fail with a cryptic error about
  “toplevel.xml”
• You must declare stage instances explicitly. If you use Flash and have “Automatically declare stage instances” turned on in the Actionscript 3.0 publish settings, ASDoc will fail, throwing an error for each stage instance name in your classes that doesn’t appear in the variable declarations.
• Even more annoying, if you use any open-source packages like Papervision, their syntax must also be flawless, or ASDoc will fail (in fact, ASDoc failed for me when trying to run it on a project with the Papervision3D package). For large projects, this can be a huge pain. So, you may want to run ASDoc on any open-source libraries first to make sure they compile correctly by themselves.

If anyone knows how to modify these instructions for a Mac, let me know and I’ll update the post.

You can download the sample files here.

One of my main frustrations with Flash is the lack of useful error statements when I am testing a program. The compiler errors are okay – they catch my syntax mistakes and point out the location of the problem in my code (usually). Runtime errors , on the other hand, are an exercise in frustration. Flash usually provides cryptic runtime errors like “null object reference” and then gives me a vague hint about where the problem is in my code. Then, I spend lots of time adding trace statements to try to figure out where the code is failing. Once I know where the code fails, I can figure out why. I have constantly wondered why Flash can’t simply give me the exact location where the program crashed.

Well, one of my coworkers figured out how to get useful error statements from Flash the other day and I’m ashamed to admit that I didn’t know this (neither did he, and we’ve both been developing in Flash for over 5 years). In Flash CS3 or higher, simply open the Publish Settings and go to the Flash tab. One of the checkboxes on this tab says “Permit Debugging.” Enable this and Flash will tell you exactly where your program failed, so you can quickly track down why it happened.

As always, I’ve attached a quick example. The sample Flash file has a problem that will cause Flash to throw a runtime error. Compile it and note how it only tells you that the problem is in the actionscript on frame 1 (no duh). Now, change the publish settings to permit debugging and try again. This time, at the end of the error message, it will actually tell you the exact line of code where the program crashed.

Once you are finished testing your applications, you should probably turn debugging off before publishing your final SWF.

Download the sample file here.

Five3D is a compact Actionscript library that allows you to create 3D views quickly and easily. Much like Papervision3D, Away3D or Sandy, it allows you to create basic 3D graphics with Actionscript. Why would you use Five3D instead of one of these other libraries? Here’s a quick rundown of the advantages and shortcomings of Five3D  that I have found:

• Five3D has a stripped-down feature set. If you need to do something simple like move a large number of planes in 3D space, Five3D will be easier to set up than the other 3D packages. The drawback is that it doesn’t do many of the things that the other engines do, like providing built-in primitives or Collada imports.
• Five3D handles vector objects without first turning them into bitmaps. You can actually use Flash’s native drawing API to create vector shapes and move them in 3D while still retaining the vectors. This creates smoother renders than the other 3D engines, especially when scaling and rotating objects. The other 3D engines create bitmaps of textures and then map them onto the surfaces of objects.
• Five3D handles 3D text really well. You can convert fonts into vectors and then use them as 3D objects. This makes 3D text effects really simple.
• The default handling of bitmap textures is cleaner than Papervision. With Five3D, bitmap textures on planes map much more smoothly than with Papervision’s defaults. You can map textures just as well in Papervision, but it’s a little bit of a hassle to set up.
• The Five3D library is written to extend the native flash classes in a way that is really intuitive. For example, a MovieClip3D is just like a MovieClip, but it has additional features like a z-coordinate. Half the time, you can guess what properties each object will have without even looking them up in the docs.
• Five3D doesn’t use a camera object. Depending on your needs, this could be an advantage or a disadvantage. You can handle this by simply creating a Sprite3D container to hold all of your objects. Then, move the container to simulate camera movement. I often do this in Papervision projects anyway because of various issues I have had with the camera.

I have built a simple “Hello World” test of Five3D, which you can see below. It’s not very exciting, but it isn’t supposed to be. When I started playing with Five3D, I had a hard time finding a simple, stripped-down example that could get me started, so that is what I’ve built here. You can download the source files here. I have also added links to some more advanced tutorials and samples at the bottom of this post.

I did run into some weird Five3D quirks when I built this. First, when I created a MovieClip3D object and added it to the scene, it wasn’t appearing on stage. I traced all of the properties and everything indicated that it was on the stage, but it was not displaying. I Googled around a bit and found this website with the answer: you have to call the activate() function for MovieClip3D objects to get them to render on the stage. I don’t understand why you need to do this, but it fixed my problem.

The other quirk that you need to know about is that you have to turn on z-sorting. By default, it z-sorts according to your addChild() calls, just like regular MovieClips. If you don’t need z-sorting, just add the 3D items in the correct sequence. I’m guessing that this helps to optimize the code. If you need your objects to spin in 3D space, you can turn on z-sorting with the childrenSorted property (check out the example source code for usage).

Thanks to Mathieu Badimon for this amazing Actionscript package.

Links:

Download the source files for the example above

A 3D text sample with source code

A simple example of Five3D with source code

A fun Five3D experiment

A tutorial on building a 3D photo album with Five3D

Info on integrating Five3D with Jiglib physics

As I have made the transition to AS3 class-based programming, I have built a package of useful classes that handle functionality I need all the time. For example, I have a class that handles the basic rollover functionality for a button. Rather than write this code over and over, I made a class that takes care of it. That’s the main benefit of working in classes – things become more modular and you (theoretically) spend less time building repetitive code. I am always looking for good code to add to my core package of classes and the following two classes definitely fit the bill. I use them all the time and I thought I’d help more people locate them:

getURL:
One of the biggest hassles in AS3 is writing 10 lines of code to accomplish the same thing that you can do with one line in AS2. The getURL() function was killed in AS3. Now you need to set up a URLRequest… it’s a hassle. Well, Actionscript guru Senocular has created a getURL() class that mimics the behavior of the AS2 function. simply add the class to your import statements and then use it just like you did in AS2. Grab it here.

Pixel Perfect Collision:
One of the more annoying problems with Flash is that collision-detection has never lived up to its promise. In AS2, the hitTest() function only allowed you to check if the bounding boxes of 2 objects were touching. This worked great if all of your graphics were rectangular, but it often registered a collision between objects that, visually, looked like they were still pretty far apart. Grant Skinner was the first person to solve this problem with his AS2 collision-detection code. His original code was then ported to as3 by Boulevart. I had been using that code for projects, but it had a few shortcomings – it didn’t work for rotated or scaled objects and both objects had to share the same parent. I was just recently contemplating an update to the AS3 Collision class to fix some of these issues when I found an updated version by Troy Gilbert. It not only handles rotated and scaled objects, but he has optimized the code and removed the constructor (which was really unnecessary anyway). You will definitely want to get his PixelPerfectCollision class.

That’s all for now. If you’ve found any other classes that you use all the time, leave a comment and let me know.