Difference between revisions of "Leapster Explorer: Play Your Own Flash Games"

From eLinux.org
Jump to: navigation, search
(Developing)
Line 134: Line 134:
 
The LX uses Flashlite 3.1 For The Digital Home, which is a version meant for System On a Chip hardware. Unlike the Mobile version which is for mobile phones and those such devices. With Digital Home, the hardware vendor uses the source, in conjunction with Actionscript Extensions. The Extensions are to provide the Flashlite player with specific access to items on the hardware. If this was a media set top box, then it could be used to give Flashlite access to a volume circuit or the ability to change channels. Essentially an AS file is created, that is similar to a C++ header file, which is imported into the Flash app during development. The hardware vendor also creates a corresponding C++ file with the actual working code in it, which is compiled along with the Flashlite player from the Adobe provided source code. Which unless you're a company with a good pitch, you probably won't be getting any time soon. Thus leaving you needing to reverse engineer the added functionality of the hardware you are trying to develop Flash for. If it is the LX you would surely want to be able to exit your Flash app with out having to shut down your device. There may very well also be some other features you would like to incorporate, if you planned on creating your own User Interface, or application that needs lower level hardware access. I will explain the process to incorporating any functions you may find, that you would like access to in your Flash app.
 
The LX uses Flashlite 3.1 For The Digital Home, which is a version meant for System On a Chip hardware. Unlike the Mobile version which is for mobile phones and those such devices. With Digital Home, the hardware vendor uses the source, in conjunction with Actionscript Extensions. The Extensions are to provide the Flashlite player with specific access to items on the hardware. If this was a media set top box, then it could be used to give Flashlite access to a volume circuit or the ability to change channels. Essentially an AS file is created, that is similar to a C++ header file, which is imported into the Flash app during development. The hardware vendor also creates a corresponding C++ file with the actual working code in it, which is compiled along with the Flashlite player from the Adobe provided source code. Which unless you're a company with a good pitch, you probably won't be getting any time soon. Thus leaving you needing to reverse engineer the added functionality of the hardware you are trying to develop Flash for. If it is the LX you would surely want to be able to exit your Flash app with out having to shut down your device. There may very well also be some other features you would like to incorporate, if you planned on creating your own User Interface, or application that needs lower level hardware access. I will explain the process to incorporating any functions you may find, that you would like access to in your Flash app.
  
First you will need to figure out what functions are available, Google should provide you with plenty of answers on how to accomplish this task.
+
The function are listed in plain text in the Plugin binaries, on your LX look in /LF/Base/Flash/plugins, you will find AppManagerPlugin.so CYOPlugin.so etc. I used Notepad++ to open these, its a text editor, and while you will see a bunch of garbage, if you scroll down thru the file, you will see some plain text, of what look like some function names. AppManagerPlugin.so happened to have the exit function in it popApp. I will take some figuring out, popApp sounds like taking an element out of an array, there was also pushApp. You may also want to check the log file found in /LF/Base/FR/ as I did a search for popApp after it didn't work I found a reference to a kPopApp, after some fiddling with the name it turned out to be PopApp() a capital P instead of lower case. Also in the binary you should find the plain text LF.AppManager, this turns out to be the name of what you will import into Flash.
  
Next you will need to create the Class for your functions. Lets say you're hardware is called the Darn Spiffy, and you figured out the class that contains the function you want, is lets say some cutesy name like Lawyer, as it manages what can and can't be done. And of course the actual function that interacts with the hardware side of the Flashlite player, lets say, feature_unload(). So you will probably find calls in your example source code like DS.Lawyer.feature_unload(); So to create what you need to import this into your AS file. You will created a folder in your project directory called DS, inside this directory, create a file called Lawyer.as. Open this file in a text editor or what ever you prefer, and include this in it.
+
So now that we have our information, lets build the file needed by Flash to use the LF exit function, instead of that nasty crash back to the UI way. Create a folder in your project directory named LF/ inside that file create a file named AppManager.as then open it with your favorite text editor and put in
  
   intrinsic dynamic class DS.Lawyer
