Lean Pool
DOCUMENTATION
What is Lean Pool?
Lean Pool is a lightweight pooling asset, allowing you to easily cache and recycle prefab instances.
Pooling improves spawning performance, despawning performance, and reduces gc alloc.
Lean Pool also works with normal C# classes too.
How do I use it?
Find your code that heavily relies on:
Instantiate( ... );
And replace it with:
Lean.Pool.LeanPool.Spawn( ... );
Next, find your code that heavily relies on:
Destroy( ... );
And replace it with:
Lean.Pool.LeanPool.Despawn( ... );
For example:
var enemy = Lean.Pool.LeanPool.Spawn(enemyPrefab);
...
Lean.Pool.LeanPool.Despawn(enemy);
That's it, you've now implemented Lean Pool!
Why do I have to type Lean.Pool. before everything?
To improve organization, all Lean Pool classes are inside the Lean.Pool namespace.
If you don't like typing Lean.Pool. each time, then you can add the following code to the top of your script:
using Lean.Pool;
You can now just call LeanPool.Spawn(...) etc.
How do I alter the settings?
If you use the steps above then Lean Pool will automatically create pools when you first call LeanPool.Spawn, so to adjust the settings ahead of time you need to manually create the pool.
To do this, right click in your Hierarchy window, and select Lean / Pool. You should now see a GameObject in your scene called LeanGameObjectPool, and it should be automatically selected.
Next, drag and drop your prefab into the Prefab slot, and this will associate this pool with this prefab. You can now adjust the pool settings like the Preload, Capacity, etc.
My Rigidbody velocity isn't being reset!?
By default, Lean Pool doesn't modify any components when spawning or despawning.
This works fine for most components, but some components maintain their state even when deactivated, which requires you to manually reset their state.
The Rigidbody and Rigidbody2D components are two examples that don't reset their own state. When these components are despawned/deactivated they will retain their velocity, and when spawned again they will shoot off with their old velocity.
To fix this, the velocity must reset when despawned. This can be done by adding the LeanPooledRigidbody or LeanPooledRigidbody2D component that comes with Lean Pool.
How do I write custom spawning/despawning code?
There are several ways to do this, each with their pros and cons.
OnEnable and OnDisable messages
LeanPool will activate and deactivate your prefab clones when pooled.
When a component is deactivated, Unity sends it the OnDisable message, and when activated it sends the OnEnable message.
This means you can make a new component that implements OnEnable and/or OnDisable, and attach this component to your prefab.
OnSpawn and OnDespawn messages
If you use the LeanGameObjectPool.Notification = Send Message setting, then LeanPool will call the OnSpawn and OnDespawn methods on any components attached to your prefab clone.
This means you can make a new component that implements OnSpawn and/or OnDespawn, and attach this component to your prefab.
The main downside to this approach is that it may have performance overhead, it may interfere with any code that already uses OnSpawn or OnDespawn for something else, and you may make a typo, causing the methods to not get called.
If you need to reset the state of a child GameObjct, then you can use the LeanGameObjectPool.Notification = Broadcast Message setting instead.
IPoolable interface
If you use the LeanGameObjectPool.Notification = IPoolable setting, then LeanPool will call the OnSpawn and OnDespawn methods on any components attached to your prefab clone that implement the Lean.Pool.IPoolable interface.
This is the recommended approach, because it makes the intent of your code clearer. However, if you can use OnEnable and OnDisable instead, then that may give you slightly better performance.
If you need to reset the state of a child GameObjct, then you can use the LeanGameObjectPool.Notification = Broadcast IPoolable setting instead.
How do I increase the performance even more?
You may notice that the Lean.Pool.LeanPool.Spawn and Lean.Pool.LeanPool.Despawn methods work like magic.
This is because they're static methods that search a dictionary to find the pool associated with the prefab clone before performing the actual spawn or despawn code.
This is generally very fast, but if you need to super optimize your game then you may want to access the Lean.Pool.LeanGameObjectPool component itself. If you store a reference to it, then you can call the Spawn and Despawn methods directly.
Why do I get warnings in the console?
This is probably because you did something wrong.
For example, you may have replaced all your Instantiate calls with Spawn calls, but maybe you forgot to replace all your Destroy calls with Despawn calls.
There are many scenarios like this where you can forget what code is instantiating or destroying what, and it causes Lean Pool to throw a warning when it detects soemthing wrong.
However, Lean Pool will (hopefully) not break if you make mistakes like this, becuase I included many safety checks at every step.
If you're having issues tracking down the cause of a warning, then you can add the LeanPoolDebugger component to your prefab. This component actively tracks the current prefab clone, and will tell you exactly when you incorrectly spawn or destroy it.
Assets
Here's a list of all my other assets, please check them out!
You can also view this list on my Asset Store page.
Lean Touch
Rapidly develop your game with consistent input across desktop & mobile using Lean Touch. This lightweight asset comes with many modular components, allowing you to customize them to your exact project needs!
Lean Touch+
Lean Touch+ is an extension to the popular Lean Touch asset, adding many more example scenes.
Lean Localization
Lean Localization is a localization library that's designed to be as simple to use as possible for both designers, and programmers.
Lean Pool
Quickly optimize the performance of your games using Lean Pool. Within minutes you can use this lightweight asset to preload, recycle, and limit the spawning of your prefabs.
Lean Transition
Quickly polish your games using Lean Transition. This asset allows you to easily tween or animate almost anything in your game, making it transition smoothly.
Lean GUI
Lean GUI is a colllection of components that extend Unity's GUI system, allowing you to rapidly enhance the user experience (UX) of your game's UI.
Lean GUI Shapes
Lean GUI Shapes allows you to quickly add lines, rounded boxes, polygons, and much more to your GUI!
Lean Texture
Lean Texture allows you quickly modify textures in your project with a range of filters, pack them together into channels, and much more!
Lean Texture+
Lean Texture+ is an extension to Lean Texture, adding many new types of texture modification tools!
Modular Backgrounds
Unlock a universe of visual possibilities with Modular Backgrounds. Simply drag and drop these graphics into the background of your scenes.
Paint in 3D
Paint all your objects using Paint in 3D - both in game, and in editor. All features are optimized with GPU accelerated texture painting, so you can enjoy consistent performance, even if you paint your objects one million times!
Paint in 2D
Paint all your sprites with Paint in 2D. With incredible performance on mobile, WebGL, and much more!
Paint in Editor
Paint in Editor unlocks the ability to paint objects in your scene - great for making small tweaks, or even creating entirely new texture sets!
FLOW
FLOW allows you to add large scale interactive fluids to your scene - all highly optimized using GPU acceleration.
Destructible 2D
Unlock the full potential of your 2D games using Destructible 2D, this asset allows you to quickly convert all your boring solid sprites into fully destructible ones!
Space Graphics Toolkit
Quickly make the space scene of your dreams using Space Graphics Toolkit. This huge collection of space effects can be customized and combined in any way you like, allowing you to quickly make realistic or fantasy worlds. Each feature has been heavily optimized to run on almost any device and platform.
Space Graphics Planets
Enhance your space scenes using this large pack of high detail volumetric planets. These planets are finished using the powerful planet features from Space Graphics Toolkit (not required).
Volumetric Audio
Unity sounds only emanate from a single point source. This is great for explosions and footsteps, but quite often you need something more advanced. Volumetric Audio is an easy to use package that allows you to define boxes, spheres, capsules, paths, or meshes that sounds can emanate from.
Versions
2.0.1
Moved main build to Unity 2020.3.0f1.
Fixed LeanPoolDebugger component requiring a Rigidbody.
Fixed LeanGameObjectPool.DespawnAll method not removing LeanPool.Links.
2.0.0
Changed folder structure to be inside Plugins/CW/LeanPool.
Updated inspector code to support third party assets that implement nested inspectors.
1.4.0
Moved main build to Unity 2019.4.12f1.
Made LeanGameObjectPool auto detach clones when being destroyed (e.g. changing scenes).
1.2.9
Added LeanPool.Detach methods.
Added LeanGameObjectPool.Detach method.
Fixed inspector error after manually deleting spawned prefab.
Improved spawn consistency compared to Instantiate.
1.2.7
In-editor preloaded prefabs now retain their prefab link.
Added inspector warning to LeanGameObjectPool when preloaded objects differ from the prefab.
1.2.5
Added warning when multiple pools manage the same prefab.
Fixed prefab spawning when using multiple scenes.
1.2.3
Initial prefab spawns now begin with their final positions in Awake/OnEnable.
Updated common library code.
1.2.2
Fixed spawn transform being incorrect in some scenarios.
Fixed inspector expand buttons in UI Elements.
Components
IPoolable
If you implement this interface in a component on your pooled prefab, then the OnSpawn and OnDespawn methods will be automatically called when the associated LeanGameObjectPool.Notification = PoolableInterface.
LeanClassPool<T>
This class allows you to pool normal C# classes, for example:
var foo = Lean.Pool.LeanClassPool
Lean.Pool.LeanClassPool
static T
Spawn
System.Action<T> onSpawn
This will either return a pooled class instance, or null. If an instance it found, onSpawn will be called with it. NOTE: onSpawn is expected to not be null.
static T
Spawn
System.Predicate<T> match
This will either return a pooled class instance, or null.
All pooled classes will be checked with match to see if they qualify.
static T
Spawn
System.Predicate<T> match, System.Action<T> onSpawn
This will either return a pooled class instance, or null.
All pooled classes will be checked with match to see if they qualify.
If an instance it found, onSpawn will be called with it.
static void
Despawn
T instance
This will pool the passed class instance.
static void
Despawn
T instance, System.Action<T> onDespawn
This will pool the passed class instance.
If you need to perform despawning code then you can do that via onDespawn.
LeanGameObjectPool
This component allows you to pool GameObjects, giving you a very fast alternative to Instantiate and Destroy.
Pools also have settings to preload, recycle, and set the spawn capacity, giving you lots of control over your spawning.
static LinkedList<LeanGameObjectPool>
Instances
All active and enabled pools in the scene.
GameObject
Prefab
The prefab this pool controls.
NotificationType
Notification
If you need to perform a special action when a prefab is spawned or despawned, then this allows you to control how that action is performed.
StrategyType
Strategy
This allows you to control how spawned/despawned GameObjects will be handled. The DeactivateViaHierarchy mode should be used if you need to maintain your prefab's de/activation state.
ActivateAndDeactivate = Despawned clones will be deactivated and placed under this GameObject.
DeactivateViaHierarchy = Despawned clones will be placed under a deactivated GameObject and left alone.
int
Preload
Should this pool preload some clones?
int
Capacity
Should this pool have a maximum amount of spawnable clones?
bool
Recycle
If the pool reaches capacity, should new spawns force older ones to despawn?
bool
Persist
Should this pool be marked as DontDestroyOnLoad?
bool
Stamp
Should the spawned clones have their clone index appended to their name?
bool
Warnings
Should detected issues be output to the console?
Transform
DeactivatedChild
If you're using the Strategy = DeactivateViaHierarchy mode, then all despawned clones will be placed under this.
bool
DespawnedClonesMatch
This will return false if you have preloaded prefabs do not match the Prefab.
int
Spawned
Returns the amount of spawned clones.
int
Despawned
Returns the amount of despawned clones.
int
Total
Returns the total amount of spawned and despawned clones.
static bool
TryFindPoolByPrefab
GameObject prefab, ref LeanGameObjectPool foundPool
Find the pool responsible for handling the specified prefab.
static bool
TryFindPoolByClone
GameObject clone, ref LeanGameObjectPool pool
Find the pool responsible for handling the specified prefab clone.
void
Spawn
This will either spawn a previously despawned/preloaded clone, recycle one, create a new one, or return null.
void
Spawn
Vector3 position
This will either spawn a previously despawned/preloaded clone, recycle one, create a new one, or return null.
GameObject
Spawn
Transform parent, bool worldPositionStays = false
This will either spawn a previously despawned/preloaded clone, recycle one, create a new one, or return null.
GameObject
Spawn
Vector3 position, Quaternion rotation, Transform parent = null
This will either spawn a previously despawned/preloaded clone, recycle one, create a new one, or return null.
bool
TrySpawn
ref GameObject clone, Transform parent, bool worldPositionStays = false
This will either spawn a previously despawned/preloaded clone, recycle one, create a new one, or return null.
bool
TrySpawn
ref GameObject clone, Vector3 position, Quaternion rotation, Transform parent = null
This will either spawn a previously despawned/preloaded clone, recycle one, create a new one, or return null.
bool
TrySpawn
ref GameObject clone
This will either spawn a previously despawned/preloaded clone, recycle one, create a new one, or return null.
bool
TrySpawn
ref GameObject clone, Vector3 localPosition, Quaternion localRotation, Vector3 localScale, Transform parent, bool worldPositionStays
This will either spawn a previously despawned/preloaded clone, recycle one, create a new one, or return null.
void
DespawnOldest
This will despawn the oldest prefab clone that is still spawned.
void
DespawnAll
bool cleanLinks
This method will despawn all currently spawned prefabs managed by this pool.
void
Despawn
GameObject clone, float t = 0.0f
This will either instantly despawn the specified gameObject, or delay despawn it after t seconds.
void
Detach
GameObject clone, bool cleanLinks = true
This allows you to remove all references to the specified clone from this pool.
A detached clone will act as a normal GameObject, requiring you to manually destroy or otherwise manage it.
void
PreloadOneMore
This method will create an additional prefab clone and add it to the despawned list.
void
PreloadAll
This will preload the pool based on the Preload setting.
void
Clean
This will destroy all preloaded or despawned clones. This is useful if you've despawned more prefabs than you likely need, and want to free up some memory.
void
GetClones
List<GameObject> gameObjects, bool addSpawnedClones = true, bool addDespawnedClones = true
This method will clear and fill the specified list with the specified clones from this pool.
LeanPool
This class handles the association between a spawned prefab, and the LeanGameObjectPool component that manages it.
static Dictionary<GameObject, LeanGameObjectPool>
Links
When you spawn a prefab from this class, the association between the spawned clone and the pool that spawned it will be stored here so it can quickly be despawned.
static T
Spawn<T>
T prefab, Transform parent, bool worldPositionStays = false
This allows you to spawn a prefab via Component.
static T
Spawn<T>
T prefab, Vector3 position, Quaternion rotation, Transform parent = null
This allows you to spawn a prefab via Component.
static T
Spawn<T>
T prefab
This allows you to spawn a prefab via Component.
static GameObject
Spawn
GameObject prefab, Transform parent, bool worldPositionStays = false
This allows you to spawn a prefab via GameObject.
static GameObject
Spawn
GameObject prefab, Vector3 position, Quaternion rotation, Transform parent = null
This allows you to spawn a prefab via GameObject.
static GameObject
Spawn
GameObject prefab
This allows you to spawn a prefab via GameObject.
static void
DespawnAll
This will call DespawnAll on all active and enabled pools.
static void
Despawn
Component clone, float delay = 0.0f
This allows you to despawn a clone via Component, with optional delay.
static void
Despawn
GameObject clone, float delay = 0.0f
This allows you to despawn a clone via GameObject, with optional delay.
static void
Detach
Component clone, bool detachFromPool = true
This allows you to detach a clone via Component.
A detached clone will act as a normal GameObject, requiring you to manually destroy or otherwise manage it.
static void
Detach
GameObject clone, bool detachFromPool
This allows you to detach a clone via GameObject.
A detached clone will act as a normal GameObject, requiring you to manually destroy or otherwise manage it.
LeanPoolDebugger
This component can be added to your prefab GameObject, and it will throw warnings if it is instantiated without the use of LeanPool.Spawn, or despawned without the use of LeanPool.Despawn.