# 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`.

## 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.