My Blog

If you ever wanted to add joystick input to your Flash project, a quick search probably told you it is impossible. This is because Flash does not have any built-in features to access game controller input. However, a new feature added in AIR 2.0 allows Flash projects published to AIR to interface with custom executable, so that's what I made.

JoyQuery is my own Windows C++ program that outputs joystick states through standard output for up to 16 joysticks.

While its intended purpose is AIR applications, it does not require AIR to run and can be used without AIR.

 

Downloads:

• Source Files (A sample project you can test in Windows Flash CS5 or higher.)
• Example Application (See it in action. A published version of the Source Files above.)

 

How to use JoyQuery in your own projects:

1. Download the Source Files above.

2. Copy "joyquery.exe" into your project folder (remember to include the file in the publishing) and the "extension" folder into your ActionScript source folder.

3. Your application profile must be Extended Desktop. Add the following code to your application's XML descriptor file between the root ("application") tags.<supportedProfiles>extendedDesktop</supportedProfiles>

4. Import and construct the extension class with the following code:

/*Import the class.*/
import extension.JoyQuery.Joystick;
/*Create Joystick object variable. For this exmaple I used "joy" for the variable.
The first argument to the new Joystick() function must be the main document object.
The second argument must be the path to the JoyQuery executable relative to the main file.*/
var joy:Joystick = new Joystick(this, "joyquery.exe");

5. Now you have access to a full set of function for interfacing with the JoyQuery executable (example of how to call the functions "joy.init();"). These APIs are:

init([speed])

This function starts the JoyQuery executable. The speed Number argument is optional. Specifies the delay in seconds between JoyQuery output. Lower number means better performance, but higher CPU. If no argument or "auto" is specified, the class will create a delay the same as or slightly faster than each frame.

kill()

Kills the JoyQuery executable. No need to kill the process on close out of the application, the class does this automatically.

isReady()

Return true if JoyQuery has output data since it was started, false if it has not or has been killed.

getTotal()

Returns a number of the total joysticks JoyQuery is outputting states to.

buttonIsDown(joystickNum, buttonNum)

Argument 1 is the joystick number to check (0-15 with 0 the first). Argument 2 is the joyStick button number to ckeck is down (0-? with 0 the first). Returns true if down, false if not.

getAxis(joystickNum, axisNum)

Argument 1 is the joystick number to check (0-15 with 0 the first). Argument 2 is the joyStick axis number to ckeck is down (0-? with 0 the first). Returns -1 - 1 (i.e. left [-1] to right [+1]) or 0 if not available.

getTotalButtons(joystickNum)

Argument is the joystick number to check (0-15 with 0 the first). Returns the number of buttons on the joystick.

getTotalAxes(joystickNum)

Argument is the joystick number to check (0-15 with 0 the first). Returns the number of axes on the joystick.

 

Technical Notes:

The AIR project must be published as a native Windows installer (.exe) not a .air.

The JoyQuery executable is machine code, so it does not require any additional software to run. It may, however, require DirectX be installed on the users machine.

JoyQuery may also work with other game controllers.

As of this point, JoyQuery is Windows only. Mac and Linux ports should be possible, but I would require funding to pursue it. If interested, contact me, we'll talk.

This is free software. You may copy, reuse, and redistribute this program freely provided that it remains unaltered. This includes commercial use.

While not necessary, I would appreciate any credit given to me and, if published in an application, if you would tell me what project you have used it in.