Click or drag to resize

GameObjectPool Class

[This is preliminary documentation and is subject to change.]

A MonoBehaviour component that provides pooling of many instances of a single GameObject, allowing the game objects to be recycled and reused.
Inheritance Hierarchy
System.Object
  UnityEngine.Object
    UnityEngine.Component
      UnityEngine.Behaviour
        UnityEngine.MonoBehaviour
          Umbrace.Unity.PurePool.PoolBase<GameObject, GameObject, GameObjectPoolSettings>
            Umbrace.Unity.PurePool.GameObjectPool

Namespace:  Umbrace.Unity.PurePool
Assembly:  Umbrace.Unity.PurePool (in Umbrace.Unity.PurePool.dll) Version: 0.0.0.0 (1.0.0.0)
Syntax
C#
public class GameObjectPool : PoolBase<GameObject, GameObject, GameObjectPoolSettings>, 
	IGameObjectPoolSettings, ISharedPoolSettings<GameObject>, ISharedPoolSettings

The GameObjectPool type exposes the following members.

Constructors
  NameDescription
Public methodGameObjectPool
Initializes a new instance of the GameObjectPool class
Top
Properties
  NameDescription
Public propertyCanAcquire

Gets a value indicating whether an instance can be acquired from the pool.

An instance can be acquired when the pool contains at least one instance, or when InstantiateWhenEmpty is true.

