# XPool - Object Pooling System for Unity [![Release](https://camo.githubusercontent.com/08921bdea90870821699e57d45e2b6d14d11ca372268b7f0d7ce527c7ba4a71e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6d61636b79736f66742f58506f6f6c)](https://github.com/mackysoft/XPool/releases) [![openupm](https://camo.githubusercontent.com/9bd1133c687786a08460429e2f583ca7b1f4fc7d0d004a5faddd9eb3858e4dbd/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f636f6d2e6d61636b79736f66742e78706f6f6c3f6c6162656c3d6f70656e75706d2672656769737472795f7572693d68747470733a2f2f7061636b6167652e6f70656e75706d2e636f6d)](https://openupm.com/packages/com.mackysoft.xpool/) ![XPool_Frame](https://user-images.githubusercontent.com/13536348/154980636-f949151e-f820-4d86-b9e9-302880671d14.png) **Created by Hiroya Aramaki ([Makihiro](https://twitter.com/makihiro_dev))** ## What is XPool ? XPool is an object pooling library for Unity. This was developed to be able to do all the pooling expected in application development with just this library. - All your classes can be pooled. - Short code, easy to use. - Fast performance - Scalability - Tested. It works stably. ## Table of Contents - [📥 Installation](https://github.com/mackysoft/XPool/raw/main/#installation) - [🔰 Usage](https://github.com/mackysoft/XPool/raw/main/#usage) - [Unity Object Pool](https://github.com/mackysoft/XPool/raw/main/#unity-object-pool) - [ParticleSystem Pool](https://github.com/mackysoft/XPool/raw/main/#particle-system-pool) - [Pure C# Object Pool](https://github.com/mackysoft/XPool/raw/main/#object-pool) - [Collection Pool](https://github.com/mackysoft/XPool/raw/main/#collection-pool) - [Non Allocated Collections](https://github.com/mackysoft/XPool/raw/main/#non-allocated-collections) - [How to write custom pool ?](https://github.com/mackysoft/XPool/raw/main/#how-to-write-custom-pool) - [ParticleSystemPool implementation](https://github.com/mackysoft/XPool/raw/main/#particle-system-pool-implementation) - [Optimization](https://github.com/mackysoft/XPool/raw/main/#optimization) - [✉ Help & Contribute](https://github.com/mackysoft/XPool/raw/main/#help-and-contribute) - [📔 Author Info](https://github.com/mackysoft/XPool/raw/main/#author-info) - [📜 License](https://github.com/mackysoft/XPool/raw/main/#license) # 📥 Installation Download any version from releases. Releases: https://github.com/mackysoft/XPool/releases ### Install via PackageManager Or, you can add this package by opening PackageManager and entering `https://github.com/mackysoft/XPool.git?path=Assets/MackySoft/MackySoft.XPool` from the `Add package from git URL` option. ### Install via Open UPM Or, you can install this package from the [Open UPM](https://openupm.com/packages/com.mackysoft.xpool/) registry. More details [here](https://openupm.com/). ``` openupm add com.mackysoft.xpool ``` # 🔰 Usage The full Scripting API is [here](https://mackysoft.github.io/XPool/api/MackySoft.XPool.html). Scripting API: https://mackysoft.github.io/XPool/api/MackySoft.XPool.html ## Unity Object Pool (GameObject, Component) Pooling of Unity Object (GameObject, Component) can be performed using `GameObjectPool` or `ComponentPool`. These hierarchical objects can be rented by writing them in a similar way to `Instantiate` method. ```cs // Example code is being written... ``` ### ParticleSystem Pool Optimized pools are available for some of the components implemented in Unity. This is an example of `ParticleSystemPool` usage. ```cs public class HitParticleSystemEmitter : MonoBehaviour { [SerializeField] ParticleSystemPool m_HitParticleSystemPool = new ParticleSystemPool(); void OnCollisionEnter (Collision collision) { // The rented ParticleSystem is automatically returned to the pool when completed. m_HitParticleSystemPool.Rent(collision.contacts[0],Quaternion.identity); } } ``` If you need an optimized pool for other components, please refer to the [How to write custom pool ?](https://github.com/mackysoft/XPool/raw/main/#how-to-write-custom-pool) section, or give me feedback via [issues](https://github.com/mackysoft/XPool/issues) or [pull requests](https://github.com/mackysoft/XPool/pulls). ## Object Pool (Pure C# Object) `FactoryPool` can be used to pool Pure C# Object. > Unity Object are not supported, as they behave differently from Pure C# Object in that they can be set to null externally with `Destroy` method. ```cs // Give the capacity and factory method to the constructor. var pool = new FactoryPool(8,() => new MyClass()); // Create new instance by factory if pool is empty. MyClass instance = pool.Rent(); // Return instance to the pool. pool.Return(instance); ``` ## Collection Pool (`T[]`, `List`, `Qeueue`, `Stack`, `HashSet`, `Dictionary`) An optimized pool is provided for the generic collections provided in .NET Framework. ```cs // Rent an array from the pool. // Note that the array length to be rented is the next two powers of minimumLength. T[] array = ArrayPool.Shared.Rent(minimumLength: 10); // Return array to the pool. ArrayPool.Shared.Return(array); // ListPool, QueuePool, StackPool, HashSetPool, DictionaryPool are also available. List list = ListPool.Shared.Rent(); Queue queue = QueuePool.Shared.Rent(); Stack stack = StackPool.Shared.Rent(); HashSet hashSet = HashSetPool.Shared.Rent(); Dictionary dictionary = DictionaryPool.Shared.Rent(); ``` ## Non allocated collections You can use the TemporaryCollections API that leverages `ArrayPool`. These collections are a struct and internally use array rented from `ArrayPool`. Therefore, it is fast and non-allocation. ```cs // Create a temporary array. var array = TemporaryArray.Create(10); // You must release collection when you are done using it. array.Dispose(); // TemporaryList, TemporaryQueue, TemporaryStack are also available. TemporaryList list = TemporaryList.Create(); TemporaryQueue queue = TemporaryQueue.Create(); TemporaryStack stack = TemporaryStack.Create(); ``` ## How to write custom pool ? If you want to implement a more customized pool, you can quickly create one by using the provided base classes. The base class of the pool is in the `ObjectModel` namespace. - `MackySoft.XPool.ObjectMode.PoolBase` - `MackySoft.XPool.Unity.ObjectModel.UnityObjectPoolBase` - `MackySoft.XPool.Unity.ObjectModel.ComponentPoolBase` ```cs using MackySoft.XPool.ObjectModel; // PoolBase is here. public class MyPool : PoolBase { public MyPool () { } public MyPool (MyClass original,int capacity) : base(original,capacity) { } // Called when Rent is invoked and there are no instances in the pool. protected override MyClass Factory () { return new MyClass(); } // Called when an instance is rented from the pool. // This is also the case when a new instance is created by the Factory. protected override void OnRent (MyClass instance) { } // Called when an instance is returned to the pool. protected override void OnReturn (MyClass instance) { } // Called when the capacity is exceeded and the instance cannot be returned to the pool, // or when the instance is released by the ReleaseInstances method. protected override void OnRelease (MyClass instance) { } } ``` ### ParticleSystemPool implementation As an example, `ParticleSystemPool` is implemented using `ComponentPoolBase`. Its functionality has been optimized for ParticleSystem. ```cs using System; using UnityEngine; using MackySoft.XPool.Unity.ObjectModel; // ComponentPoolBase is here. [Serializable] public class ParticleSystemPool : ComponentPoolBase { [SerializeField] bool m_PlayOnRent; public bool PlayOnRent { get => m_PlayOnRent; set => m_PlayOnRent = value; } public ParticleSystemPool () { } public ParticleSystemPool (ParticleSystem original,int capacity) : base(original,capacity) { } protected override void OnCreate (ParticleSystem instance) { var main = instance.main; main.stopAction = ParticleSystemStopAction.Callback; var trigger = instance.gameObject.AddComponent(); trigger.Initialize(instance,this); } protected override void OnRent (ParticleSystem instance) { if (m_PlayOnRent) { instance.Play(true); } } protected override void OnReturn (ParticleSystem instance) { instance.Stop(true,ParticleSystemStopBehavior.StopEmitting); } protected override void OnRelease (ParticleSystem instance) { UnityEngine.Object.Destroy(instance.gameObject); } public class ParticleSystemStoppedTrigger : MonoBehaviour { ParticleSystem m_ParticleSystem; IPool m_Pool; internal void Initialize (ParticleSystem ps,IPool pool) { m_ParticleSystem = ps; m_Pool = pool; } void OnParticleSystemStopped () { m_Pool?.Return(m_ParticleSystem); } } } ``` # ✉ Help & Contribute I welcome feature requests and bug reports in [issues](https://github.com/mackysoft/XPool/issues) and [pull requests](https://github.com/mackysoft/XPool/pulls). If you feel that my works are worthwhile, I would greatly appreciate it if you could sponsor me. GitHub Sponsors: https://github.com/sponsors/mackysoft # 📔 Author Info Hiroya Aramaki is a indie game developer in Japan. - Twitter: [https://twitter.com/makihiro_dev](https://twitter.com/makihiro_dev) - Blog: [https://mackysoft.net/blog](https://mackysoft.net/blog) # 📜 License This library is under the MIT License.