API Documentation for: 0.6.1
Show:

SpriteSheet Class

Defined in: SpriteSheet:33
Module: EaselJS

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 eight 100x100 images could be combined into a single 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].

SpriteSheet Format

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

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:

 var data = {
     images: ["sprites.jpg"],
     frames: {width:50, height:50},
     animations: {run:[0,4], jump:[5,8,"run"]}
 };
 var spriteSheet = new createjs.SpriteSheet(data);
 var animation = new createjs.BitmapAnimation(spriteSheet);
 animation.gotoAndPlay("run");

Constructor

SpriteSheet

(
  • data
)

Defined in SpriteSheet:33

Parameters:

Methods

_calculateFrames

() protected

_handleImageLoad

() protected

addEventListener

(
  • type
  • listener
)
Function | Object

Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.

Example

 displayObject.addEventListener("click", handleClick);
 function handleClick(event) {
    // Click happened.
 }

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

Returns:

Function | Object: Returns the listener for chaining or assignment.

clone

() SpriteSheet

Defined in clone:402

Returns a clone of the SpriteSheet instance.

Returns:

SpriteSheet: a clone of the SpriteSheet instance.

dispatchEvent

(
  • eventObj
  • [target]
)
Boolean

Dispatches the specified event to all listeners.

Example

 // Use a string event
 this.dispatchEvent("complete");

 // Use an object
 var event = {
     type: "complete",
     foo: "bar"
 };
 this.dispatchEvent(event);

Parameters:

  • eventObj Object | String

    An object with a "type" property, or a string type. If a string is used, dispatchEvent will construct a generic event object with the specified type.

  • [target] Object optional

    The object to use as the target property of the event object. This will default to the dispatching object.

Returns:

Boolean: Returns true if any listener returned true.

getAnimation

(
  • name
)
Object

Defined in getAnimation:352

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 String

    The name of the animation to get.

Returns:

Object: a generic object with frames, frequency, name, and next properties.

getAnimations

() Array

Defined in getAnimations:343

Returns an array of all available animation names as strings.

Returns:

Array: an array of animation names available on this sprite sheet.

getFrame

(
  • frameIndex
)
Object

Defined in getFrame:366

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.

getFrameBounds

(
  • frameIndex
)
Rectangle

Defined in getFrameBounds:381

Returns a Rectangle instance defining the bounds of the specified frame relative to the origin. For example, a 90 x 70 frame with a regX of 50 and a regY of 40 would return a rectangle with [x=-50, y=-40, width=90, height=70].

Parameters:

  • frameIndex Number

    The index of the frame.

Returns:

Rectangle: A Rectangle instance. Returns null if the frame does not exist, or the image is not fully loaded.

getNumFrames

(
  • animation
)
Number

Defined in getNumFrames:326

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.

hasEventListener

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean: Returns true if there is at least one listener for the specified event.

initialize

() protected

Inherited from EventDispatcher but overwritten in initialize:244

removeAllEventListeners

(
  • [type]
)

Removes all listeners for the specified type, or all listeners of all types.

Example

 // Remove all listeners
 displayObject.removeAllEvenListeners();

 // Remove all click listeners
 displayObject.removeAllEventListeners("click");

Parameters:

  • [type] String optional

    The string type of the event. If omitted, all listeners for all types will be removed.

removeEventListener

(
  • type
  • listener
)

Removes the specified event listener.

Important Note: that you must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.

Example

 displayObject.removeEventListener("click", handleClick);

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

toString

() String

Inherited from EventDispatcher but overwritten in toString:393

Returns a string representation of this object.

Returns:

String: a string representation of the instance.

Properties

_animations

Unknown protected

Defined in _animations:182

_data

Unknown protected

Defined in _data:200

_frameHeight

Unknown protected

Defined in _frameHeight:213

_frames

Unknown protected

Defined in _frames:188

_frameWidth

Unknown protected

Defined in _frameWidth:219

_images

Unknown protected

Defined in _images:194

_listeners

Object protected

Inherited from EventDispatcher: _listeners:90

_loadCount

Unknown protected

Defined in _loadCount:206

_numFrames

Unknown protected

Defined in _numFrames:225

_regX

Unknown protected

Defined in _regX:231

_regY

Unknown protected

Defined in _regY:237

complete

Boolean

Defined in complete:148

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

onComplete

Function deprecated

Defined in onComplete:156

Deprecated: In favour of the "complete" event. Will be removed in a future version.

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

Events

complete

Defined in complete:132

Available since 0.6.0

Dispatched 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 a listener. Ex.

var sheet = new SpriteSheet(data);
if (!sheet.complete) {
   // not preloaded, listen for onComplete:
   sheet.addEventListener("complete", handler);
}

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.