Actor Pooling

Combat systems often need to spawn short-lived actors, such as projectiles, cast actors, targeting actors, and marker actors. Creating and destroying these actors repeatedly during combat can become expensive, especially when many combatants are active at the same time.

The Actor Pool reduces that cost by preparing reusable actor instances ahead of time. Instead of spawning a new actor every time one is needed, the Combat System can retrieve an inactive actor from the pool, activate it, and return it to the pool when it is no longer needed.

Actor Pooling is optional, but it is recommended for actors that are spawned frequently during combat.

Actor Pool Component

Each combatant can have its own Actor Pool, represented by the NinjaCombatActorPoolComponent. The component defines which actor classes are pooled and how many instances of each class should be initialized.

Combatants using an Actor Pool should also implement CombatPoolProviderInterface. This allows other systems, such as projectile requests, cast abilities, and targeting logic, to retrieve the pool without depending on a specific character class.

Add the Actor Pool Component

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Character.h"
#include "Interfaces/CombatPoolProviderInterface.h"
#include "PluginLabsCharacter.generated.h"

class UNinjaCombatActorPoolComponent;

UCLASS()
class PLUGINLABS_API APluginLabsCharacter : public ACharacter, public ICombatPoolProviderInterface
{

	GENERATED_BODY()

public:

	APluginLabsCharacter(const FObjectInitializer& ObjectInitializer = FObjectInitializer::Get());

	// -- Begin Pool Provider interface.
	virtual UNinjaCombatActorPoolComponent* GetActorPool_Implementation() const override;
	// -- End Pool Provider interface.


private:

	/** Pool of actors that are frequently used. */
	UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category = "Components", meta = (AllowPrivateAccess = true))
	TObjectPtr<UNinjaCombatActorPoolComponent> ActorPool;

};

#include "GameFramework/PluginLabsCharacter.h"
#include "Components/NinjaCombatActorPoolComponent.h"

APluginLabsCharacter::APluginLabsCharacter(const FObjectInitializer& ObjectInitializer) : Super(ObjectInitializer)
{
	static const FName ActorPoolName = TEXT("ActorPool");
	ActorPool = CreateDefaultSubobject<UNinjaCombatActorPoolComponent>(ActorPoolName);
}

UNinjaCombatActorPoolComponent* APluginLabsCharacter::GetActorPool_Implementation() const
{
	return ActorPool;
}

Add the Actor Pool component to your character.
Implement CombatPoolProviderInterface and return the Actor Pool component from the appropriate function.

Pool Configuration

The Actor Pool is configured directly in the Actor Pool Component. Each entry defines an actor class and the number of instances that should be initialized for that class.

Poolable Actors

Poolable actors are defined by CombatPoolableActorInterface. Any actor implementing this interface can be added to the Actor Pool Component.

For most cases, it is recommended to extend NinjaCombatPoolableActor instead of implementing the interface directly. This base class already implements the poolable actor contract and is configured to support networking and replication, so pooled actors can behave as if they were placed in the map.

The Actor Pool Component and NinjaCombatPoolableActor work together to reduce the initial network overhead that could otherwise happen when many replicated actors are spawned at the same time.

Actor Lifecycle

Poolable actors have a different lifecycle from regular spawned actors.

Functions such as Begin Play and End Play are called when the pooled actor is created or destroyed by the pool. They are not called every time the actor is retrieved from the pool or returned to it.

For per-use behavior, use the lifecycle functions provided by CombatPoolableActorInterface.

Function	Description
`Activate`	Called when a poolable actor is retrieved from the pool and placed in the world.
`Deactivate`	Called when a poolable actor is ready to return to the pool.

If you are using NinjaCombatPoolableActor, these functions are already implemented. You can use the extension points provided by the base class instead.

Extension Point	Description
`OnActivation`	Called when the actor is activated on the server and clients.
`OnDeactivation`	Called when the actor is deactivated on the server and clients.

These events are appropriate for behavior that should happen every time the actor is reused, such as:

Playing a particle effect from the start.
Playing a sound effect from the start.
Applying velocity to a projectile.
Resetting visual state or gameplay state from a previous activation.

Supported Actors

The following actor types are supported by the Actor Pool by default.

Actor Type	Description
Projectile Actors	Spawned by Ranged Attacks.
Cast Actors	Spawned by certain Cast Flows.
Targeting Actors	Spawned by abilities that use Targeting Actors, like the Cast Ability.
Marker Actors	Spawned by the Target Lock Ability

You can support additional actors by extending NinjaCombatPoolableActor, or by implementing CombatPoolableActorInterface directly.

Retrieving Actors

To retrieve an actor from the pool, use TryGetActorFromPool from the Actor Pool Function Library.

The actor types listed above already use this functionality internally, so no additional retrieval code is required when using the default Combat features.

#include "NinjaCombatActorPoolFunctionLibrary.h"

void APluginLabsCharacter::ActivateActor()
{
    AActor* PoolableActor = UNinjaCombatActorPoolFunctionLibrary::TryGetActorFromPool(RequestOwner, DesiredClass);
	if (IsValid(PoolableActor))
	{
		// The actor was spawned.
	}
	else
	{
		// The pool does not have an instance available.
	}
}

25 June 2026