# SpriteSheet(​properties)

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

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

### SpriteSheet Parameters

`properties`

  Object. Properties of the sprite sheet.

`properties.image`

  Image 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.frameMargin` Optional

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

`properties.animations` Optional

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

## SpriteSheet​.animations #

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

### createAnimations 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 String[]. 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 #

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

`width` and `height` are the width of a single frame, while `margin` defines the amount of whitespace between each frame.

## SpriteSheet​.image #

The sprite sheet image.