[rfk-dev] RFK for J2ME-enabled phones

[Tim Allen]

Last year I got a Nokia 3530 phone, one that lets me install Java 
applets via HTTP. A few months after that I found a port of the J2ME 
tools ('Java 2 Mobile Edition', I believe), and a little while after 
that I was looking for a simple-ish program to write that would be kind 
to my phone's diminutive processor and miniscule display, when suddenly 
I remembered robotfindskitten.

Quick details:
==============
I've got the latest version of the program temporarily online at:

	http://robotbee.org/~st/midlets/

The interesting files are:
  - robotfindskitten.jar: The actual installable package.
  - robotfindskitten.jad: A required metadata file
  - robotfindskitten-src.tar.gz: A standard tarball of the sourcecode.
  - test.html, me-applet.jar: View test.html in a Java-enabled browser 
to play with RFK without having to find a Java-enabled phone.

NOTE: Both the 'jad' and 'jar' files contain references to the URL 
containing the software. If the software is to be hosted somewhere 
else, it might need to be recompiled, or at least tinkered with. See 
'Notes on the build system' below.

Highlights:
===========
  - Contains all the NKIs from whatever the latest version of RFK was 
when I wrote the Java version.
  - Lets you save a game in progress and come back to it later.
  - Sophisticated scrolling system lets robot search for kitten in an 
arena larger than the screen.
  - No 'You found kitten!' animation, but there is a cute hand-drawn 
kitten graphic.

Notes on the source code:
=========================
  - Arena.java represents the arena robot explores, and contains the 
list of NKIs.
  - ArenaDisplay.java takes the Arena and figures out how to draw it 
nicely on a bitmap screen whose dimensions are not necessarily integer 
multiples of the font size. It also contains the main RFK event 
handling.
  - Main.java contains all the menus and the state-saving.

Notes on the build system:
==========================
In order to build RFK for J2ME, you'll need a copy of Sun's J2ME SDK; 
basically a simple emulator for testing and class-libraries to link 
against:

	http://java.sun.com/products/j2mewtoolkit/download.html

It's available for Windows, Linux and Solaris, with all sorts of spiffy 
IDEs and such, but I was using the cheapskate Mac OS X port which just 
supplies the bare minimum necessary. Accordingly, rfk uses the highly 
complicated and eerily advanced 'GNU make' as its build engine. Folk 
who posess sufficient make-fu will no doubt be able to divine all I 
know about J2ME packaging from the included makefile, others will need 
to read on.

First, a word about J2ME packaging: Each 'midlet' needs certain 
associated metadata in order to run. This metadata appears in two 
places - some of it appears in the 'robotfindskitten.jad' file that you 
feed to your phone, which tells it the name of the application and 
where to download the actual code, and some of it appears in 
'MANIFEST.MF' in the .jar file. The source tarball includes a file 
called 'manifest.mf' which contains the union of the two information 
sets, this file is filtered to become both metadata files. 
Specifically, to set the 'source URL', edit the line 'MIDlet-Jar-URL' 
in 'manifest.in' and rebuild.

There are 'test' and 'install' targets - these most likely won't work 
unless you happen to have things set up identically to me. 'make 
localtest' is more likely to be useful. 'make clean' works as it 
should.

You'll need to have $MIDP_HOME in your environment, but installing the 
J2ME SDK should take care of that anyway.

Notes on installing the thing into a phone:
===========================================
Some phones won't install a midlet that's over 64k. RFK is currently 
22k, and most of that is NKIs.

Phones are very, *very* picky about MIME types. I have the following 
settings in my .htaccess:

	AddType text/vnd.sun.j2me.app-descriptor JAD jad
	AddType application/java-archive JAR jar

Final notes:
============
I'm subscribed to rfk-dev now, if anyone has any further queries or 
suggestions or even just wants to say they've installed it on their 
phone and it worked, I'd be interested to hear them.