EaselJS  0.4

EaselJS > EaselJS > SpriteSheet

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 = {
	// 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"],
	// 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, image index, regX, regY
	// 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
  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: {frameWidth:50, frameHeight:50},
	animations: {run:[0,4], jump:[5,8,"run"]}


SpriteSheet ( data )
data <object>


_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.



protected void _calculateFrames ( )
Returns: void


protected void _handleImageLoad ( )
Returns: void


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


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


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 frame is found, and a rect property containing a Rectangle instance which defines the boundaries for the frame within that image.
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.


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.
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.


protected void initialize ( )
Returns: void


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