Skip navigation

Sprite(​[properties])

A versatile way to update and draw your sprites. It can handle simple rectangles, images, and sprite sheet animations. It can be used for your main player object as well as tiny particles in a particle engine.

Extends: GameObject

Parameters

properties Optional

Object. Properties of the sprite.

properties.color Optional

String. Fill color for the game object if no image or animation is provided.

properties.image Optional

HTMLImageElement or HTMLCanvasElement. Use an image to draw the sprite.

properties.animations Optional

Object. An object of Animations from a Spritesheet to animate the sprite.

Table of Contents

Rectangle Sprite

In its most basic form, a sprite is a rectangle with a fill color. To create a rectangle sprite, pass the arguments width, height, and color. A rectangle sprite is great for initial prototyping and particles.

let { Sprite } = kontra

let sprite = Sprite({
  x: 300,
  y: 100,
  anchor: {x: 0.5, y: 0.5},

  // required for a rectangle sprite
  width: 20,
  height: 40,
  color: 'red'
});

sprite.render();
import { Sprite } from 'path/to/kontra.mjs'

let sprite = Sprite({
  x: 300,
  y: 100,
  anchor: {x: 0.5, y: 0.5},

  // required for a rectangle sprite
  width: 20,
  height: 40,
  color: 'red'
});

sprite.render();
import { Sprite } from 'kontra';

let sprite = Sprite({
  x: 300,
  y: 100,
  anchor: {x: 0.5, y: 0.5},

  // required for a rectangle sprite
  width: 20,
  height: 40,
  color: 'red'
});

sprite.render();

Image Sprite

A sprite can use an image instead of drawing a rectangle. To create an image sprite, pass the image argument. The size of the sprite will automatically be set as the width and height of the image.

let { Sprite } = kontra

let image = new Image();
image.src = 'assets/imgs/character.png';
image.onload = function() {
  let sprite = Sprite({
    x: 300,
    y: 100,
    anchor: {x: 0.5, y: 0.5},

    // required for an image sprite
    image: image
  });

  sprite.render();
};
import { Sprite } from 'path/to/kontra.mjs'

let image = new Image();
image.src = 'assets/imgs/character.png';
image.onload = function() {
  let sprite = Sprite({
    x: 300,
    y: 100,
    anchor: {x: 0.5, y: 0.5},

    // required for an image sprite
    image: image
  });

  sprite.render();
};
import { Sprite } from 'kontra';

let image = new Image();
image.src = 'assets/imgs/character.png';
image.onload = function() {
  let sprite = Sprite({
    x: 300,
    y: 100,
    anchor: {x: 0.5, y: 0.5},

    // required for an image sprite
    image: image
  });

  sprite.render();
};

Animation Sprite

A sprite can use a spritesheet animation as well. To create an animation sprite, pass the animations argument. The size of the sprite will automatically be set as the width and height of a frame of the spritesheet.

A sprite can have multiple named animations. The easiest way to create animations is to use SpriteSheet. All animations will automatically be cloned so no two sprites update the same animation.

let { Sprite, SpriteSheet, GameLoop } = kontra

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

  // use spriteSheet to create animations from an image
  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: 300,
    y: 100,
    anchor: {x: 0.5, y: 0.5},

    // required for an animation sprite
    animations: spriteSheet.animations
  });

  // use kontra.gameLoop to play the animation
  let loop = GameLoop({
    update: function(dt) {
      sprite.update();
    },
    render: function() {
      sprite.render();
    }
  });

  loop.start();
};
import { Sprite, SpriteSheet, GameLoop } from 'path/to/kontra.mjs'

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

  // use spriteSheet to create animations from an image
  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: 300,
    y: 100,
    anchor: {x: 0.5, y: 0.5},

    // required for an animation sprite
    animations: spriteSheet.animations
  });

  // use kontra.gameLoop to play the animation
  let loop = GameLoop({
    update: function(dt) {
      sprite.update();
    },
    render: function() {
      sprite.render();
    }
  });

  loop.start();
};
import { Sprite, SpriteSheet, GameLoop } from 'kontra';

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

  // use spriteSheet to create animations from an image
  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: 300,
    y: 100,
    anchor: {x: 0.5, y: 0.5},

    // required for an animation sprite
    animations: spriteSheet.animations
  });

  // use kontra.gameLoop to play the animation
  let loop = GameLoop({
    update: function(dt) {
      sprite.update();
    },
    render: function() {
      sprite.render();
    }
  });

  loop.start();
};

Custom Properties

If you need to draw a different shape, such as a circle, you can pass in custom properties and a render function to handle drawing the sprite.

Do note that the canvas has been rotated and translated to the sprites position (taking into account anchor), so {0,0} will be the top-left corner of the sprite when drawing.

let { Sprite } = kontra

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

  color: 'red',

  // custom properties
  radius: 20,

  render: function() {
    this.context.fillStyle = this.color;

    this.context.beginPath();
    this.context.arc(0, 0, this.radius, 0, 2  * Math.PI);
    this.context.fill();
  }
});

