Manual

Replicator provides GameObject pooling for Unity projects. Pooling can improve performance where an object would be Instantiated and Destroyed repeatedly. To facilitate this, Replicator operates using operations analogous to Instantiate and Destroy, namely Spawn and Recycle. It also provides a way to hook-in to the spawn/release cycle (see Custom).

Contents:

• Basics
• Getting Started
• ObjectPool
  • Configuration
  • Use
• MultiObjectPool
• Cleanup
• Custom

Basics

An object pool is a collection of inactive GameObjects which will be needed for creation. These are (usually) pre-loaded to avoid costly runtime Instantiate() calls. Spawning an object gets an available inactive GameObject from the pool, and prepares it for use. Recycling an object avoids the performance costs associated with Destroy() calls, by deactivating an object and returning it to the pool for re-use.

The core of Replicator is based around the asset, ObjectPool. These pools are assets in your Unity project, making them simple to manage. ObjectPools provide Spawn and Recycle functionality for pooled objects, with a similar set of options available as via Unity's built-in Instantiate and Destroy methods.

To assist in handling components that require cleanup, Replicator provides cleanup scripts.

Getting Started

To make use of pooling for a prefab, you'll need to create an ObjectPool in your project. These can be created through Unity's asset creation menus, in the toolbar or the project window.

Once the pool is configured (refer to ObjectPool below), it can be used in your scripts with a public (or otherwise serialized) field, allowing the assignment of the project asset:

public ObjectPool pool;

ObjectPool

An ObjectPool is both a runtime pool of GameObjects which can be used for spawning / recycling GameObjects and the project asset which represents the pool.

Configuration

ObjectPools contain the following options:

• Prefab: a GameObject, the prefab that the pool will spawn
• Pre Load: an integer
  • Defaults to being equal to Capacity
  • The number of instances to create when the game loads, the others being instantiated as requested until the capacity is exhausted
• Capacity: an integer, the capacity of the pool (not including growth, if applicable)
• Growth: a multi-select, which determines how the pool will grow, or if it will. Used when more objects are requested and the pool does not have any available to spawn (changed in 0.3.0-alpha)
  • None: The pool will not grow
  • Single: The pool will grow by one each time an object is requested and one is not available
  • Tenth: The pool will increase in size equal to 1/10 of its capacity
  • Quarter: The pool will increase in size equal to 1/4 of its capacity
  • Half: The pool will increase in size equal to 1/2 of its capacity
  • Double: The pool will increase in size to double its capacity
• Hide Unspawned: a checkbox, determines if inactive objects in the pool will be shown in the hierarchy

Use

To spawn and recycle a GameObject from the pool:

using Replicator;

public class MyScript : MonoBehaviour {
    public ObjectPool pool;
    
    void Update() {
        GameObject clone = pool.Spawn(Vector3.zero, Quaternion.identity);
        pool.Recycle(clone);
    }
}

For more information on the ways to spawn / recycle GameObjects, please refer to the API Reference.

MultiObjectPool (from 0.2.0-alpha)

A variant of ObjectPool. Allows multiple prefabs to be pooled, and when spawned will choose one at random. Configuration is the same as for ObjectPools. Use is identical to ObjectPool.

It differs from regular ObjectPools only in that it provides an interface for slecting and ordering the variants that the pool can spawn. Order has no effect on probability of spawning an object.

Cleanup

Replicator provides cleanup scripts to reset components after recycling for the following components:

• Rigidbody
• Rigidbody2D
• ParticleSystem (from 0.2.0-alpha)

These can be found in the Add Component menus in Unity

Custom

For adding your own handlers to scripts for spawning and recycling, see the API reference for the ISpawned, IRecycled and IPooled interfaces.