Category Archives: Tutorials

tutorials

Starling Stress Test/Benchmark of 1,000 Particles

Starling Stress Test

Starling Stress Test

The other day while working on a project we needed to gauge the speed of AIR on mobile, and to do so we created a stress test to see just how fast the latest AIR 3.6 SDK was. We created a small AIR application using Starling and decided to share it with the community. The application creates 1000 particles which are emitted by two emitters, one produces 500 Cowlorful Cows and the other 500 GrindheadGames logos. It seems to run at a solid 30FPS on a Samsung Galaxy S3 and an Apple 4S, however we would love to hear performance reports from other mobile devices, so please leave a comment if run the test yourselves.

We have made a GitHub repository for the Starling Benchmark so that you can download the code and run it yourself. Instructions are included how to get the project to compile, but leave a comment if you get stuck. There is also a precompiled APK in the build folder, so you can run the test on Android without having to compile if you want to. You will have to set up development certificates to get the application to compile for iOS, there is no precompiled file for the platform included.

We created used the Starling framework and the Particles extension to run this, make sure you add them to the source path to build the project.

Enjoy!

Working with Full Screen mode in AS3

When working with fullscreen mode in AS3, there are a few things to take notice of when developing applications.

For fullscreen mode to be enabled, the allowFullScreen tag in the embed has to be set to true for Flash Player to be able to display in full screen.

<object> 
    ... 
    <param name="allowFullScreen" value="true" /> 
    <embed ... allowfullscreen="true" /> 
</object>

When working with fullscreen mode, applications are often a lot less confusing if a full screen button is only displayed if the application can actually display in full screen mode.
To check if full screen mode is available to Flash Player, you can check the stage Boolean property stage.allowsfullScreen(). If true, fullscreen mode can be used and a button to enter full screen mode can be shown to the user for example. To check if full screen mode can be used, use the following:


if(stage.allowsFullScreen())
{
 //full screen code here
}

Fullscreen mode can also only be turned on by a user interaction, the user has to have pressed a button for the change to take place. It is not possible in Flash Player to automatically force the user into fullscreen mode, and the user must trigger the change. In Adobe AIR applications, it is ok to automatically load an application in full screen mode.

You can add an event listener for when a application enters or leaves full screen mode. This is how to create an event listener for that event:

import flash.events.FullScreenEvent; 
 
function handleFullScreenEvent(event:FullScreenEvent):void 
{ 
    if (event.fullScreen) 
    { 
      //handle fullscreen mode
    } 
    else 
    { 
        //handle normal mode
    } 
} 

clip.stage.addEventListener(FullScreenEvent.FULL_SCREEN, handleFullScreenEvent);

Finally, setting stage.fullScreenSourceRect can greatly increase performance of projects running in full screen mode. This makes the Flash Player render the project using hardware, rendering the display stack as an upscaled bitmap instead of scaling the vector artwork. The result is much faster render speeds and a performance increase, however it can look a little blurry.

stage.fullScreenSourceRect() is a rectangle, and which is used to specify an area of the screen to upscale as a bitmap in fullscreen mode. It normally makes sense to set this to the screen size of your minimised stage size, with an x and y position of 0. For example:

stage.fullScreenSourceRect = new Rectangle(0,0,stage.stageWidth,stage.stageHeight);

More information about working with fullscreen mode in AS3 can be found on the Adobe docs here.

** Update **

I have found when embedding flash content in HTML pages and using the fullScreenSourceRect property. I am using a Macbook Pro and Flash Player 11.5 in Chrome, and have tested the problem with older versions of Flash Player also. When using fullScreenSourceRect, you can upscale fine when in fullscreen mode in the projector and in the browser. However in the browser when you exit full screen mode and return to normal the Flash Player has a terrible time of things and the display gets really confused. The sampled image and the scaled image can be seen at the same time, and there seems to be no fix for this bug. Even setting the fullScreenSourceRect to null does not work. I have emailed Adobe about this problem and will post up their response when or if I receive one. Fingers crossed this can be fixed as we are wanting to use this feature in Enola: Prelude!

Leaving fullscreen mode can leave both renders visible with fullScreenSourceRect

Leaving fullscreen mode can leave both renders visible with fullScreenSourceRect

Loading external files with Adobe AIR

When creating Adobe AIR applications, you have the option of compiling resources into the output file. Accessing the location of the file in AIR can be slightly tricky however, and is not as simple as it is in Flash Player when run locally. To access a local file in Flash Player, you can normally make a new URLRequest() to the location of the file and it will work. In AIR, you have to use the File.as class to access the file location relative to a location within the operating system. While researching this topic, the first Google result was a post by Erik Phansen who wrote about the

