Building Your First Game Using NME

I know there are many choices when developing a game for the BlackBerry platform, but I wanted to share my favorite with you. If you have not heard of it before, NME is a free and open-source framework, designed to bring a unified feature set and native performance to many platforms, including the BlackBerry® PlayBook™ tablet and BlackBerry® 10. 

Defining a Project File

The first place to start when building an NME project is to make sure you have a project file. This will tell NME where your asset and source files are located, as well as meta-data like the application name, version and author.

Unlike other BlackBerry applications, you will not need to define a "bar-descriptor.xml" file later. NME will generate the file for you, based on the values in the NME project file.

<?xml version="1.0" encoding="utf-8"?>
<project>
<meta title="Asterisk Game" package="com.testing.asteriskgame" version="1.0.0" company="Joshua Granick" />
<app main="AsteriskGame" path="Export" />
	<window width="800" height="600" unless="mobile" />

<source path="Source" />
<haxelib name="nme" />
<haxelib name="actuate" />
	<assets path="Assets" rename="assets" exclude="icon-*.png" />
<icon path="Assets/icon-114.png" size="114" />
<icon path="Assets/icon-86.png" size="86" />
</project>

You can find more details about the NMML format here.

Loading Assets

NME has an Assets class that makes it simple to load resource files. It accepts a path, based on the file structure of your project and the <assets /> nodes you include in the project file. You can use the Assets class to load bitmap data, bytes, font references, sounds and plain text synchronously.

If you need to load an asset asynchronously, such as from a remote server, you can use the NME Loader and URLLoader classes, which are outside the scope of this post.

Creating a Bitmap

var bitmapData = Assets.getBitmapData ("assets/asterisk.png");
var bitmap = new Bitmap (bitmapData);
addChild (bitmap);

Unless you are creating a new bitmap in memory, the first step is to load an existing image asset from a file or a web server. In this sample, I am using an existing graphic called "asterisk.png", which I have included in my project.

Once this process is complete, I will have the data for my bitmap, represented in NME by the BitmapData class. With a BitmapData object, I can use one of multiple rendering methods available. The simplest and most common is to create a Bitmap and add it to the "display list." In NME, there is a tree of objects which are rendered automatically. By adding a display object to a parent that already is a member of the "display list," it will be rendered as well. In this way, we can decide when our Bitmap is able to be rendered.

Adding Touch Interaction

It is exciting to get a bitmap on-screen, but in order to build a game we need to be able to handle touch interaction. Although a Bitmap has values like a position, size, scale and alpha (transparency), the Bitmap class cannot handle touch or mouse interaction.

The easiest way to add this support is to put our bitmap inside of a Sprite:

var sprite = new Sprite ();
var bitmap = new Bitmap (Assets.getBitmapData ("assets/asterisk.png"));
sprite.addChild (bitmap);
addChild (sprite);

The Sprite class is one of the most common classes in NME development. In addition to being a DisplayObject, like the Bitmap class, a Sprite instance can contain other objects. The Sprite class also supports dispatches touch and mouse events, which is what we are looking for.

sprite.addEventListener (MouseEvent.MOUSE_DOWN, function (event) { bitmap.visible = false; });

Adding an event listener makes it possible to respond when an event occurs on the objects, such as the MouseEvent.MOUSE_DOWN event.

NME supports a touch-specific API, but most applications will only need to listen to standard mouse events. These will work with touch screens as well as traditional desktop and laptop systems, making it simpler for your project to run on multiple form-factors.

Playing Sound

var sound = Assets.getSound ("assets/fuzz.wav");
sound.play (); 

Loading a Sound is simple, thanks to the NME Assets class. Then you can call play to your sound.

Internally, NME is using SDL_mixer on BlackBerry to play audio. This provides excellent support for many file formats, but also presents some restrictions. SDL_mixer supports one streaming "music" channel at once and multiple event "sound" channels simultaneously. NME will try to automatically detect whether a file is "music" or "sound" based on the file extension, but this can be controlled manually in your NMML project file.

SDL_mixer only supports MP3 in the "music" channel, while other formats, such as OGG and WAV, can be used for "sound". This is a limitation to be aware of, especially if you are using MP3 files.

Download the Sample

You can download the "Asterisk Game," a small sample that uses these features to make a simple "whack-a-mole" style game. Asterisks will appear on screen, and the player taps the asterisks to make them disappear until time runs out. The score is based on the number of asterisks the player is able to tap before they fade on their own, and bonus points are awarded based on the size of the asterisk – smaller asterisks are worth more points.

If you appreciated this tutorial and would like to learn more about NME, please sound off in the comments!