(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyCount
Gets the number of objects currently contained by the pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyDefinition
Gets the settings that were used to initialise this pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyDontDestroyOnLoad
Gets or sets a value indicating whether the pool should persist between scene changes.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyEnabled
Gets or sets a value indicating whether pooling is enabled.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyInitialiseOnStart
Gets or sets a value indicating whether to initialise the pool in the MonoBehaviour Start method. Cannot be set once the pool has been initialised.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyInitialSize
Gets or sets the initial size of the pool. Cannot be set once the pool has been initialised.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyInstantiateWhenEmpty
Gets or sets a value indicating whether to instantiate a new object when the pool is empty, and an attempt is made to acquire from the pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyIsEmpty
Gets a value indicating whether the pool is empty and contains no objects.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyIsInitialised
Gets a value indicating whether the pool has been initialised.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyItems
Gets a list of items currently contained by the pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyLogMessages
Gets or sets the level of log messaging that the pool will output.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyMaximumSize
Gets or sets the maximum size of the pool, which is the maximum number of objects it can contain.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyNotificationMode
Gets or sets the modes in which pooled objects are notified of their acquisition from, and release to, the pool.
(Overrides PoolBase<TSource, TInstance, TSettings>.NotificationMode.)
Protected propertyPool
When implemented in a derived class, gets or sets the internal object pool.
(Overrides PoolBase<TSource, TInstance, TSettings>.Pool.)
Public propertyRecordStatistics
Gets or sets a value indicating whether to record pool statistics.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyReparentPooledObjects
Gets or sets a value indicating whether to re-parent the pooled objects to the pool's Transform, after the objects are returned to the pool.
(Overrides PoolBase<TSource, TInstance, TSettings>.ReparentPooledObjects.)
Public propertySource
Gets or sets the source object that will be pooled.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyStatistics
Gets an object containing general operational statistics about the pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public propertyWarnOnDestroy
Gets or sets a value indicating whether to log a warning message when a poolable object is destroyed (either inside of the pool, or while in use).
(Overrides PoolBase<TSource, TInstance, TSettings>.WarnOnDestroy.)
Top
Methods
  NameDescription
Public methodAcquire()
Acquires an instance from the pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public methodAcquire(Transform)
Acquires an instance of the source object, and sets its parent transform.
Public methodAcquire(Transform, Boolean)
Acquires an instance of the source object, and sets its parent transform.
Public methodAcquire(Vector3, Quaternion)
Acquires an instance of the source object, and sets its position and rotation.
Public methodAcquire(Vector3, Quaternion, Transform)
Acquires an instance of the source object, and sets its parent transform, position and rotation.
Protected methodCanInitialise
When overridden in a derived class, determines whether the pool can be initialised.
(Overrides PoolBase<TSource, TInstance, TSettings>.CanInitialise().)
Public methodClear
Clears the pool, emptying it of all pooled objects.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Protected methodCreateInternalPool
When implemented in a derived class, creates the internal object pool.
(Overrides PoolBase<TSource, TInstance, TSettings>.CreateInternalPool().)
Protected methodCreateSettingsClone
When implemented in a derived class, creates a new instance of TSettings that is an exact copy of the specified settings.
(Overrides PoolBase<TSource, TInstance, TSettings>.CreateSettingsClone(TSettings).)
Protected methodDestroyInstance
When implemented in a derived class, destroys the specified instance.
(Overrides PoolBase<TSource, TInstance, TSettings>.DestroyInstance(TInstance).)
Public methodEquals (Inherited from Object.)
Public methodFill
Fills the pool, populating it with pooled objects until it reaches the maximum pool size.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Protected methodFinalize (Inherited from Object.)
Public methodGetHashCode (Inherited from Object.)
Public methodGetItems (Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public methodGetType (Inherited from Object.)
Public methodGrow
Increases the number of objects contained by the pool by the specified amount.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public methodInitialise()
Initialises the pool, populating it with the initial number of objects.
(Overrides PoolBase<TSource, TInstance, TSettings>.Initialise().)
Public methodInitialise(TSettings)
Initialises the pool, populating it with the initial number of objects.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Protected methodMemberwiseClone (Inherited from Object.)
Protected methodOnCanAcquireChanged
Raises the CanAcquireChanged event.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Protected methodOnCountChanged
Raises the CountChanged event.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Protected methodOnDestroy (Overrides PoolBase<TSource, TInstance, TSettings>.OnDestroy().)
Protected methodOnDestroyed
Raises the Destroyed event.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Protected methodOnInitialised
Raises the Initialised event.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Protected methodOnObjectAcquired
Raises the ObjectAcquired event.
(Overrides PoolBase<TSource, TInstance, TSettings>.OnObjectAcquired(TInstance, Boolean).)
Protected methodOnObjectDestroyed
Raises the ObjectDestroyed event.
(Overrides PoolBase<TSource, TInstance, TSettings>.OnObjectDestroyed(TInstance).)
Protected methodOnObjectInstantiated
Raises the ObjectInstantiated event.
(Overrides PoolBase<TSource, TInstance, TSettings>.OnObjectInstantiated(TInstance).)
Protected methodOnObjectReleased
Raises the ObjectReleased event.
(Overrides PoolBase<TSource, TInstance, TSettings>.OnObjectReleased(TInstance, Boolean).)
Public methodRelease
Releases an instance back to the pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public methodSetSize
Sets the number of objects contained by the pool, either destroying excess pooled objects, or instantiating new ones.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public methodShrink
Decreases the number of objects contained by the pool by the specified amount.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Protected methodStart (Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public methodToString (Inherited from Object.)
Public methodTryAcquire(TInstance)
Acquires an instance from the pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public methodTryAcquire(Transform, GameObject)
Acquires an instance of the source object, and sets its parent transform.
Public methodTryAcquire(Transform, Boolean, GameObject)
Acquires an instance of the source object, and sets its parent transform.
Public methodTryAcquire(Vector3, Quaternion, GameObject)
Acquires an instance of the source object, and sets its position and rotation.
Public methodTryAcquire(Vector3, Quaternion, Transform, GameObject)
Acquires an instance of the source object, and sets its parent transform, position and rotation.
Top
Events
  NameDescription
Public eventCanAcquireChanged
Occurs when the value of CanAcquire changes.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public eventCountChanged
Occurs when Count changes.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public eventDestroyed
Occurs when the pool is destroyed.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public eventInitialised
Occurs when the pool is initialised.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public eventObjectAcquired
Occurs when an instance of the source object is acquired from the pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public eventObjectDestroyed
Occurs when an instance of the source object is destroyed.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public eventObjectInstantiated
Occurs when a new instance of the source object is instantiated.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Public eventObjectReleased
Occurs when an instance of the source object is released back to the pool.
(Inherited from PoolBase<TSource, TInstance, TSettings>.)
Top
Fields
  NameDescription
Public fieldObjectAcquiredEvent
Occurs when an instance of the source object is acquired from the pool.
Public fieldObjectDestroyedEvent
Occurs when an instance of the source object is destroyed.
Public fieldObjectInstantiatedEvent
Occurs when a new instance of the source object is instantiated.
Public fieldObjectReleasedEvent
Occurs when an instance of the source object is released back to the pool.
Top
Remarks

By virtue of being serialisable, GameObjectPool can survive an assembly reload caused by live recompilation inside of the Unity editor.

To use the GameObjectPool, add a new instance of the component to a GameObject, and then set the properties to appropriate values. Once all properties have been set, invoke the Initialise() method. A pool cannot be used without being initialised.

Examples
C#
// Create the pool as a component on a game object.
var pool = gameObject.AddComponent<GameObjectPool>();

// Set up the pool's properties.
pool.SourceObject = prefab;
pool.InitialSize = 50;
pool.MaximumSize = 200;
pool.InstantiateWhenEmpty = true;
pool.NotificationMode = NotificationMode.Interface;
pool.LogMessages = LogLevel.Warning;

// Initialise the pool. It will contain 50 objects.
pool.Initialise();

// Acquire one of the 50 objects from the pool. The Acquire method can be used safely if InstantiateWhenEmpty is true, or if a check is made to CanAcquire beforehand.
GameObject instance = pool.Acquire();

// Acquire one of the 49 remaining objects from the pool. TryAcquire can be used safely even when InstantiateWhenEmpty is false.
GameObject secondInstance;
if (pool.TryAcquire(out secondInstance)) {
    // Release the object back to the pool. It now contains 49 objects again.
    pool.Release(secondInstance);
}

// Release the object back to the pool. It now contains 50 objects.
pool.Release(instance);
See Also