Kontra​.pool(​properties)

Basic Use#

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

The object must implement the functions update(dt), init(properties), and isAlive(). If one of these functions is missing the pool will throw an error. kontra.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 need an object from the pool, use the pools get() function and pass it any properties you want the reused object to have.

let pool = kontra.pool({
  create: kontra.sprite  // create a new sprite every time the pool needs new objects
});

pool.get({
  x: 100,
  y: 200,
  width: 20,
  height: 40,
  color: 'red',
  ttl: 60
});

Notice that the get() function doesn't return an object. This is because the object pool keeps track of all objects internally. When you need to update or render all in use objects in the pool, use the pools update() and render() functions.

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

kontra.pool​.clear()#

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

kontra.pool​.get(properties)#

properties {object}

Optional. Properties to pass to the objects init(properties) function.

Get and return an object from the pool. The properties parameter will be passed directly to the objects init(properties) function. If you're using kontra.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
});

kontra.pool​.getAliveObjects()#

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

kontra.pool​.maxSize#

{number}

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

kontra.pool​.objects#

{object[]}

All objects currently in the pool, both in use and not in use.

kontra.pool​.render()#

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

kontra.pool​.size#

{number}

The number of objects currently in use.

kontra.pool​.update(dt)#

dt {number}

Optional. Time since last update.

Update all in use 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.