Mobile games development

I’m really honored that another article, published on Forum Nokia Wiki, has been selected as Article of the Month!

As the previous one, this also is related to Google Maps usage in mobile applications, and you can read it here: How to use Google Maps data in mobile applications.

As its name says, It’s an introductory article on how to use Google Maps services, in particular the geocoding and static maps ones, from a mobile application, where standard Google Maps API code is not suitable (since it is thought for web based and Ajax’d apps). Its content does not focus on any particular programming language, but gives base guidelines to use those services using REST.

So… any kind of feedbacks is welcome!

I’m really happy to announce that my J2ME Google Maps API article on Forum Nokia Wiki has been selected as Article of the Week!

And, to celebrate this event, I’ve added a brand new feature to my article that will allow you to:

• create larger tiled maps
• support map scrolling

How does it work?

You start instantiating a GoogleMaps object as usual:

GoogleMaps gMap = new GoogleMaps("API_KEY");

Then you get your map, for example geocoding a given address:

double[] coords = gMap.geocodeAddress("Leicester square, London");
 
Image mapImage = gMap.retrieveStaticImage(
	150, 150,
	coords[0], coords[1],
	12, "png"
);

Then, let’s say you want to scroll your map 100 pixels up, what you’ll do is:

double[] newCoords = gMap.adjust(
	coords[0], coords[1],
	0, -100, 12
);
 
Image newMapImage = gMap.retrieveStaticImage(
	150, 150,
	newCoords[0], newCoords[1],
	12, "png"
);

As you’ve seen, the adjust method takes these arguments:

• the current latitude and longitude
• the deltaX and deltaY, in pixels
• the current zoom level

and returns the new map center latitude and longitude coordinates.

You can check the full updated source code on Forum Nokia Wiki article: J2ME Google Maps API, and a full-featured example, with the scrolling feature, on the emulator page: J2ME Google Maps API in action.

After two tutorials on Image animations in J2ME, I’ve finally decided to put together a library to easily integrate Image effects in a Java ME application. This first release is very very early, and is intended to be tested and to allow developers to give their feedbacks about it, so It’d be possible to modify and improve it.

Currently supported effects are visible on the emulator page, and are:

• BlindsFx
• ExplodeFx
• PuzzleFx
• ShakeFx
• SlideFx
• SpiralFx
• WaveFx
• WipeFx

How to use it?

Let’s start from a simple usage example. We start creating an Image, and then using it to create an AnimatedImage instance:

Image baseImage = Image.createImage("/base.png");
 
AnimatedImage animated = new AnimatedImage(baseImage);

Now, we have created an AnimatedImage, that is the base class that will allow us to apply effects to Images.

Now, we can create an effect (that will be a subclass of ImageFx) and apply it to our AnimatedImage:

ImageFx fx = new PuzzleFx(8, 8, ImageFx.TYPE_IN);
 
animated.setFx(fx);

In this example, we have chosen a PuzzleFx effect, that will show (or hide, depending on Fx type) our image piece by piece. As you can check on JavaDocs page for PuzzleFx class, first 2 arguments represent the horizontal and vertical pieces to split the Image into, while the last one is the type of the Fx itself.

Now, our AnimatedImage is ready to be animated. To start the animation, simply call the AnimatedImage start() method, passing as argument the effect duration in milliseconds:

animated.start(3000L);

About painting, you’ll simply have to call the paint() method, in a way that is really similar to Graphics drawImage():

animated.paint(g, 100, 100, Graphics.TOP | Graphics.LEFT);

Now, to begin using this library, you don’t really need any more infos. Just to point out some methods you can find useful in your app:

//stop() method will immediatly stop the FX
fx.stop();
 
//isRunning() method tells if the FX is running or not
fx.isRunning();
 
//isEnded() method tells if the FX animation is ended
fx.isEnded()
 
//and, if you want a looping effect, you can use
fx.setLooping(true);

Further information

You can library JAR file here: ImageFx.jar. Current version requires MIDP 2.0 and CLDC 1.1 to be used (a version compatible with CLDC 1.0 will be released as soon as I’ve got time :)).

Full API JavaDocs (still in early phase too :)) are also available here.

After a busy period, I finally got some time to come back to Jappit blog, just in time to announce…

Forum Nokia Code Champ Winners!

This competition, launched by Nokia to promote the development of WebRuntime and Flash-based applications has finally announced his winners, and there are really cool applications!

CityLite of IdeasLite is a guide to night life in Latin American capitals, with informations about events, theaters, and a lot more. Really cool interface!

KuneriLite team also won the award for Europe/Middle East/Africa with their one-button voting system: Kuneri Easy Vote! Congratulations for their good work!

For the full list of winners, you can look here.

iPhone 3G is finally here!