+
   intrinsic dynamic class LF.AppManager
 
   {
 
   {
  public static function feature_unload():Void;
+
public static function PopApp():Void;
 
   }
 
   }
  
Intrinsic tells it that this file just basically has the prototypes of the functions, dynamic allows the objects to be changed, and won't do strict type checks. [http://www.adobe.com/devnet/devices/digital_home/as_extensions_flash_lite_digital_home.pdf AS Extenions for Flashlite Digital Home] This file will explain it much better. I went with Dynamic simply because this is going to take some trial and error. Looking at your example code, should give you some clues as to what sort of data is expected or is sent. Create an entry for each function you would like access to, and put this in the Actions/Actionscript file of your Flash project.
+
Intrinsic tells it that this file just basically has the prototypes of the functions, dynamic allows the objects to be changed, and won't do strict type checks. [http://www.adobe.com/devnet/devices/digital_home/as_extensions_flash_lite_digital_home.pdf AS Extenions for Flashlite Digital Home] This file will explain it much better. I went with Dynamic simply because this is going to take some trial and error. Looking at your binary in a text editor, should give you some clues as to what sort of data is expected or is sent. Look for things like function_arg(%s) or function_return() %s. Its a bit cryptic but with some practice, you should be able to decipher some of it. Create an entry for each function you would like access to, and put this in the Actions/Actionscript file of your Flash project.
  
   import DS.Lawyer;
+
   import LF.AppManager;
  
Which will make the feature_unload() function available in your application, and allow the swf to compile with out complaint. Things I noted while trying this out, the compiler complained the function wasn't static, you may want to play around with it. Tho noted in the linked document, private is not appropriate, as all of that will be taken care of in the C++ files.
+
Which will make the function PopApp() available in your application, and allow the swf to compile with out complaint. Things I noted while trying this out, the compiler complained the function wasn't static, you may want to play around with it. Tho noted in the linked document, private is not appropriate, as all of that will be taken care of in the C++ files themselves.
  
