SpriterAS

author:
Shawn
description:
Highly optimized playback of Spriter Animations (SCML)
lastupdate:
2013-04-12
compatible:
v1.3
depend:
AS3 Signals
tag:
Spriter, Skeleton, Bones, Animation
homepage:
https://github.com/treefortress/SpriterAS
download:
https://github.com/treefortress/SpriterAS/archive/master.zip

Overview

Library for playing back Spriter Animation Files (SCML).

Spriter is a Skeletal animation based tool that was funded on Kickstarter in 2012. It allows you to create smooth 60fps animations, with a very small texture memory footprint.

SpriterAS is a highly optimized plugin for Starling, it can render close to 80 animations on low performance devices such as iPad 1 and iPhone 4, and much higher than that on more powerful devices. Each animations typically consist of 6-8 individual sprites.

On top of standard playback, we've also added a few helper API's to ease your daily development. For more detailed code examples, check out this blog post:

Or, you can check out some of the online code Example's:

Dependancies

SpriterAS includes the following dependancies:

Basic Usage

//Load SCML File that you saved from Spriter
loader = new SpriterLoader();
loader.completed.addOnce(onLoadComplete);
loader.load(["assets/spriter/brawler/brawler.scml"]);
 
//Playback Animation
function onLoadComplete(loader:SpriterLoader):void {
    //Once the file is loader, ask loader for a "SpriterClip"
    var brawler:SpriterClip = loader.getSpriterClip("brawler");
    brawler.x = 100;
    //User SpriterClip to playback your animation!
    brawler.play("run");
    addChild(brawler);
    Starling.juggler.add(brawler);
}

Texture Packer Support

SpriterAS is built to work with Texture Packer as well. Simply create a standard Starling Atlas, and pass it in to SpriterClip:

var atlas:TextureAtlas = new TextureAtlas(atlasTexture, atlasXml);
 
//Create AnimationSet.
//We must pass the TexturePacker prefix so the animation can find its textures.
var animation:AnimationSet = new AnimationSet(XML(new OrcScml()), 1, "orc");
 
//Create the SpriterClip and inject the Atlas.
var orc:SpriterClip = new SpriterClip(animation, atlas);

The various loading techniques are shown here: https://github.com/treefortress/SpriterAS/blob/master/demo/src/ExampleLoading.as

Dynamically Adjust Playback Speed

You can easily tweak the playback speed of your animations in realtime:

brawler.playbackSpeed = .5;

Add callback's for specific events

You can manually add a callback for a specific time in the animation, this will respect the current playback speed.

//Add callback @ 400ms
archer.addCallback(onArrowFired, 400)

Swap Body Parts

You can manually swap the pieces for any body-part. This lets you easily manipulate your animations while they're running. For example, you can make someone blink, or degrade their armor as they get damaged.

//Blink!
brawler.swapPiece("eyes_open", "eyes_closed");
setTimeout(function(){
    brawler.unswapPiece("eyes_open");
}, 50)
 
//If we fall below 50% health, swap our head sprite for one with damage. It will continue to animate as normal.
if(brawler.health < .5){
    brawler.swapPiece("face", "face_hurt");
} else {
    brawler.unswapPiece("face");
}

Tint entire sprite

//Flash Red
brawler.setColor(0xFF0000);

Isolate Body Parts and control externally

//Decapitation!
var image:Image = brawler.getImage("brawler_head");
brawler.excludePiece(image);
 
//Position this anywhere we like, it will no longer be animated.
image.x = 100;
image.y = 100;
 
//Return it to the animation
brawler.includePiece(image);

Map External Sprites to Specific Body Parts

//Create a standard Starling Particle Emitter
emitterFront = new PDParticleSystem(particleXml, particleTex);
addChild(emitterFront);
 
//Each frame, update the particle emitter so it appears to follow the character's hand
public function tick(time:Number):void {
    var frontHand:Image = mage.getImage("mage_0000_handfront");
    emitterFront.emitterX = mage.x + frontHand.x;
    emitterFront.emitterY = mage.y + frontHand.y;
}

Changelog

  • 2013/04/12 16:55: First public version

Complete Example

Below is a full example showing basic Animations and Touch interaction.

This is part of the DEMO project found here: https://github.com/treefortress/SpriterAS/blob/master/demo/src/

package
{
	import starling.core.Starling;
	import starling.display.Sprite;
	import starling.events.Touch;
	import starling.events.TouchEvent;
	import starling.events.TouchPhase;
 
	import treefortress.spriter.SpriterClip;
	import treefortress.spriter.SpriterLoader;
 
	public class ExampleBasic extends Sprite
	{
 
		protected var brawler:SpriterClip;
		protected var spriterLoader:SpriterLoader;
		protected var orc:SpriterClip;
 
		public function ExampleBasic(){
 
			//We can scale the PNG's to any size we like, allowing you to start with Hi-Res assets, and scale down to lower powered devices.
			//In this case, the source sprites are Retina-Size, so we will downscale them by 50%
			var textureScale:Number = .5;
 
			//Use the SpriterLoader class to load individual SCML files, generate a TextureAtlas, and create AnimationSets, all at once.
			spriterLoader = new SpriterLoader();
			spriterLoader.completed.addOnce(onSpriterLoaderComplete);
			spriterLoader.load(["assets/spriter/orc/orc.scml", "assets/spriter/brawler/brawler.scml"], textureScale);
		}
 
		protected function onSpriterLoaderComplete(loader:SpriterLoader):void {
 
			//Add Orc 1
			orc = spriterLoader.getSpriterClip("orc");
			orc.play("run", 0);
			orc.scaleX = -1;
			orc.y = 50;
			orc.x = 300;
			orc.playbackSpeed = .5;
			addChild(orc);
 
			//For performance reasons, SpriterClips will not update themselves, they must externally ticked each frame.
			//The Starling Juggler is a simple way to do that.
			Starling.juggler.add(orc);
 
			//Add a "Brawler"
			brawler = spriterLoader.getSpriterClip("brawler");
			brawler.setPosition(500, 50);
			brawler.play("idle");
			addChild(brawler);
			Starling.juggler.add(brawler);
 
			//Add Touch Support to each Sprite
			orc.touchable = true;
			orc.addEventListener(TouchEvent.TOUCH, onCharacterTouched);
			brawler.touchable = true;
			brawler.addEventListener(TouchEvent.TOUCH, onCharacterTouched);
 
		}
 
		protected function onCharacterTouched(event:TouchEvent):void {
			var touch:Touch = event.touches[0];
			if(touch.phase == TouchPhase.ENDED){
				(event.currentTarget as SpriterClip).play("attack");
				(event.currentTarget as SpriterClip).animationComplete.addOnce(function(clip:SpriterClip){
					clip.play((clip == brawler)? "idle" : "run");
				});
			}
		}
	}
}

User Comments

Feel free to edit this part of the page!

  extensions/spriteras.txt · Last modified: 2015/03/11 14:05 (external edit)
 
Powered by DokuWiki