Skip navigation

SpriteSheet(​properties)

A sprite sheet to animate a sequence of images. Used to create animation sprites.

11 frames of a walking pill-like alien wearing a space helmet.
Sprite sheet image courtesy of Kenney.

Typically you create a sprite sheet just to create animations and then use the animations for your sprite.

let { Sprite, SpriteSheet } = kontra;

let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {
  let spriteSheet = SpriteSheet({
    image: image,
    frameWidth: 72,
    frameHeight: 97,
    animations: {
      // create a named animation: walk
      walk: {
        frames: '0..9',  // frames 0 through 9
        frameRate: 30
      }
    }
  });

  let sprite = Sprite({
    x: 200,
    y: 100,

    // use the sprite sheet animations for the sprite
    animations: spriteSheet.animations
  });
};

import { Sprite, SpriteSheet } from 'path/to/kontra.mjs';

let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {
  let spriteSheet = SpriteSheet({
    image: image,
    frameWidth: 72,
    frameHeight: 97,
    animations: {
      // create a named animation: walk
      walk: {
        frames: '0..9',  // frames 0 through 9
        frameRate: 30
      }
    }
  });

  let sprite = Sprite({
    x: 200,
    y: 100,

    // use the sprite sheet animations for the sprite
    animations: spriteSheet.animations
  });
};

import { Sprite, SpriteSheet } from 'kontra';

let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {
  let spriteSheet = SpriteSheet({
    image: image,
    frameWidth: 72,
    frameHeight: 97,
    animations: {
      // create a named animation: walk
      walk: {
        frames: '0..9',  // frames 0 through 9
        frameRate: 30
      }
    }
  });

  let sprite = Sprite({
    x: 200,
    y: 100,

    // use the sprite sheet animations for the sprite
    animations: spriteSheet.animations
  });
};

Parameters

properties

Object. Properties of the sprite sheet.

properties.image

HTMLImageElement or HTMLCanvasElement. The sprite sheet image.

properties.frameWidth

Number. The width of a single frame.

properties.frameHeight

Number. The height of a single frame.

properties.spacing Optional

Number. The amount of whitespace between each frame. Defaults to 0.

properties.margin Optional

Number. The amount of whitespace border around the entire image. Defaults to 0.

properties.animations Optional

Object. Animations to create from the sprite sheet using Animation. Passed directly into the sprite sheets createAnimations() function.

Table of Contents

SpriteSheet​.animations

Object. An object of named Animation objects. Typically you pass this object into Sprite to create an animation sprites.

SpriteSheet​.createAnimations(​animations)

Create named animations from the sprite sheet. Called from the constructor if the animations argument is passed.

This function populates the sprite sheets animations property with Animation objects. Each animation is accessible by its name.

let { Sprite, SpriteSheet } = kontra;

let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {

  let spriteSheet = SpriteSheet({
    image: image,
    frameWidth: 72,
    frameHeight: 97,

    // this will also call createAnimations()
    animations: {
      // create 1 animation: idle
      idle: {
        // a single frame
        frames: 1
      }
    }
  });

  spriteSheet.createAnimations({
    // create 4 animations: jump, walk, moonWalk, attack
    jump: {
      // sequence of frames (can be non-consecutive)
      frames: [1, 10, 1],
      frameRate: 10,
      loop: false,
    },
    walk: {
      // ascending consecutive frame animation (frames 2-6, inclusive)
      frames: '2..6',
      frameRate: 20
    },
    moonWalk: {
      // descending consecutive frame animation (frames 6-2, inclusive)
      frames: '6..2',
      frameRate: 20
    },
    attack: {
      // you can also mix and match, in this case frames [8,9,10,13,10,9,8]
      frames: ['8..10', 13, '10..8'],
      frameRate: 10,
      loop: false,
    }
  });
};

import { Sprite, SpriteSheet } from 'path/to/kontra.mjs';

let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {

  let spriteSheet = SpriteSheet({
    image: image,
    frameWidth: 72,
    frameHeight: 97,

    // this will also call createAnimations()
    animations: {
      // create 1 animation: idle
      idle: {
        // a single frame
        frames: 1
      }
    }
  });

  spriteSheet.createAnimations({
    // create 4 animations: jump, walk, moonWalk, attack
    jump: {
      // sequence of frames (can be non-consecutive)
      frames: [1, 10, 1],
      frameRate: 10,
      loop: false,
    },
    walk: {
      // ascending consecutive frame animation (frames 2-6, inclusive)
      frames: '2..6',
      frameRate: 20
    },
    moonWalk: {
      // descending consecutive frame animation (frames 6-2, inclusive)
      frames: '6..2',
      frameRate: 20
    },
    attack: {
      // you can also mix and match, in this case frames [8,9,10,13,10,9,8]
      frames: ['8..10', 13, '10..8'],
      frameRate: 10,
      loop: false,
    }
  });
};

import { Sprite, SpriteSheet } from 'kontra';

let image = new Image();
image.src = 'assets/imgs/character_walk_sheet.png';
image.onload = function() {

  let spriteSheet = SpriteSheet({
    image: image,
    frameWidth: 72,
    frameHeight: 97,

    // this will also call createAnimations()
    animations: {
      // create 1 animation: idle
      idle: {
        // a single frame
        frames: 1
      }
    }
  });

  spriteSheet.createAnimations({
    // create 4 animations: jump, walk, moonWalk, attack
    jump: {
      // sequence of frames (can be non-consecutive)
      frames: [1, 10, 1],
      frameRate: 10,
      loop: false,
    },
    walk: {
      // ascending consecutive frame animation (frames 2-6, inclusive)
      frames: '2..6',
      frameRate: 20
    },
    moonWalk: {
      // descending consecutive frame animation (frames 6-2, inclusive)
      frames: '6..2',
      frameRate: 20
    },
    attack: {
      // you can also mix and match, in this case frames [8,9,10,13,10,9,8]
      frames: ['8..10', 13, '10..8'],
      frameRate: 10,
      loop: false,
    }
  });
};

Parameters

animations

Object. Object of named animations to create from the sprite sheet.

animations.<name>.frames

Number or String or an Array of Numbers or an Array of Strings. The sequence of frames to use from the sprite sheet. It can either be a single frame (1), a sequence of frames ([1,2,3,4]), or a consecutive frame notation ('1..4'). Sprite sheet frames are 0 indexed.

animations.<name>.frameRate

Number. The number frames to display per second.

animations.<name>.loop Optional

Boolean. If the animation should loop back to the beginning once completed. Defaults to true.

SpriteSheet​.frame

Object. An object that defines properties of a single frame in the sprite sheet. It has properties of width, height, spacing, and margin.

width and height are the width of a single frame, while spacing defines the amount of whitespace between each frame, and margin defines the amount of whitespace border around the image.

SpriteSheet​.image

HTMLImageElement or HTMLCanvasElement. The sprite sheet image.