After months of guessing and posting, Apple will finally announce, during San Francisco Apple WorldWide Developers Conference of June 9th, the 3G version of its iPhone. And it seems that it’ll arrive in Italy before the end of June branded by the two Carriers Tim and Vofafone.

While it’s definitely a good news that it’ll support HSDPA, it seems that we’ll not have a builtin GPS… too bad for all location-fanatics!

Jarpa, source code is out!

Jarpa is an absolutely interesting project aiming to extend FlashLite and Java ME feature by allowing them to intercommunicate, and so allowing developers to create hybrid applications that can take the best of both worlds.

Some days ago, Felipe Andrade has finally released Jarpa sourcecode, so developers can finally start to benefit of this framework, and for J2ME and FL-addicted like me, this is a GREAT news!

And, if you need one more reason to congratulate with Felipe for its great and extensive work, here is its Nokia Championship award!

After an explosive J2ME class, now it’s the time for sliding transition effects. With the following SlidingImage class you’ll be able to seamlessly add both SlideIn and SlideOut effects to your toooo static apps!

As usual, take a look at how this would appear in a real phone, and then proceed with the simple these 1,2,3 steps

1. Download and include in your code the SlidingImage.java class
2. Instantiate a new SlidingImage:

   SlidingImage image = new SlidingImage(
   	Image.createImage("/image1.png"),
   	10,
   	SlidingImage.SLIDE_OUT);

   These are the constructor arguments:

   • An Image object to be slided
   • The number of pieces of the sliding image
   • The type of slide, can be SlidingImage.SLIDE_IN or SlidingImage.SLIDE_OUT
3. Start the sliding effect, specifying its direction and duration (in milliseconds):

   image.slide(Canvas.RIGHT, 3000);

   Direction can be one of Canvas properties UP, RIGHT, DOWN and LEFT.

4. Now you can paint it simply specifying coordinates and an anchor, as usual:

   image.paint(g,
   	100, 100,
   	Graphics.HCENTER | Graphics.VCENTER);

5. If you remember ExplodingImage class, you can check if effect is ended with the public ended property:

   if(image.ended)
   {
   //effect-end related code
   }

6. If you want to reset the effect, also changing the sliding image pieces and effect type (slide in or out), you can use the reset() method:

   //to reset changing also slides and type properties
   image.reset(12, SlidingImage.SLIDE_IN);
   //otherwise, to simply reset:
   image.reset();

You can download source code here:

• SlidingImage.java: main class source code
• SimpleSlidingCanvas.java: example of Canvas using SlidingImage

After a MIDP 1.0 utility to rotate images now time has come for some image fun

When writing mobile applications, it’s always cool to add some effects or transitions. But, while for example FlashLite has a nice builtin support for them, with J2ME you have to hand-code even the simplest movement (and this is the main reason why most J2ME apps are all but attractive).

So, here’s a first class that you can use to add an “explode” effect to images in a straightforward way. How to do it? Here we come:

1. Download the ExplodingImage.java source code and put it straight in your project
2. Instantiate an ExplodingImage this way:

   //get your Image
   Image sourceImage = Image.createImage("/image.png");
   //and then use it in ExplodingImage constructor
   ExplodingImage image = new ExplodingImage(sourceImage , 5, 8, 8);

   The ExplodingImage constructor accepts the following arguments:

   • An Image instance
   • An int representing the “level” for the exploding effect, that is the strength of the effect itself (higher the level, stronger the effect).
   • The last 2 int arguments represent the horizontal and vertical pieces of the exploded image.
3. Start the explode effect with the explode() method, that will accept the effect duration as argument:

   image.explode(2000L);

4. To paint it, simply use its paint() method, very similary to the Graphics drawImage() one. For example, in a Canvas paint() method, you can do something like this:

   protected void paint(Graphics g)
   {
   	g.setColor(0xffffff);
   	g.fillRect(0, 0, width, height);
   	image.paint(g, getWidth() / 2, getHeight() / 2, Graphics.HCENTER | Graphics.VCENTER);
   }

   To give the effect a “smooth” animation, you should paint it quite frequently (let’s say, not once per second :)). So, always using Canvas, a sample code could be like this:

   public void run()
   {
   	while(true)
   	{
   		repaint();
    
   		try
   		{
   			synchronized(this)
   			{
   				wait(50L);
   			}
   		}
   		catch(Exception e)
   		{
   			e.printStackTrace();
   		}
   	}
   }

5. To test if the effect has ended, you can simply access your ExplodingImage ended instance variable:

   if(image.ended)
   {
   	//effect-end related code
   }

6. And you’re done! See it in action here: J2ME image explode effect in action

Sample source code is available here:

• ExplodingImage.java: main class
• ExplodingImageCanvas.java: sample usage of ExplodingImage within a Canvas

So you’re still using MIDP 1.0 uh? And maybe you need to rotate an image?

