~~NOTOC~~

====== SpriterAS ======

---- dataentry extension ----
author_mail   : support@treefortress.com Shawn
description   : Highly optimized playback of Spriter Animations (SCML)           # enter a short description of the extension
lastupdate_dt : 2013-04-12 # the date you created the extension
compatible    : v1.3       # the Starling version you tested the extension with
depends       : AS3 Signals         # if the ext. depends on others, list them here
tags          : Spriter, Skeleton, Bones, Animation
homepage_url  : https://github.com/treefortress/SpriterAS
download_url  : 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 [[http://www.kickstarter.com/projects/539087245/spriter|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:
  * http://treefortress.com/introducing-spriteras-play-spriter-animations-scml-with-starling/

Or, you can check out some of the online code Example's:
  * https://github.com/treefortress/SpriterAS/tree/master/demo/src
====== Dependancies ======
SpriterAS includes the following dependancies:
  * AS3 Signals (https://github.com/robertpenner/as3-signals)

====== Basic Usage ======
<code as3>
//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);
}
</code>

====== 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:
<code as3>

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);
</code>

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:
<code as3>
brawler.playbackSpeed = .5;
</code>

====== 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.
<code as3>
//Add callback @ 400ms
archer.addCallback(onArrowFired, 400)
</code>

====== 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.
<code as3>
//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");
}
</code>

====== Tint entire sprite ======
<code as3>
//Flash Red
brawler.setColor(0xFF0000);
</code>

====== Isolate Body Parts and control externally ======
<code as3>
//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);
</code>


====== Map External Sprites to Specific Body Parts ======
<code as3>
//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;
}
</code>
===== 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/

<code as3>

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");
				});
			}
		}
	}
}

</code>
===== User Comments =====

//Feel free to edit this part of the page!//