This is a rather generic explanation of the process, and should be applicable to all SoC's that use Flash in a standalone fashion for their UI or other features. And of course, check with the manufacturer on the legality of what you are attempting, so think before you leap. Some good resources I found linked to on the internet, explaining Adobe Flashlite for Digital Home.
+
This is a rather generic explanation of the process, and should be applicable to all SoC's that use Flash in a standalone fashion for their UI or other features. And of course, check with the manufacturer on the legality of what you are attempting or more importantly, how you are doing it, so think before you leap, least you want some trouble. Some good resources I found linked to on the internet, explaining Adobe Flashlite for Digital Home.
  
 
[http://www.adobe.com/devnet/devices/digital_home/flash_lite_digital_home_getting_started.pdf Getting Started with Flashlite Digital Home]
 
[http://www.adobe.com/devnet/devices/digital_home/flash_lite_digital_home_getting_started.pdf Getting Started with Flashlite Digital Home]

Revision as of 18:31, 3 August 2010

This how-to will show you how to load your own flash swf files on to the Leapster Explorer and play them from the standard User Interface. This solution is very very beta, proceed to the Problems section before experimenting with this, it does not work 100% and will require some trial and error to find flash files that work well with the Explorers range of inputs.


Programs Needed

SFTP Client, SFTP on your LX

Text Editor


Software Needed

Flash swf file. Must be made with ActionScript2 and Flash 8 at the lateest, since this is what Flashlite supports.

The leaplet game folder from Leapfrog


Configuring the Folder

First you need to find a suitable flash swf file, look for older games online, this can be hit or miss really, finding AS2 Flash8 files, that also lend themselves to being used on the Explorer. The touchscreen acts like a mouse and mouse button push, if your game requires aiming and clicking, instead of moving the mouse and clicking, you will simply click where you desire, which may or maybe not hinder game play. The other buttons provide input also, it may take a few tries to get a feel for good flash interactive flash files for the Explorer.

Using your free leaplet card, download one of the games, I happen to kind of like, Leapfrog's Wheel Works.

Once downloaded you'll find it in C:\Documents and Settings\All Users\Application Data\Leapfrog\LeapFrog Connect\LeapsterExplorer\LST3-0x00180004-000000.lf2 extract the folder with 7zip or similar.

Go into the folder, then open up your text editor, you'll need to modify the GameInfo.json file. This is the text used in the Explorer UI for the names of the games. Change Title to something relevant to your file, and close and save the file. Now, delete loader.swf and main.swf and copy and paste your flash file into the folder, renaming it loader.swf. You'll probably want to modify the icon files in some way, to make it easier to spot your flash file from the menu, save them as 8bit PNG files. You could also modify the mp3 file to something relevant if you wanted also. Finally rename your folder to something like My_Flash.


Loading the Files

Open up your ssh program and navigate to /LF/Bulk/ProgramFiles on your Explorer. And upload your folder.

Now eject your Explorer, pull the usb cable out, and let it refresh to the main UI, you might have to scroll the screen over, but you should see your new flash file there. If all went well, you can tap on it, and it should start playing.


Problems

Screen goes black, and returns to Explorer UI

- Flash file is newer than ActionScript2.

- Flash file is made for a Flash Player greater Flash 8.

- Flash executed a command that is not available in Flashlite, certain filters, web links, etc.

Controls not responding, or missing

- game or interactive elements not compatible with the limited inputs of the Explorer.

No way to exit Flash

- This is to my knowledge unavoidable with random Flash files, see the Example for how to deal with it on your own files.

Flash runs very slow

- Common problem with games that have a lot of movement or complex physics or any other processor intensive code.


Example Flash App

This assumes previous knowledge of Adobe Flash.

Document:

Width: 320

Height: 240

12 Frames Per Second

Publish Settings:

Flash Player 8

ActionScript 2

This sample will print the OS Name, Player version and will capture input codes and print them to the stage which you can use to control the games from LX input. On the state create two labels and a button. Create three labels text_version, text_keypress and, text_stylus, name the button button_exit.

On the first frame add this for the Actions

 // get version from player
 version = eval("$version");
 // player info vars
 var os_type;  
 var version_array;
 var major_version;
 var major_revision;
 var minor_version;
 var minor_revision;
 // split up version info
 os_array = version.split(' ');
 os_type = os_array[0];
 version_array = os_array[1].split(',');
 
 // populate version vars
 major_version = version_array[0];
 major_revision = version_array[1];
 minor_version = version_array[2];
 minor_revision = version_array[3];
 // populate text_version label
 text_version.text = "Version Info: \n" +
 "OS Version: " + os_type + "\n" +
 "Major Version: " + major_version + "\n" +
 "Major Revision: " + major_revision + "\n" +
 "Minor Version: " + minor_version + "\n" +
 "Minor Revision: " + minor_revision + "\n";
 // populate initial text_keypress label
 text_keypress.text = "Key Press Code:\nKey ASCII Code:";
 // set up key press event listener and function
 var key_listener:Object = new Object();
 key_listener.onKeyDown = function() {
   text_keypress.text = "Key Press Code: " + Key.getCode() + "\n" +
   "Key ASCII Code: " + Key.getAscii();
 };
 Key.addListener(key_listener);
 // capture stylus position
 text_stylus.text = "Stylus: \nX: 0\nY: 0";
 onEnterFrame = function() {
  text_stylus.text = "Stylus: \nX: " + _xmouse + "\n" + 
  "Y: " + _ymouse;
 };


For the button change its label to exit and add this to the Actions. The LX Flash player can not handle getURL this will cause the app to error, which will make the LX return to its main menu. So far the only way I've figured out how to do this, as the exit routine I believe is actually in the none standard player, which is common with Flashlite.

 // on key press make Flash error
 on(release){
   getURL("error_out");
 }

Make sure your settings are to Flash Player 8 and ActionScript 2 and publish your file, saving it as loader.swf. Populate the game folder with the necessary files and changes to meta.ini and gameInfo.json. Then load them onto your LX. If all went well, you should see the Flash Player version and OS type. Now press the stylus on the screen and move it around, you will its X and Y coordinates at the bottom.

Developing

The LX uses Flashlite 3.1 For The Digital Home, which is a version meant for System On a Chip hardware. Unlike the Mobile version which is for mobile phones and those such devices. With Digital Home, the hardware vendor uses the source, in conjunction with Actionscript Extensions. The Extensions are to provide the Flashlite player with specific access to items on the hardware. If this was a media set top box, then it could be used to give Flashlite access to a volume circuit or the ability to change channels. Essentially an AS file is created, that is similar to a C++ header file, which is imported into the Flash app during development. The hardware vendor also creates a corresponding C++ file with the actual working code in it, which is compiled along with the Flashlite player from the Adobe provided source code. Which unless you're a company with a good pitch, you probably won't be getting any time soon. Thus leaving you needing to reverse engineer the added functionality of the hardware you are trying to develop Flash for. If it is the LX you would surely want to be able to exit your Flash app with out having to shut down your device. There may very well also be some other features you would like to incorporate, if you planned on creating your own User Interface, or application that needs lower level hardware access. I will explain the process to incorporating any functions you may find, that you would like access to in your Flash app.

The function are listed in plain text in the Plugin binaries, on your LX look in /LF/Base/Flash/plugins, you will find AppManagerPlugin.so CYOPlugin.so etc. I used Notepad++ to open these, its a text editor, and while you will see a bunch of garbage, if you scroll down thru the file, you will see some plain text, of what look like some function names. AppManagerPlugin.so happened to have the exit function in it popApp. I will take some figuring out, popApp sounds like taking an element out of an array, there was also pushApp. You may also want to check the log file found in /LF/Base/FR/ as I did a search for popApp after it didn't work I found a reference to a kPopApp, after some fiddling with the name it turned out to be PopApp() a capital P instead of lower case. Also in the binary you should find the plain text LF.AppManager, this turns out to be the name of what you will import into Flash.

So now that we have our information, lets build the file needed by Flash to use the LF exit function, instead of that nasty crash back to the UI way. Create a folder in your project directory named LF/ inside that file create a file named AppManager.as then open it with your favorite text editor and put in

 intrinsic dynamic class LF.AppManager
 {

public static function PopApp():Void;

 }

Intrinsic tells it that this file just basically has the prototypes of the functions, dynamic allows the objects to be changed, and won't do strict type checks. AS Extenions for Flashlite Digital Home This file will explain it much better. I went with Dynamic simply because this is going to take some trial and error. Looking at your binary in a text editor, should give you some clues as to what sort of data is expected or is sent. Look for things like function_arg(%s) or function_return() %s. Its a bit cryptic but with some practice, you should be able to decipher some of it. Create an entry for each function you would like access to, and put this in the Actions/Actionscript file of your Flash project.

 import LF.AppManager;

Which will make the function PopApp() available in your application, and allow the swf to compile with out complaint. Things I noted while trying this out, the compiler complained the function wasn't static, you may want to play around with it. Tho noted in the linked document, private is not appropriate, as all of that will be taken care of in the C++ files themselves.

This is a rather generic explanation of the process, and should be applicable to all SoC's that use Flash in a standalone fashion for their UI or other features. And of course, check with the manufacturer on the legality of what you are attempting or more importantly, how you are doing it, so think before you leap, least you want some trouble. Some good resources I found linked to on the internet, explaining Adobe Flashlite for Digital Home.

Getting Started with Flashlite Digital Home

Developing Apps for Flashlite Digital Home

AS Extenions for Flashlite Digital Home

Optimizing Flashlite Digital Home