Sunday, April 28, 2013

Animated Sprite using Bitmap Spritesheet with Haxe NME/OpenFL Spritesheet Library

NME comes with great spritesheet lib which can be installed with haxelib install spritesheet command on commandline. Unfortunately it lacks documentation and how to example tutorial. The only spritesheet tutorial available is the singmajesty's tutorial which also doesn't give a clue about how to work with bitmap spritesheet. So I tried to figured it out myself. And turns out it's not that hard, so I'll tell you how in a fast and effective way.

The first thing needed to create animated sprite of course is the spritesheet itself. I will use the spritesheet I took from opengameart as example.

also don't forget to add  spritesheet lib to nmml with haxelib tag

<haxelib name="spritesheet" />

to load the bitmap and parse it as animation frames we can use BitmapImporter class inside com.ecleticdesignstudio.spritesheet.importers package. this class is really simple because it's only contain one static function called create(). as the input parameter it ask for the BitmapData , column count, row count, frame width, frame height, and some additional parameter which I'm not sure what it is so I'll leave it like that for now. The create() methods gives output a Spritesheet class, we need to create a variable to hold this output.

var spritesheet:Spritesheet = BitmapImporter.create(Assets.getBitmapData("img/kit_from_firefox.png"), 3, 9, 56, 80);

we can (and must) assign BehaviourData this Spritesheet object. BehaviourData required to define how the spritesheet should be used, which frame should be played at what speed(fps) and should it be looped or not.
for this example I create 9 behaviour for the spritesheet and assigns it to each row of frames, and I give different parameter for each behaviour. What's important for this BehaviourData input parameter is the name and frame number.

spritesheet.addBehavior(new BehaviorData("stand", [0, 1, 2], true));
spritesheet.addBehavior(new BehaviorData("down", [3, 4, 5], false,15));
spritesheet.addBehavior(new BehaviorData("jump", [6, 7, 8], false,15));
spritesheet.addBehavior(new BehaviorData("hit", [9, 10, 11], false,15));
spritesheet.addBehavior(new BehaviorData("punch", [12, 13, 14], false,5));
spritesheet.addBehavior(new BehaviorData("kick", [15, 16, 17], false,15));
spritesheet.addBehavior(new BehaviorData("flypunch", [18, 19, 20], false,10));
spritesheet.addBehavior(new BehaviorData("flykick", [21, 22, 23], false,10));
spritesheet.addBehavior(new BehaviorData("dizzy", [24, 25, 26], true));

The spritesheet itself is ready, but we can't use it directly. spritesheet library has their own sprite class for animation called AnimatedSprite. We can use this AnimatedSprite to animate the spritesheet created before. to use it simply input the spritesheet into the constructor parameter.

var animated:AnimatedSprite = new AnimatedSprite(spritesheet, true)

AnimatedSprite need to update itself for animation, so we must call it's update() method on each update cycle

 public function onEnterFrame(e:Event):Void
  var delta = Lib.getTimer()- lastTime;
  lastTime = Lib.getTimer();

To play animation we can call behaviour names from spritesheet using showBehaviour() method or showBehaviours() if we want to call a list of behaviour consecutively. We can also queue behaviour using queueBehaviour(), the method will queue behaviour and animate it after the current animation finished. Remember that a looping behaviour will loop forever and so it should not be used inside the behaviour queue (if we use showBehaviours() or queueBehaviour())


So that's what I know about how to use spritesheet library . I hope it could help as the a simple tutorial of how to use Haxe NME spritesheet library because spritesheet is a fundamental thing in game. and spritesheet lib is a neat library for a playing animation. :)

Here is the result:
you could find the example source here .

Cheers! :)

Update : Dealing with Haxe 3 Change

if you switch to haxe 3 you may deal with error saying that package not found. that's happen because spritesheet library on haxe 3 use different package name. The solution is to change the package name


import com.eclecticdesignstudio.spritesheet.AnimatedSprite;
import com.eclecticdesignstudio.spritesheet.importers.BitmapImporter;
import com.eclecticdesignstudio.spritesheet.Spritesheet;


import spritesheet.AnimatedSprite;
import spritesheet.importers.BitmapImporter;
import spritesheet.Spritesheet;

there you go. now it will run without any problems . Good luck! :)