Options
All
  • Public
  • Public/Protected
  • All
Menu

Sprite sheets are a useful mechanism for slicing up image resources into separate sprites or for generating in game animations. Sprites are organized in row major order in the SpriteSheet.

You can also use a SpriteFont which is special kind of SpriteSheet for use with Labels.

Creating a SpriteSheet

To create a SpriteSheet you need a loaded Texture resource.

var game = new ex.Engine();
var txAnimPlayerIdle = new ex.Texture('/assets/tx/anim-player-idle.png');
// load assets
var loader = new ex.Loader(txAnimPlayerIdle);

// start game
game.start(loader).then(function() {
  var player = new ex.Actor();

  // create sprite sheet with 5 columns, 1 row, 80x80 frames
  var playerIdleSheet = new ex.SpriteSheet(txAnimPlayerIdle, 5, 1, 80, 80);

  // create animation (125ms frame speed)
  var playerIdleAnimation = playerIdleSheet.getAnimationForAll(game, 125);

  // add drawing to player as "idle"
  player.addDrawing('idle', playerIdleAnimation);
  // add player to game
  game.add(player);
});

Creating animations

SpriteSheets provide a quick way to generate a new Animation instance.

You can use all the frames of a Texture(SpriteSheet.getAnimationForAll) or you can use a range of frames (SpriteSheet.getAnimationBetween) or you can use specific frames (SpriteSheet.getAnimationByIndices).

To create an Animation these methods must be passed an instance of Engine. It's recommended to generate animations for an Actor in their Actor.onInitialize event because the Engine is passed to the initialization function. However, if your Engine instance is in the global scope, you can create an Animation at any time provided the Texture has been loaded.

// create sprite sheet with 5 columns, 1 row, 80x80 frames
var playerIdleSheet = new ex.SpriteSheet(txAnimPlayerIdle, 5, 1, 80, 80);

// create animation for all frames (125ms frame speed)
var playerIdleAnimation = playerIdleSheet.getAnimationForAll(game, 125);
// create animation for a range of frames (2-4) (125ms frame speed)
var playerIdleAnimation = playerIdleSheet.getAnimationBetween(game, 1, 3, 125);
// create animation for specific frames 2, 4, 5 (125ms frame speed)
var playerIdleAnimation = playerIdleSheet.getAnimationByIndices(game, [1, 3, 4], 125);
// create a repeating animation (ping-pong)
var playerIdleAnimation = playerIdleSheet.getAnimationByIndices(game, [1, 3, 4, 3, 1], 125);

Multiple rows

Sheets are organized in "row major order" which means left-to-right, top-to-bottom. Indexes are zero-based, so while you might think to yourself the first column is column "1", to the engine it is column "0". You can easily calculate an index of a frame using this formula:

Given: col = 5, row = 3, columns = 10
index = col + row * columns
index = 4 + 2 * 10 // zero-based, subtract 1 from col & row
index = 24

You can also simply count the frames of the image visually starting from the top left and beginning with zero.

// get a sprite for column 3, row 6
var sprite = animation.getSprite(2 + 5 * 10);

Hierarchy

Index

Constructors

constructor

Properties

columns

columns: number = 0

image

image: Texture = null

rows

rows: number = 0

spHeight

spHeight: number = 0

spWidth

spWidth: number = 0

sprites

sprites: Sprite[] = []

Methods

getAnimationBetween

  • getAnimationBetween(engine: Engine, beginIndex: number, endIndex: number, speed: number): Animation
  • Create an animation from the this SpriteSheet by specifing the range of images with the beginning (inclusive) and ending (exclusive) index For example getAnimationBetween(engine, 0, 5, 200) returns an animation with 5 frames.

    Parameters

    • engine: Engine

      Reference to the current game Engine

    • beginIndex: number

      The index to start taking frames (inclusive)

    • endIndex: number

      The index to stop taking frames (exclusive)

    • speed: number

      The number in milliseconds to display each frame in the animation

    Returns Animation

getAnimationByCoords

  • Get an animation with bespoke sprite coordinates. This is useful if the SpriteSheet is packed and not a uniform width or height. The resulting Animation will have the height and width of the largest dimension (width, height) from among the sprite coordinates

    Parameters

    Returns Animation

getAnimationByIndices

  • getAnimationByIndices(engine: Engine, indices: number[], speed: number): Animation
  • Create an animation from the this SpriteSheet by listing out the sprite indices. Sprites are organized in row major order in the SpriteSheet.

    Parameters

    • engine: Engine

      Reference to the current game Engine

    • indices: number[]

      An array of sprite indices to use in the animation

    • speed: number

      The number in milliseconds to display each frame in the animation

    Returns Animation

getAnimationForAll

  • Treat the entire SpriteSheet as one animation, organizing the frames in row major order.

    Parameters

    • engine: Engine

      Reference to the current game Engine

    • speed: number

      The number in milliseconds to display each frame the animation

    Returns Animation

getSprite

  • getSprite(index: number): Sprite
  • Retreive a specific sprite from the SpriteSheet by its index. Sprites are organized in row major order in the SpriteSheet.

    Parameters

    • index: number

      The index of the sprite

    Returns Sprite