Quickstart

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.

Spawning An Actor

Blueprint

C++

Spawn Actor

AMyActorType* SpawnedActor = UNActorPoolSubsystem::Get(GetWorld())->SpawnActor<AMyActorType>(MyActorClass, MyPosition, MyRotation);

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.

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.

Returning An Actor

Blueprint

C++

Ambiguous Return

UNActorPoolSubsystem::Get(GetWorld())->ReturnActor(TargetActor);

While the Blueprint logic is the most generic, one of the benefits of utilizing the INActorPoolItem interfaces is that there are baked-in fast paths.

INActorPoolItem-Based Return

TargetActor->ReturnToActorPool();