If this is your case, you could find useful this simple function:

public static Image rotateImage(Image image, int angle) throws Exception
{
	if(angle == 0)
	{
		return image; 
	}
	else if(angle != 180 && angle != 90 && angle != 270)
	{
		throw new Exception("Invalid angle");
	}
 
	int width = image.getWidth();
	int height = image.getHeight();
 
	int[] rowData = new int[width];
	int[] rotatedData = new int[width * height];
 
	int rotatedIndex = 0;
 
	for(int i = 0; i < height; i++)
	{
		image.getRGB(rowData, 0, width, 0, i, width, 1);
 
		for(int j = 0; j < width; j++)
		{
			rotatedIndex = 
				angle == 90 ? (height - i - 1) + j * height : 
				(angle == 270 ? i + height * (width - j - 1) : 
					width * height - (i * width + j) - 1
				);
 
			rotatedData[rotatedIndex] = rowData[j];
		}
	}
 
	if(angle == 90 || angle == 270)
	{
		return Image.createRGBImage(rotatedData, height, width, true);
	}
	else
	{
		return Image.createRGBImage(rotatedData, width, height, true);
	}
}

So, how can you use it? Nothing more than:

Image original = Image.createImage("/original_image.png");
 
Image rotated_image = rotateImage(original, 90);

You know that J2ME support for Canvas is quite ridiculous.. One list, some form items, and stop. Canvas is left to its terrible destiny, with nothing more than a couple of lines and circles.. isn’t it sad?
So, after this melodramatic introduction, we’re ready for today’s code: a fully featured, customizable, Canvas based calendar!

If you prefer a live demonstration rather than a simple screenshot, just go here: Canvas Calendar in action.

So, how to use it?

1. Download its source code (CalendarWidget.java) and put it straight in your project
2. Instantiate it within your Canvas with its plain-old-unique constructor:

   CalendarWidget calendar = new CalendarWidget(new Date());

3. Customize it with the colors/fonts/padding you prefer:

   calendar.headerFont = Font.getFont(Font.FACE_PROPORTIONAL, Font.STYLE_BOLD, Font.SIZE_LARGE);
   calendar.weekdayFont = Font.getFont(Font.FACE_PROPORTIONAL, Font.STYLE_BOLD, Font.SIZE_MEDIUM);
   calendar.weekdayBgColor = 0xccccff;
   calendar.weekdayColor = 0x0000ff;
   calendar.headerColor = 0xffffff;

4. After you’ve customized it, remember to always call its initialize() method:

   calendar.initialize();

5. Now, to paint it, you can simply call its paint() method from your Canvas paint(), like this:

   protected void paint(Graphics g)
   {
       g.setColor(0xffffff);
       g.fillRect(0, 0, getWidth(), getHeight());
       calendar.paint(g);
   }

6. Now you must allow users to interact with it, so you can, for example, use Canvas keyPressed() method to interact with calendar:

   protected void keyPressed(int key)
   {
       int keyCode = getGameAction(key);
       if(keyCode == FIRE)
       {
           Display.getDisplay(midlet).setCurrent(
               new Alert("Selected date", calendar.getSelectedDate().toString(), null, AlertType.CONFIRMATION)
           );
       }
       else
       {
           calendar.keyPressed(keyCode);
           repaint();
       }
   }

   As you see, what we do is this:

   • if the user press FIRE button, we alert the current selected date
   • otherwise we call calendar keyPressed() method, to make it behave accordingly
7. Other customizable properties include:
   • MONTH_LABELS: change this to customize month labels in your own language
   • WEEKDAY_LABELS: as above, change this to customize weekday labels
   • startWeekday: this represents the week starting day, and its values range goes from 0 (for Monday) to 6 (for Sunday)

You can download source code of the example described above here: CalendarCanvas.java.

To get some more details about CalendarWidget source code, you can take a look at my article on Forum Nokia Wiki: Building a J2ME Canvas based Calendar / Date picker.

Some days ago I’ve posted J2ME code to parse RSS feeds using kXML library. Today’s code is about parsing a generic XML, so you can use it to parse any XML document you want. Code is splitted in the following two classes.

XmlNode class

This is the class representing a single node. We’ll define 2 node types:

• Text nodes: nodes without a name, contanining only a textual value. For them we’ll define a TEXT_NODE final variable
• Element nodes: nodes with a tag name, that can have children nodes and/or attributes

XmlNode class source code is available here: XmlNode.java

GenericXmlParser class

This is the class that will actually do XML parsing. We’ll define only one public method, parseXML(), that will accept 2 arguments:

• a KXmlParser instance, that will be used to do XML parsing
• a boolean that will tell if whitespace-only text nodes must be ignored or not

and will return and XmlNode representing the root node of the parsed XML tree.

