EaselJS

EaselJS  0.5.0

EaselJS > EaselJS > SpriteSheet
Search:
 
Filters

Class SpriteSheet

Encapsulates the properties and methods associated with a sprite sheet. A sprite sheet is a series of images (usually animation frames) combined into a larger image (or images). For example, an animation consisting of 8 100x100 images could be combined into a 400x200 sprite sheet (4 frames across by 2 high).

The data passed to the SpriteSheet constructor defines three critical pieces of information:
  1. The image or images to use.
  2. The positions of individual image frames. This data can be represented in one of two ways: As a regular grid of sequential, equal-sized frames, or as individually defined, variable sized frames arranged in an irregular (non-sequential) fashion.
  3. Likewise, animations can be represented in two ways: As a series of sequential frames, defined by a start and end frame [0,3], or as a list of frames [0,1,2,3].
The easiest way to understand the data format is to see an example:
data = {
 
// DEFINING IMAGES:
	// list of images or image URIs to use. SpriteSheet can handle preloading.
	// the order dictates their index value for frame definition.
	images: [image1, "path/to/image2.png"],
 
// DEFINING FRAMES:
 
	// the simple way to define frames, only requires frame size because frames are consecutive:
	// define frame width/height, and optionally the frame count and registration point x/y.
	// if count is omitted, it will be calculated automatically based on image dimensions.
	frames: {width:64, height:64, count:20, regX: 32, regY:64},
 
	// OR, the complex way that defines individual rects for frames.
	// The 5th value is the image index per the list defined in "images" (defaults to 0).
	frames: [
		// x, y, width, height, imageIndex, regX, regY
		[0,0,64,64,0,32,64],
		[64,0,96,64,0]
	],
 
// DEFINING ANIMATIONS:
 
	// simple animation definitions. Define a consecutive range of frames.
	// also optionally define a "next" animation name for sequencing.
	// setting next to false makes it pause when it reaches the end.
	animations: {
		// start, end, next, frequency
		run: [0,8],
		jump: [9,12,"run",2],
		stand: [13]
	}
 
	// the complex approach which specifies every frame in the animation by index.
	animations: {
		run: {
			frames: [1,2,3,3,2,1]
		},
		jump: {
			frames: [1,4,5,6,1],
			next: "run",
			frequency: 2
		},
		stand: { frames: [7] }
	}
 
	// the above two approaches can be combined, you can also use a single frame definition:
	animations: {
		run: [0,8,true,2],
		jump: {
			frames: [8,9,10,9,8],
			next: "run",
			frequency: 2
		},
		stand:7
	}
}
  For example, to define a simple sprite sheet, with a single image "sprites.jpg" arranged in a regular 50x50 grid with two animations, "run" looping from frame 0-4 inclusive, and "jump" playing from frame 5-8 and sequencing back to run:
data = {
	images: ["sprites.jpg"],
	frames: {width:50, height:50},
	animations: {run:[0,4], jump:[5,8,"run"]}
}

Constructor

SpriteSheet ( data )
Parameters:
data <object>

Properties

_animations - protected object


_data - protected object


_frameHeight - protected object


_frames - protected object


_frameWidth - protected object


_images - protected object


_loadCount - protected object


_numFrames - protected object


_regX - protected object


_regY - protected object


complete - Boolean

Read-only property indicating whether all images are finished loading.

Methods

_calculateFrames

protected void _calculateFrames ( )
Returns: void

_handleImageLoad

protected void _handleImageLoad ( )
Returns: void

clone

SpriteSheet clone ( )
Returns a clone of the SpriteSheet instance.
Returns: SpriteSheet
a clone of the SpriteSheet instance.

getAnimation

Object getAnimation ( name )
Returns an object defining the specified animation. The returned object has a frames property containing an array of the frame id's in the animation, a frequency property indicating the advance frequency for this animation, a name property, and a next property, which specifies the default next animation. If the animation loops, the name and next property will be the same.
Parameters:
name <object> The name of the animation to get.
Returns: Object
a generic object with frames, frequency, name, and next properties.

getAnimations

Array getAnimations ( )
Returns an array of all available animation names as strings.
Returns: Array
an array of animation names available on this sprite sheet.

getFrame

Object getFrame ( frameIndex )
Returns an object specifying the image and source rect of the specified frame. The returned object has an image property holding a reference to the image object in which the frame is found, and a rect property containing a Rectangle instance which defines the boundaries for the frame within that image.
Parameters:
frameIndex <Number> The index of the frame.
Returns: Object
a generic object with image and rect properties. Returns null if the frame does not exist, or the image is not fully loaded.

getNumFrames

Number getNumFrames ( animation )
Returns the total number of frames in the specified animation, or in the whole sprite sheet if the animation param is omitted.
Parameters:
animation <String> The name of the animation to get a frame count for.
Returns: Number
The number of frames in the animation, or in the entire sprite sheet if the animation param is omitted.

initialize

protected void initialize ( )
Returns: void

toString

String toString ( )
Returns a string representation of this object.
Returns: String
a string representation of the instance.

Events

onComplete

onComplete ( )
The onComplete callback is called when all images are loaded. Note that this only fires if the images were not fully loaded when the sprite sheet was initialized. You should check the complete property to prior to adding an onComplete handler. Ex.
var sheet = new SpriteSheet(data);
if (!sheet.complete) {
  // not preloaded, listen for onComplete:
  sheet.onComplete = handler;
}