FlashPunk utility class for loading sprite definitions from an XML file

SpriteLoader.as

package net.flashpunk.utils 
{
	import net.flashpunk.graphics.Spritemap;
	/**
	 * Utility class for loading sprite definitions from an XML file
	 * 
	 * A Sprite Definition XML Document containing two sprite definitions is shown below:
	 * 
	 * <sprites>
	 *     <sprite name="player" width="32" height="32">
	 *         <animation name="walk-left" speed="0.4" loop="true">0,1,0,2</animation>
	 *         <animation name="walk-right" speed="0.4" loop="true">3,4,3,5</animation>
	 *     </sprite>
	 *     <sprite name="monster" width="32" height="32">
	 *         <animation name="walk-left" speed="0.2" loop="true">0,1,0,2</animation>
	 *         <animation name="walk-right" speed="0.2" loop="true">3,4,3,5</animation>
	 *     </sprite>
	 * </sprites>
	 * 
	 * @author Richard Marks
	 */
	public class SpriteLoader 
	{
		/**
		 * reads an XML sprite definition and creates a new Spritemap with all animations
		 * @param	spriteName - name of  sprite to read from the xml
		 * @param	spriteXML - embedded xml containing the sprite definition
		 * @param	spriteSheet - image containing the frames. Note: supports embedded image Class, or BitmapData
		 * @return a new Spritemap object will all animations setup and ready to go
		 */
		static public function CreateSpritemapFromXML(spriteName:String, spriteXML:Class, spriteSheet:*):Spritemap
		{
			// create the xml document root node
			var xmlRoot:XML = new XML(new spriteXML);
			
			// find the requested sprite definition in the xml document
			var spriteXMLRoot:XML = FindSpriteDefinition(spriteName, xmlRoot);
			if (spriteXMLRoot == null)
			{
				throw new Error("SpriteLoader.CreateSpritemapFromXML(): Error - Cannot find the sprite definition for \"" + spriteName + "\". Check your XML and make sure you do not have typos.")
			}
			
			// get the width and height of the sprite frames from the sprite definition xml
			var frameWidth:Number = Number(spriteXMLRoot.@width);
			var frameHeight:Number = Number(spriteXMLRoot.@height);
			
			// create the sprite map object
			var spriteMap:Spritemap = new Spritemap(spriteSheet, frameWidth, frameHeight);
			
			// loop through all of the animations in the sprite definition xml
			for each(var node:XML in spriteXMLRoot.animation)
			{
				var animationName:String = node.@name;
				var frameSpeed:Number = node.@speed;
				var frames:Array = FrameList(node);
				var loopAnimation:Boolean = (node.@loop == "true");
				spriteMap.add(animationName, frames, frameSpeed, loopAnimation);
			}
			
			// return the sprite map object
			return spriteMap;
		}
		
		/**
		 * searches the XML document for the specified sprite definition
		 * @param	spriteName - name of the sprite to find
		 * @param	xmlRoot - XML document to search
		 * @return the sprite definition XML node or null if not found
		 */
		static private function FindSpriteDefinition(spriteName:String, xmlRoot:XML):XML
		{
			for each(var node:XML in xmlRoot.sprite)
			{
				if (node.@name == spriteName)
				{
					return node;
				}
			}
			
			return null;
		}
		
		/**
		 * translates a string such as "1,2,3,4" into an array of Numbers [1,2,3,4]
		 * @param	frames - String containing values with which to populate the Array
		 * @return Array populated with the specified values
		 */
		static public function FrameList(frames:String):Array
		{
			if (frames.length == 0)
			{
				return [];
			}
			
			var list:Array = [];
			
			var values:Array = frames.split(",");
			
			for each(var value:String in values)
			{
				list.push(Number(value));
			}
			
			return list;
		}
	}
}