Java applications for Mobile Devices

An introduction to the Java MIDP 2.0 Game API

Csar Toscano March/2009

The Game API Package

Package javax.microedition.lcdui.game. Provides classes that enable developers to build rich gaming content for wireless devices. Based on low-level graphics classes such as Graphics and Image from MIDP 1.0. There is no immediate visible effect when methods modify the states of the classes in the package. Objects store their states, for use in subsequent calls to paint() (usually, gaming applications redraw the entire screen at the end of every game cycle).

The Game API Package

The package comprises five classes. GameCanvas: subclass of javax.microedition.lcdui.Canvas; provides the basic screen functionality for a game. Includes gaming-oriented methods to query the state of the game keys, and synchronous graphics flushing. Layer: abstract class that forms the basis for a framework of layered graphics. Represents a visual element in a game, such as a Sprite or a TiledLayer, and has attributes like location, size, and visibility. Sprite: basic animated layer that can display one of several graphical frames of equal size and stored in a single Image object. Supports transformations such as flip and rotate, as well as collision-detection methods. TiledLayer: represents a visual element composed of a grid of cells that can be filled with a set of tile images. This class enables the developer to create large areas of graphical content without the resource use that a large Image object would require. LayerManager: simplifies game development by automating the rendering process. It is useful for games with multiple layers. It enables the developer to set a view window to represent the user's view of the game, and automatically renders the game's layers to implement the desired view.

GameCanvas class
public class MyCanvas extends GameCanvas implements Runnable { public void run() { Graphics g = getGraphics(); while(true) { // update the game state // ... int k = getKeyStates(); // respond to key events flushGraphics(); } } }

Layer class
It is an abstract class that represents a visual element of a game. Each Layer can be made visible or invisible, and has a position, width, and height. Subclasses of Layer must implement the paint(Graphics) method so that they can be rendered. The position of a Layer is expressed as the position of the upper-left corner of its visual bounds. Its x-y position is interpreted relative to the coordinate system of the Graphics object passed to its paint() method; its initial location in that system is 0-0.

LayerManager class
Manages and organizes the graphical layers in the game (instances of Layer and its subclasses). For example, manages background layers (TiledLayer instances) and player characters (Sprite instances). The order in which layers are painted is the reverse of the order you append them to the LayerManager. You can create a graphical painting larger than the device screen and then select what section of the painting to display as a game proceeds. setViewWindow (int x, int y, int width, int height) sets the visible rectangle based on the LayerManager's coordinate system. paint (Graphics g, int x, int y) method paints the layer on the screen based on the state of the GameCanvas.

Sprite class
A typical two-dimensional game has characters that move around and interact with each other: they are represented by Sprites. A Sprite class represents a graphical image at a point in time. Sprites have Cartesian coordinates: its x-coordinate indicates how far across the screen they should be placed, and its y-coordinate indicates how far down. Animation is supported: a sequence of frames is defined using setFrameSequence (int sequence[]), and the animation is advanced from one frame to the next using nextFrame(). The appearance of a sprite can be changed through transformations such as rotations and mirror images.

Sprite class
A single Image object supplies the raw frames. Each frame is assigned a unique index number.

A Sprite's frame sequence is a simple array of ints that defines an ordered list of frames to be displayed.

Sprite class
Reference pixel: the pixel to use as the upper-left pixel when specifying a sprite's position. The default reference pixel is the one at 0-0. defineReferencePixel (int x, int y) lets you override the default reference pixel in the sprite's untransformed frame. You can specify the reference cell's position on the screen and thus the sprite's position by calling setRefPixelLocation (int x, int y).

Sprite class
You can apply various transformations to a Sprite. When a transform is applied, the Sprite is redrawn at a location that leaves the position of the reference pixel in the painter's coordinate system unchanged. The reference cell becomes the center of the transform operation, and the sprite flips or rotates around it.

TiledLayer class
Similar to Sprite in some ways, different in others. It may include animated elements, but has no transformations, frame sequence, or reference pixel. It is a grid of cells, each painted with one frame selected from an Image. To provide all the needed tiles to fill the TiledLayer's cells, a number of equally-sized frames are stored in a single small Image.

TiledLayer class
Each tile in the Image is assigned a unique index number; the tile in the upper-left corner of the Image has an index of 1. A positive tile index indicates a static tile, a negative index indicates an animated tile, and an index of zero indicates an empty cell. To create a TiledLayer: Instantiate TiledLayer, passing to the constructor the number of rows and the number of columns in the layer, the Image that holds the tile set, and the width and height of the tiles in that set, which will determine the layer's cell size. Next you fill each cell with the index of a tile, using setCell (int column, int row, int tileIndex). A static tile set is created when the TiledLayer is instantiated, and you can update it at any time using the setStaticTileSet() method. You create animated tiles with the createAnimatedTile() method, which returns the index to be used for the new animated tile. Animated tile indices are always negative and consecutive, beginning with -1. You can change the static tile associated with an animated tile with the setAnimatedTile() method.