Kontra.js

Use the Scene factory function to organize a group of objects that will update and render together. A scene manages a collection of objects, a camera for viewport control, and an accessible DOM node for screen readers.

Configuration Options

When creating a scene, you can pass an options object with the following properties:

• id (String): The unique identifier for the scene.
• name (String, optional): A human-friendly name used for screen reader accessibility. Defaults to id.
• objects (Object[], optional): An initial array of objects to add to the scene.
• context (CanvasRenderingContext2D, optional): The canvas context to draw to. Defaults to the result of core.getContext().
• cullObjects (Boolean, optional): If true, objects outside the camera bounds will not be rendered. Defaults to true.
• cullFunction (Function, optional): The function used to filter objects for rendering. Defaults to helpers.collides.
• sortFunction (Function, optional): The function used to sort objects before rendering (e.g., for depth sorting).
• onShow (Function, optional): Callback triggered when the scene is shown.
• onHide (Function, optional): Callback triggered when the scene is hidden.
• props (Object, optional): Any additional properties to be assigned to the scene instance.

import { Scene, Sprite } from 'kontra';

const sprite = Sprite({
  x: 100,
  y: 200,
  width: 20,
  height: 40,
  color: 'red'
});

const scene = Scene({
  id: 'game',
  objects: [sprite]
});

scene.render();

To use animations, pass an animations object to the Sprite constructor. This object should contain Animation instances (usually obtained from a SpriteSheet).

When animations are provided:

• The sprite automatically clones each animation so that multiple sprites can use the same sheet without interfering with each other's playback state.
• The currentAnimation is set to the first animation in the list by default.
• You can switch between animations using playAnimation(name).
• The sprite's width and height will default to the dimensions of the animation frames if not explicitly set.

import { Sprite, SpriteSheet } from 'kontra';

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

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

// Play a specific animation by name
sprite.playAnimation('idle');

The TileEngine is used to manage and render tile-based maps. It uses an off-screen canvas to pre-render tiles for performance. You can initialize it by passing a properties object containing map dimensions, tile dimensions, tilesets, and layers.

Properties:

• width (Number): Width of the tile map in number of tiles.
• height (Number): Height of the tile map in number of tiles.
• tilewidth (Number): Width of a single tile in pixels.
• tileheight (Number): Height of a single tile in pixels.
• context (CanvasRenderingContext2D, optional): The context to draw to. Defaults to core.getContext().
• tilesets (Object[], required): Array of tileset objects.
• layers (Object[], required): Array of layer objects.

Tileset Object Properties:

• firstgid (Number): First tile index of the tileset (the first tileset should have firstgid: 1).
• image (String|HTMLImageElement): Path to the image or the element itself. If a path is used, it must be pre-loaded via assets.load.
• spacing (Number, default: 0): Whitespace between tiles in pixels.
• margin (Number, default: 0): Whitespace border around the tileset image.
• tilewidth (Number, optional): Width of the tileset tile. Defaults to engine tilewidth.
• tileheight (Number, optional): Height of the tileset tile. Defaults to engine tileheight.
• columns (Number, optional): Number of columns in the tileset image.
• source (String, optional): Path to a Tiled JSON source file (must be pre-loaded).

Layer Object Properties:

• name (String): Unique name of the layer.
• data (Number[]): 1D array of tile indices.
• visible (Boolean, default: true): Whether the layer is drawn.
• opacity (Number, default: 1): Layer opacity (0 to 1).

import { TileEngine } from 'kontra';

let tileEngine = TileEngine({
  tilewidth: 32,
  tileheight: 32,
  width: 4,
  height: 4,
  tilesets: [{
    firstgid: 1,
    image: myLoadedImage
  }],
  layers: [{
    name: 'background',
    data: [ 1, 1, 1, 1, 1, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]
  }]
});

When initializing a Grid, you can provide the following properties to control its layout behavior: