Skip to main content

Actor Pools

NexusActorPools
Module Name:
NexusActorPools / NActorPools
Initial Release:
0.1.0
Description:
Generalized pooling system for Actors.
BP Category:
NEXUS > Actor Pools
Area Owner:
@reapazor

This plugin is purpose-built for scenarios with high-frequency AActor reusage:

  • Combat Systems: Bullets, projectiles, explosions, damage numbers, etc.
  • Gameplay Objects: Collectible items, temporary platforms, interactive props
  • NPCs: Enemies, crowds

The pooling concept dramatically improves performance by eliminating the cost of spawning AActors and the associated garbage collection spikes, resulting in reduced hiccups and overhead associated with AActor usage. It is important to note that there are bespoke pooling systems included with different parts of the engine; these should be utilized when available.

Lifecycle​

It is essential to consider the lifecycle of any AActor used in an object pooling scenario. Specifically, are there things that need to happen to the Actor's components or itself to remove it from gameplay properly, be it deactivating components, sleeping AI, or altering GAS-related logic; every game is slightly different, and you will need to address your game's specific needs. Utilizing the INActorPoolItem interface, you can quickly carve out this pooling logic.

info

There is a NActorPools category added to the built-in stat system when N.ActorPools.TrackStats is toggled on. It is however not as robust in providing individual pool statistics as using the Developer Overlay method.

Spawning An Actor​

Can Be Nothing!

There are two causes where a FNActorPool will return a nullptr.

Strategy - There are specific Strategy that can be set on a FNActorPool which when the pool of AActors has been expended it will not create a new AActor, but instead return a nullptr.

Server-Only Pools - If a FNActorPool has been created with the APF_ServerOnly flag (on by default), and a client requests an AActor from that pool it will return a nullptr.

Returning An Actor​

Prewarm Pools​

The real advantage of pooling objects comes from when you have an opportunity to create an approximate number of objects you are going to need during a non-performance sensistive moment (think loading screen). There are a few options to being able to do this with FNActorPools.

Method Call​

Because the FNActorPools is not a UObject, there is no interaction with a given pool directly via Blueprint. It is strongly encouraged to use the provided UFUNCTION on UNActorPoolSubsystem to accomplish similar outcomes.

info

This is intentional and creates some unique preferred workflows in C++.

Spawn Actor
FNActorPool* Pool = UNActorPoolSubsystem::Get(GetWorld())->GetActorPool(MyActorClass);
if (Pool != nullptr)
{
  Pool->Prewarm(20);
}

Applying NActorPoolSets​

The UNActorPoolSet lets you create a data asset which houses the definitions of multiple pools for the UNActorPoolSubsystem to create when applied.

Samples​

NActorPools

The DEMO_NActorPools sample map is available once you have enabled the NEXUS Samples: Actor Pools plugin. This is found in the NEXUS Samples category in the Edit > Plugins window.

The map has a variety of demonstration content, showcasing the UNActorPoolSpawnerComponent and its various uses. The level blueprint also demonstrates how to apply an UNActorPoolSet to prewarm some FNActorPools.

warning

APS_DEMO_NActorPools_Sphere purposely has a circular reference in its definition of Nested Sets. Do NOT do this! Our automated testing uses this to ensure that we protect against that infinite loop.