EaselJS

EaselJS  0.4

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, image index, 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: {frameWidth:50, frameHeight: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.

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