GenericXmlParser class source code is available here: GenericXmlParser.java

Sample usage

Let’s see how we can use the two classes above. First we must instantiate and initialize a KXmlParser, and then we can call our GenericXmlParser parseXML() method.

InputStreamReader reader = new InputStreamReader(getClass().getResourceAsStream("/test3.xml"));
 
KXmlParser parser = new KXmlParser();
 
parser.setInput(reader);
 
GenericXmlParser gParser = new GenericXmlParser();
 
XmlNode xml = gParser.parseXML(parser, true);

Now, we have our resulting XmlNode that will hold the whole XML tree. We can make a simple dump of it to check if it’s all ok, using this test function:

void dumpXML(XmlNode node, int deep)
{
	for(int i = 0; i < deep; i++)
	{
		System.out.print(" ");
	}
	System.out.print(node.nodeName + " - ");
 
	if(node.nodeValue != null)
	{
		System.out.print("(" + node.nodeValue + ") - ");
	}
	String[] attributes = node.getAttributeNames();
 
	for(int i = 0; i < attributes.length; i++)
	{
		System.out.print(attributes[i] + ": " + node.getAttribute(attributes[i]) + ", ");
	}
 
	System.out.println();
 
	for(int i = 0; i < node.children.size(); i++)
	{
		dumpXML((XmlNode)node.children.elementAt(i), deep + 1);
	}
}

Note: This article is available also on Forum Nokia Wiki: How to parse an XML file in J2ME with kXML

Note: You can find this article also on Forum Nokia Wiki: How to use Google Maps data in mobile applications

Today we’ll see how to use Google Maps data within a mobile application.
Google Maps offers REST services that allows accessing its data with simple HTTP requests, so we can easily integrate them within our mobile apps.

Signup for a Google Maps API key

First thing you must do is to signup on this page:
http://code.google.com/apis/maps/signup.html
Once done, you’ll get a key (a simple String) you’ll use for all your query to Google Maps services

Static maps

Standard Google Maps code is suited for web applications, since it includes alot of Ajax functionalities, that are not really useful if you’re building a mobile application. So, the solution is to use static maps service, that will allow us to retrieve single images, easily usable within our apps.

Static maps service supports different image formats (png32, gif, jpg) and customizable image size, so that we can get perfect images for all our needs. As an example, suppose we want to retrieve the location at:

• latitude: 41.867878
• longitude: 12.471516

We can simply retrieve this URL with an HTTP GET request:

http://maps.google.com/staticmap?center=41.867878,12.471516&
format=png32&zoom=8&size=240x320&key=<API_KEY>

This way, we’ll get a PNG32 image, with a width of 240 pixels, and a height of 320, centered at point (41.867878,12.471516), and with a zoom level of 8 (zoom can go from 0 to a maximum level of 19).

Geocode an address

From Google Maps docs:
Geocoding is the process of converting addresses (like “1600 Amphitheatre Parkway, Mountain View, CA”) into geographic coordinates (like latitude 37.423021 and longitude -122.083739)

So, let’s assume we want to build an application that displays the address typed by our user. We should firstly geocode its address to geographics coordinates.
To do this, Google Maps offer another REST service easily accessible with simple HTTP requests.

Let’s say you want to geocode this address “Leicester Square, London”, then you’ll request this URL:

http://maps.google.com/maps/geo?q=Leicester%20Square,%20London
&output=csv&key=<API_KEY>

and you’ll get this output:

200,6,51.510605,-0.130728

Where:

• the first number is a code, that in this case (200) means that geocoding has been successfull (for a full list of status codes you can see here: [1])
• the second number gives a measure of geocoding accuracy (from 0 to 9 - maximum accuracy)
• 3rd and 4th numbers represent latitude and longitude of the geocoded address, so these are the coordinate we’ll use to retrieve the map through the static map service we’ve seen before

As you can see, there is an ‘output’ parameter within the geocode request, and this means that we can choose the output format we prefer for our needs. Supported formats are:

• xml
• kml (same as xml, but with different Content-Type)
• json (not really useful for mobile apps)
• csv (comma separated values)

Proxy server, usage limits

Since your Google Maps API key is bound to a specific URL, to access map services you should setup a proxy server that will receive HTTP requests from your mobile application and forward them to Google Maps REST URLs, giving back Google responses to mobile clients.

Also, be aware that there is a limit to the number of requests (both for static maps and geocode service) you can do each day. For personal uses they’re more than enough, anyway consider this point if you plan to develop commercial services.

Google Maps J2ME API and sample application

Now, you want code right? Here it is:

• a J2ME class to access Google Maps REST services: http://wiki.forum.nokia.com/index.php/J2ME_Google_Maps_API
• a sample application using Google Maps data: http://www.jappit.com/index.php?page=emulator&midlet=google_maps