sprite.render();
import { Sprite } from 'path/to/kontra.mjs'

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

  color: 'red',

  // custom properties
  radius: 20,

  render: function() {
    this.context.fillStyle = this.color;

    this.context.beginPath();
    this.context.arc(0, 0, this.radius, 0, 2  * Math.PI);
    this.context.fill();
  }
});

sprite.render();
import { Sprite } from 'kontra';

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

  color: 'red',

  // custom properties
  radius: 20,

  render: function() {
    this.context.fillStyle = this.color;

    this.context.beginPath();
    this.context.arc(0, 0, this.radius, 0, 2  * Math.PI);
    this.context.fill();
  }
});

sprite.render();

Extending a Sprite

If you want to extend a Sprite, you can do so by extending the Sprite class. The one caveat is that Sprite is not the Sprite class, but actually is a factory function. To extend the Sprite class, import SpriteClass from kontra.

You should also override the draw() function instead of the render() function in your class. The draw() function determines how to draw the Sprite. It is called by the render function after transforms and rotations have been applied.

Do note that the canvas has been rotated and translated to the objects position (taking into account anchor), so {0,0} will be the top-left corner of the game object when drawing.

let { Sprite, SpriteClass } = kontra;

class CustomSprite extends SpriteClass {
  constructor(properties) {
    super(properties);
    this.myProp = properties.myProp;
  }

  draw() {
    if (this.myProp) {
      super.draw();
    }
  }
}

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

class CustomSprite extends SpriteClass {
  constructor(properties) {
    super(properties);
    this.myProp = properties.myProp;
  }

  draw() {
    if (this.myProp) {
      super.draw();
    }
  }
}

import { Sprite, SpriteClass } from 'kontra';

class CustomSprite extends SpriteClass {
  constructor(properties) {
    super(properties);
    this.myProp = properties.myProp;
  }

  draw() {
    if (this.myProp) {
      super.draw();
    }
  }
}

Sprite​.animations

Object. An object of Animations from a SpriteSheet to animate the sprite. Each animation is named so that it can can be used by name for the sprites playAnimation() function.

let { Sprite, SpriteSheet } = kontra;

let spriteSheet = SpriteSheet({
  // ...
  animations: {
    idle: {
      frames: 1,
      loop: false,
    },
    walk: {
      frames: [1,2,3]
    }
  }
});

let sprite = Sprite({
  x: 100,
  y: 200,
  animations: spriteSheet.animations
});

sprite.playAnimation('idle');

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

let spriteSheet = SpriteSheet({
  // ...
  animations: {
    idle: {
      frames: 1,
      loop: false,
    },
    walk: {
      frames: [1,2,3]
    }
  }
});

let sprite = Sprite({
  x: 100,
  y: 200,
  animations: spriteSheet.animations
});

sprite.playAnimation('idle');

import { Sprite, SpriteSheet } from 'kontra';

let spriteSheet = SpriteSheet({
  // ...
  animations: {
    idle: {
      frames: 1,
      loop: false,
    },
    walk: {
      frames: [1,2,3]
    }
  }
});

let sprite = Sprite({
  x: 100,
  y: 200,
  animations: spriteSheet.animations
});

sprite.playAnimation('idle');

Sprite​.color

String. The color of the game object if it was passed as an argument.

Sprite​.currentAnimation

Animation. The currently playing Animation object if animations was passed as an argument.

Sprite​.height

Number. The height of the sprite. If the sprite is a rectangle sprite, it uses the passed in value. For an image sprite it is the height of the image. And for an animation sprite it is the height of a single frame of the animation.

Sprite​.image

HTMLImageElement or HTMLCanvasElement. The image the sprite will use when drawn if passed as an argument.

Sprite​.playAnimation(​name)

Set the currently playing animation of an animation sprite.

let { Sprite, SpriteSheet } = kontra;

let spriteSheet = SpriteSheet({
  // ...
  animations: {
    idle: {
      frames: 1
    },
    walk: {
      frames: [1,2,3]
    }
  }
});

let sprite = Sprite({
  x: 100,
  y: 200,
  animations: spriteSheet.animations
});

sprite.playAnimation('idle');

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

let spriteSheet = SpriteSheet({
  // ...
  animations: {
    idle: {
      frames: 1
    },
    walk: {
      frames: [1,2,3]
    }
  }
});

let sprite = Sprite({
  x: 100,
  y: 200,
  animations: spriteSheet.animations
});

sprite.playAnimation('idle');

import { Sprite, SpriteSheet } from 'kontra';

let spriteSheet = SpriteSheet({
  // ...
  animations: {
    idle: {
      frames: 1
    },
    walk: {
      frames: [1,2,3]
    }
  }
});

let sprite = Sprite({
  x: 100,
  y: 200,
  animations: spriteSheet.animations
});

sprite.playAnimation('idle');

Parameters

name

String. Name of the animation to play.

Sprite​.width

Number. The width of the sprite. If the sprite is a rectangle sprite, it uses the passed in value. For an image sprite it is the width of the image. And for an animation sprite it is the width of a single frame of the animation.