Scene(​properties, ...properties.props)

A scene object for organizing a group of objects that will update and render together.

let { Scene, Sprite } = kontra;

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

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

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

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

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

scene.render();
import { Scene, Sprite } from 'kontra';

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

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

scene.render();

Scene Parameters

properties

Object. Properties of the scene.

properties.id

String. The id of the scene.

properties.name Optional

String. The name of the scene. Used by screen readers to identify each scene. Use this property to give the scene a human friendly name. Defaults to properties.id.

properties.objects Optional

An Array of Objects. Objects to add to the scene.

properties.context Optional

CanvasRenderingContext2D. The context the scene should draw to. Defaults to core.getContext().

properties.cullObjects Optional

Boolean. If the scene should not render objects outside the camera bounds. Defaults to true.

properties.cullFunction Optional

Function. The function used to filter objects to render. Defaults to helpers.collides.

properties.sortFunction Optional

Function. The function used to sort the objects of the scene.

properties.onShow Optional

Function. Function called when the scene is shown.

properties.onHide Optional

Function. Function called when the scene is hidden.

...properties.props

A list of any type. Any additional properties you need added to the scene.

Table of Contents

Scene​.add(​...objects)

Add an object to the scene.

add Parameters

...objects

A list of (Object or Array of Objects). Object to add. Can be a single object, an array of objects, or a comma-separated list of objects.

Scene​.camera

GameObject. The camera object which is used as the focal point for the scene. Defaults to to the size of the canvas with a focal point at its center. The scene will not render objects that are outside the bounds of the camera.

Additionally, the camera can be used to lookAt an object which will center the camera to that object. This allows you to zoom the scene in and out while the camera remains centered on the object.

Scene​.context

CanvasRenderingContext2D. The context the scene will draw to.

Scene​.cullFunction

Function. Camera culling function which prevents objects outside the camera screen from rendering.

Scene​.cullObjects

Boolean. If the camera should cull objects outside the camera bounds. Not rendering objects which can't be seen greatly improves the performance.

Scene​.destroy(​)

Clean up the scene and call destroy() on all objects.

Scene​.hidden

Boolean. If the scene is hidden.

Scene​.hide(​)

Hide the scene. A hidden scene will not update or render. Calls onHide if passed.

Scene​.id

String. The id of the scene.

Scene​.lookAt(​object)

Focus the camera to the objects x/y position. As the scene is scaled the focal point will keep to the position.

lookAt Parameters

object

Object. Object to look at.

Scene​.name

String. The name of the scene. Used by screen readers to identify each scene. Use this property to give the scene a human friendly name.

Scene​.node

HTMLElement. The HTML section element associated with the scene (used for accessibility). Typically you won't need to interact with the node directly, but it can be useful to move its position in the DOM to better support accessible component design.

Scene​.objects

An Array of Objects. The objects of the scene.

Scene​.onHide(​)

Function called when the scene is hidden. Override this function to have the scene do something when hidden, such as cleaning up input events.

let { Scene, offKey } = 'kontra';

let scene = Scene({
  onHide() {
    offKey('arrowup');
  }
});
let { Scene, offKey } = 'kontra';

let scene = Scene({
  onHide() {
    offKey('arrowup');
  }
});
let { Scene, offKey } = 'kontra';

let scene = Scene({
  onHide() {
    offKey('arrowup');
  }
});

Scene​.onShow(​)

Function called when the scene is shown. Override this function to have the scene do something when shown, such as adding input events.

let { Scene, onKey } = 'kontra';

let scene = Scene({
  onShow() {
    onKey('arrowup', () => {
      // ...
    })
  }
});
let { Scene, onKey } = 'kontra';

let scene = Scene({
  onShow() {
    onKey('arrowup', () => {
      // ...
    })
  }
});
let { Scene, onKey } = 'kontra';

let scene = Scene({
  onShow() {
    onKey('arrowup', () => {
      // ...
    })
  }
});

Scene​.remove(​...objects)

Remove an object from the scene.

remove Parameters

...objects

A list of (Object or Array of Objects). Object to remove. Can be a single object, an array of objects, or a comma-separated list of objects.

Scene​.render(​)

Render all objects of the scene by calling the objects render() function. If cullObjects is set to true then only those objects which are inside the camera bounds will be rendered.

Scene​.show(​)

Show the scene and resume update and render. Calls onShow if passed.

Scene​.sortFunction

Function. Function used to sort the objects of the scene before rendering. Can be used in conjunction with helpers.depthSort. Only direct objects of the scene are sorted.

let { Scene, Sprite, depthSort } = kontra;

let sprite1 = Sprite({
  // ...
});
let sprite2 = Sprite({
  // ...
});

let scene = Scene({
  id: 'game',
  objects: [sprite1, sprite2],
  sortFunction: depthSort
});

scene.render();
import { Scene, Sprite, depthSort } from 'path/to/kontra.mjs';

let sprite1 = Sprite({
  // ...
});
let sprite2 = Sprite({
  // ...
});

let scene = Scene({
  id: 'game',
  objects: [sprite1, sprite2],
  sortFunction: depthSort
});

scene.render();
import { Scene, Sprite, depthSort } from 'kontra';

let sprite1 = Sprite({
  // ...
});
let sprite2 = Sprite({
  // ...
});

let scene = Scene({
  id: 'game',
  objects: [sprite1, sprite2],
  sortFunction: depthSort
});

scene.render();

Scene​.update(​[dt])

Update all objects of the scene by calling the objects update() function.

update Parameters

dt Optional

Number. Time since last update.