Pool(​properties)

A fast and memory efficient object pool for sprite reuse. Perfect for particle systems or SHUMPs. The pool starts out with just one object, but will grow in size to accommodate as many objects as are needed.

Pool Parameters

properties

Object. Properties of the pool.

properties.create

Function. Function that returns a new object to be added to the pool when there are no more alive objects.

properties.maxSize Optional

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

Table of Contents

Basic Use

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

The object must implement the functions update(), 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
  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
  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
  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

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

get Return value

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 add all alive objects to a Quadtree.

getAliveObjects Return value

An Array of all alive objects.

Pool​.maxSize

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

Pool​.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

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.