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:

1. The source image or images to use.
2. The positions of individual image frames.
3. Sequences of frames that form named animations. Optional.
4. The target playback framerate. Optional.

SpriteSheet Format

SpriteSheets are an object with two required properties (images and frames), and two optional properties (framerate and animations). This makes them easy to define in javascript code, or in JSON.

images

An array of source images. Images can be either an HTMlimage instance, or a uri to an image. The former is recommended to control preloading.

images: [image1, "path/to/image2.png"],

frames

Defines the individual frames. There are two supported formats for frame data: When all of the frames are the same size (in a grid), use an object with width, height, regX, regY, and count properties.

• width & height are required and specify the dimensions of the frames
• regX & regY indicate the registration point or "origin" of the frames
• spacing indicate the spacing between frames
• margin specify the margin around the image(s)
• count allows you to specify the total number of frames in the spritesheet; if omitted, this will be calculated based on the dimensions of the source images and the frames. Frames will be assigned indexes based on their position in the source images (left to right, top to bottom).

 frames: {width:64, height:64, count:20, regX: 32, regY:64, spacing:0, margin:0}

If the frames are of different sizes, use an array of frame definitions. Each definition is itself an array with 4 required and 3 optional entries, in the order:

• The first four, x, y, width, and height are required and define the frame rectangle.
• The fifth, imageIndex, specifies the index of the source image (defaults to 0)
• The last two, regX and regY specify the registration point of the frame

frames: [
    // x, y, width, height, imageIndex*, regX*, regY*
    [64, 0, 96, 64],
    [0, 0, 64, 64, 1, 32, 32]
    // etc.
]

animations

Optional. An object defining sequences of frames to play as named animations. Each property corresponds to an animation of the same name. Each animation must specify the frames to play, and may also include a relative playback speed (ex. 2 would playback at double speed, 0.5 at half), and the name of the next animation to sequence to after it completes.

There are three formats supported for defining the frames in an animation, which can be mixed and matched as appropriate:

1. for a single frame animation, you can simply specify the frame index

       animations: {
           sit: 7
       }

2. for an animation of consecutive frames, you can use an array with two required, and two optional entries in the order: start, end, next, and speed. This will play the frames from start to end inclusive.

       animations: {
           // start, end, next*, speed*
           run: [0, 8],
           jump: [9, 12, "run", 2]
       }

3. for non-consecutive frames, you can use an object with a frames property defining an array of frame indexes to play in order. The object can also specify next and speed properties.

       animations: {
           walk: {
               frames: [1,2,3,3,2,1]
           },
           shoot: {
               frames: [1,4,5,6],
               next: "walk",
               speed: 0.5
           }
       }

Note: the speed property was added in EaselJS 0.7.0. Earlier versions had a frequency property instead, which was the inverse of speed. For example, a value of "4" would be 1/4 normal speed in earlier versions, but is 4x normal speed in EaselJS 0.7.0+.

framerate

Optional. Indicates the default framerate to play this spritesheet at in frames per second. See framerate for more information.

    framerate: 20

Note that the Sprite framerate will only work if the stage update method is provided with the tick event generated by the Ticker.

    createjs.Ticker.on("tick", handleTick);
    function handleTick(event) {
        stage.update(event);
    }

Example

To define a simple sprite sheet, with a single image "sprites.jpg" arranged in a regular 50x50 grid with three animations: "stand" showing the first frame, "run" looping frame 1-5 inclusive, and "jump" playing frame 6-8 and sequencing back to run.

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

Generating SpriteSheet Images

Spritesheets can be created manually by combining images in PhotoShop, and specifying the frame size or coordinates manually, however there are a number of tools that facilitate this.

• Exporting SpriteSheets or HTML5 content from Adobe Flash/Animate supports the EaselJS SpriteSheet format.
• The popular Texture Packer has EaselJS support.
• SWF animations in Adobe Flash/Animate can be exported to SpriteSheets using Zoë

Cross Origin Issues

Warning: Images loaded cross-origin will throw cross-origin security errors when interacted with using:

• a mouse
• methods such as getObjectUnderPoint
• Filters (see Filter)
• caching (see cache)

You can get around this by setting crossOrigin property on your images before passing them to EaselJS, or setting the crossOrigin property on PreloadJS' LoadQueue or LoadItems.

    var img = new Image();
    img.crossOrigin="Anonymous";
    img.src = "http://server-with-CORS-support.com/path/to/image.jpg";

If you pass string paths to SpriteSheets, they will not work cross-origin. The server that stores the image must support cross-origin requests, or this will not work. For more information, check out CORS overview on MDN.

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

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

 // Use an Event instance
 var event = new createjs.Event("progress");
 this.dispatchEvent(event);

[x=-50, y=-40, width=90, height=70]

    var listener = myBtn.on("click", handleClick, null, false, {count:3});
    function handleClick(evt, data) {
        data.count -= 1;
        console.log(this == myBtn); // true - scope defaults to the dispatcher
        if (data.count == 0) {
            alert("clicked 3 times!");
            myBtn.off("click", listener);
            // alternately: evt.remove();
        }
    }

 // Remove all listeners
 displayObject.removeAllEventListeners();

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

 displayObject.removeEventListener("click", handleClick);

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