file.documentsDirectory.resolvePath('eamplefileURL.jpg') 

method, and how it returns a location relative to the users Documents folder on their machine as a String. However, we think there is a more useful method which is

 file.applicationDirectory.resolvePath('examplefileURL.xml'); 

which returns a path relative to the location of the deployed application. For example, you can use TweenMax library to load in multiple items easily, using the following code:

 
var file:File = File.applicationDirectory.resolvePath("AppData.xml");
queue = new LoaderMax({name:"xmlQueue", onProgress:XMLprogressHandler, onComplete:XMLcompleteHandler, onError:XMLerrorHandler});
queue.append( new XMLLoader(file.url, {name:"appData"}) );
queue.load();

You need to write the missing event handlers, but you can easily add multiple items to the queue to extend it. This is great for creating AIR applications where you want to have text, images, video or other configuration that needs to be easily be adjusted post compilation.

AS3 Key Manager

Keyboard

Keyboard

I have written a small class that enables programmers to access which keys are pressed at any given time. Its particularly useful for game development when you want to move a sprite every frame for example.

The class is pretty simple and also quite small. The class contains an 2 dimensional array, and when the KEY_DOWN listener is fired the Key Code is stored into the array and a Boolean for that Key Code set to true. When the KEY_UP listener is fired, the Boolean relating to that Key Code is set to false.

To keep it simple, to use the KeyManager all you need to do is pass it an instance on the stage using an init method. As all the public methods are static, this can be done by:

KeyManager.init( stage );

To find out if a key has been pressed, you simply pass through a Key Code to the isKeyDown method. Fortunately, the Adobe libraries come with a list of Key Codes which can be found in the flash.ui.Keyboard class. We can use these with the KeyManager to easily access if a key has been pressed , like so :

KeyManager.isKeyDown( Keyboard.SPACE );

If the key has been pressed, the KeyManager will return true, else false. It is a pretty quick and easy way to work with the keyboard.
Here is the full code listing for the KeyManager:

package com.grindheadgames.input
{
	import flash.display.Stage;
	import flash.events.KeyboardEvent;

	public class KeyManager
	{
		//a reference to the stage
		private static var stage:Stage,	
		//an array of pressed keys
		lib:Array = [];
		
		public function KeyManager()
		{
			
		}
		
		/**
		 * initilise the KeyManager
		 * 
		 * @param s a reference to the Stage.
		 * 
		 */		
		
		public static function init(s:Stage):void
		{
			stage = s;
			
			stage.addEventListener(KeyboardEvent.KEY_DOWN, handleKeyDown, false,0,true);
			stage.addEventListener(KeyboardEvent.KEY_UP, handleKeyUp,false,0,true);
		}
		
		/**
		 * destroy the KeyManager and free up memory for garbage collection. 
		 */		
		
		public static function destroy():void
		{
			stage.removeEventListener(KeyboardEvent.KEY_DOWN, handleKeyDown);
			stage.removeEventListener(KeyboardEvent.KEY_UP, handleKeyUp);
		}

		/**
		 * handler for the KEY_DOWN event 
		 * @param e KeyboardEvent
		 * 
		 */		
		
		private static function handleKeyDown(e:KeyboardEvent):void
		{
			lib[e.keyCode] = true;
		}
		
		/**
		 * handler for the KEY_UP event
		 * @param e KeyboardEvent
		 * 
		 */		
		
		private static function handleKeyUp(e:KeyboardEvent):void
		{
			lib[e.keyCode] = false;
		}
		
		/**
		 * Use this method to determine if a key is down.  
		 * 
		 * @param keyCode Use the flash.ui.Keyboard class to determine if a key is down. Example: KeyManager.isKeyDown( Keyboard.Space )
		 * @return Boolean if the key is currently down, will return true, else false. 
		 * 
		 */		
		
		public static function isKeyDown( keyCode:uint ):Boolean
		{
			return lib[keyCode] as Boolean;
		}
	}
}

To demonstrate using the KeyManager, I have made a small application which shows the keyboard manager being used to control a small car. I am currently writing a tutorial on the physics and techniques used to create the car, but in the meantime I have commented each line and uploaded a ZIP folder of the files. You can download it here:

Example KeyManager with TopDownCar.as Example.

The project is a Flash Builder project, but it should work with an FLA too if you set the Document class to TopDownCarExample.as and save the FLA in the src folder.