Pool(​properties)

Basic Use #

To use the pool, you must pass the create() function argument. The create function should return a new instance of an object or Sprite. This object will be added to the pool every time there are no more alive objects.

The object must implement the functions update(), render(), init(), and isAlive(). If one of these functions is missing the pool will throw an error. Sprite defines these functions for you.

An object is available for reuse when its isAlive() function returns false. For a sprite, this is typically when its ttl is 0.

When you want an object from the pool, use the pools get() function and pass it any properties you want the newly initialized object to have.

let { Pool, Sprite } = kontra;

let pool = Pool({
  // create a new sprite every time the pool needs a new object.
  // equivalent to `create(props) { return Sprite(props) }`
  create: Sprite
});

// properties will be passed to the sprites init() function
pool.get({
  x: 100,
  y: 200,
  width: 20,
  height: 40,
  color: 'red',
  ttl: 60
});

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

let pool = Pool({
  // create a new sprite every time the pool needs a new object.
  // equivalent to `create(props) { return Sprite(props) }`
  create: Sprite
});

// properties will be passed to the sprites init() function
pool.get({
  x: 100,
  y: 200,
  width: 20,
  height: 40,
  color: 'red',
  ttl: 60
});

import { Pool, Sprite } from 'kontra';

let pool = Pool({
  // create a new sprite every time the pool needs a new object.
  // equivalent to `create(props) { return Sprite(props) }`
  create: Sprite
});

// properties will be passed to the sprites init() function
pool.get({
  x: 100,
  y: 200,
  width: 20,
  height: 40,
  color: 'red',
  ttl: 60
});

When you want to update or render all alive objects in the pool, use the pools update() and render() functions.

let { GameLoop } = kontra;

let loop = GameLoop({
  update: function() {
    pool.update();
  },
  render: function() {
    pool.render();
  }
});

import { GameLoop } from 'path/to/kontra.mjs';

let loop = GameLoop({
  update: function() {
    pool.update();
  },
  render: function() {
    pool.render();
  }
});

import { GameLoop } from 'kontra';

let loop = GameLoop({
  update: function() {
    pool.update();
  },
  render: function() {
    pool.render();
  }
});

Pool​.clear(​) #

Clear the object pool. Removes all objects from the pool and resets its size to 1.

Pool​.get(​[properties]) #

Get and return an object from the pool. The properties parameter will be passed directly to the objects init() function. If you're using a Sprite, you should also pass the ttl property to designate how many frames you want the object to be alive for.

If you want to control when the sprite is ready for reuse, pass Infinity for ttl. You'll need to set the sprites ttl to 0 when you're ready for the sprite to be reused.

let sprite = pool.get({
  // the object will get these properties and values
  x: 100,
  y: 200,
  width: 20,
  height: 40,
  color: 'red',

  // pass Infinity for ttl to prevent the object from being reused
  // until you set it back to 0
  ttl: Infinity
});

get Parameters

properties Optional

Object. Properties to pass to the objects init() function.

get Return value

Object. The newly initialized object.

Pool​.getAliveObjects(​) #

Returns an array of all alive objects. Useful if you need to do special processing on all alive objects outside of the pool, such as to add all alive objects to a Quadtree.

getAliveObjects Return value

An Array of Objects. An Array of all alive objects.

Pool​.maxSize #

Number. The maximum number of objects allowed in the pool. The pool will never grow beyond this size.

Pool​.objects #

An Array of Objects. All objects currently in the pool, both alive and not alive.

Pool​.render(​) #

Render all alive objects in the pool by calling the objects render() function.

Pool​.size #

Number. The number of alive objects.

Pool​.update(​[dt]) #

Update all alive objects in the pool by calling the objects update() function. This function also manages when each object should be recycled, so it is recommended that you do not call the objects update() function outside of this function.

update Parameters

dt Optional

Number. Time since last update.