[artlan]

Well, I asked Menneisyys about posting this, and was told to go ahead, so why not. One of my only posts here, and first time writing a guide for something like this so please bare with me.

Note: - Credit for the information in this guide goes out to Adolescent of HowardForums, UncleRUS, and the developers of JAM. I just compiled it in a more user friendly form with my own notes and shortcuts added.

Many people have complained before about installing this or that Java game on their phone, only to find that the keys partially work, or won’t work at all. Fear not! There is a way to solve this for those willing to put in a little effort and time.

There's no way to do it without modifying the game classes themselves (and inserting a bit of your own code), but the end result is well worth it. I’ve personally adapted well over 60 games for my Motorola E815, and then re-adapted them to work on my HTC Titan. I’ve included with this post a copy of the Keycode chart we compiled to aide in adapting these games.

In a nutshell, you must create a new class based on the javax.microedition.lcdui.Canvas (or GameCanvas, depending on what the game in question is using). Then you handle the keyPressed, keyReleased, keyRepeated, and getGameAction methods catching the PPC’s keycodes and passing the game class whatever keycode it's expecting.

For examples of what that means, refer to the post above this one. Thankfully, most java games use a standard template, and most JVMs for the phones, also use that template. (I know if a game runs fine in the Emulator I’ll be explaining, then it will work just as well on my Titan) If you haven’t yet, get a Midlet to show you your keycodes. I’ve included one in this post as well. Install it on your device and check what the directional keys/soft keys are. Chances are they’ll match up with either the “Emu” ones, or one of the other phones listed in the included chart.

Here's were the fun begins. Do not read beyond this if you don’t have patience, or the time to tinker and figure things out. You’ll only frustrate yourself.

Tools Used: (what I use)
Java SDK 1.5 (Or whatever the latest one is)
The latest JRE (Java Runtime Environment, free from Java’s website)
Sun Java Wireless Toolkit 2.5 for CLDC (free off the Java Website.)
Hex Editor (XVI32, freeware)
Archiver (WinRAR, trial version works fine)
JadMaker (Freeware)

So, first off, install everything. Personally, I kept it all in one spot, and made shortcuts to everything there so I could have my own little workspace.

Launch JadMaker, click and drag your Java game (the jar file) into it to get a proper working Jad file.

Launch the Java Wireless Toolkit, and go to “File” – “Create Project from Jad/Jar File”, and pick your new Jad.

This will create a folder with your games name in the “Apps” folder wherever you installed the toolkit. I installed mine to C:\Key Fixer\, so my path is “C:\Key Fixer\WTK25\Apps\<Game>\”

Click “Run” and give the game a shot, see if it works. Most games will work as is. You may get an error on same games about a missing “Nokia/mid/ui/FullCanvas.class” file. If you get this, refer to the “Other Notes” below.

Now we need to find out what class your game uses for its keys, and what style Canvas to use. So we switch over to XVI32.

After you load up XVI32, navigate over to \WTK25\Apps\<Game>\Classes. There may be a few, or there may be many. Don’t let it intimidate you. Start with the first class file, and do a search for “key”. If it doesn’t find any results, move on to the next. What your looking for are the keyPressed, keyReleased, or keyRepeated sections. Once you find a file with one or more of those, start over in that file and look for Canvas. You may find Canvas, or GameCanvas, and that will dictate what template to use. (Note: if you find BOTH Canvas and GameCanvas only work with the GameCanvas file.)

In the file your in, you need to make these changes now.

Search and replace: (case matters)

keyPressed
with
KEYPRESSED

keyRepeated
with
KEYREPEATED

keyReleased
with
KEYRELEASED

Now change one of the following.

If you’re working with “Canvas”,
javax/microedition/lcdui/Canvas
with
com/motoroladapter/patch/CANVAS

If you’re working with “GameCanvas”,
javax/microedition/lcdui/game/GameCanvas
to
com/motoroladapter/patch/game/GAMECANVAS


Once the changes are made, save the file and close the editor. Then copy the appropriate text file (canvas.java, or gamecanvas.java) into the \WTK25\<Game>\src folder. Open it with notepad, and make sure the key mappings match your findings for your device.

Back in the Wireless Toolkit program, click the “Build” button to compile the new class file, then click “Run” to test it out. This will load up a nice full phone emu, so play to your hearts content to make sure all is well. (This is also a great way to see if the game is one you’ll like before flooding your phone with it!)

Assuming everything is working okay now, use WinRAR to open the ORIGINAL .Jar file (NOT the one in the \WTK25\<Game>\Bin folder!), move that window to the side, and go into the \WTK25\<Game>\Classes folder, and click drag the new “com” folder, and the class file that you modified earlier with XVI32 into the WinRAR window.

Now you have a modified Jar file to put on your phone!

Other Notes:

When you try some games you may see an error about a missing nokia/mid/ui/fullcanvas.class file. If this is the case, use the attached rar file to place the “com” folder inside of your \WTK25\Apps\<Game>\Classes folder, then try the game again. It’s the Nokia API the game is looking for. When you do this, be aware that you will still have to edit the keyPressed, keyReleased, and keyRepeated sections, but that the file with the Canvas lines you’re looking for will be the FullCanvas.class file you just added in.

If you're getting IllegalArgumentExceptions it's because getGameAction is getting illegal values sent to it by the new code. (Some games work fine and ignore these, others don’t) Try changing the getGameAction method to this:

public int getGameAction(int i)
{
return i;
}

(In the files I included, the getGameAction function alread has both versions of the return in place, just one is commented out with “ // “, so just take those off and put them before the other one)

Hope that helps someone with getting some new games up and running! If you have questions, let me know