ObjectPoolingSubsystem - API Reference

Complete API documentation for all classes, functions, and properties.

UObjectPooling_Subsystem {#uobjectpooling_subsystem}

Overview

Location: Core/ObjectPooling_Subsystem.h

Base Class: UWorldSubsystem

Purpose: Main manager for all object pools in a specific world

Availability: Blueprint-callable functions, C++ accessible

Functions

SpawnActorPoolListBySoftClass

C++ Signature:

void SpawnActorPoolListBySoftClass(
    TSoftClassPtr<AObjectPoolingEntry> ClassToSpawn,
    int32 SpawnAmount,
    int32 MaxSpawnAmount,
    bool bExpandable,
    float SpawnTimerRate = 0.02f
);

Blueprint Signature:

Spawn Actors Pool List By Class
├─ Element Class: AObjectPoolingEntry class reference (REQUIRED)
├─ Spawn Amount: Integer (REQUIRED)
├─ Max Spawn Amount: Integer (REQUIRED)
├─ Expand On Empty: Boolean (REQUIRED)
└─ Spawn Timer Rate: Float (Optional, default 0.02)

Parameters:

Name	Type	Required	Default	Description
ClassToSpawn	TSoftClassPtr	✓	N/A	Actor class to pool
SpawnAmount	int32	✓	N/A	Initial actors to create
MaxSpawnAmount	int32	✓	N/A	Maximum pool size
bExpandable	bool	✓	N/A	Allow pool to grow?
SpawnTimerRate	float	✗	0.02	Seconds between spawn batches

Return Value: void

Usage Examples:

C++:

void AMyGameMode::BeginPlay()
{
    Super::BeginPlay();
    
    UObjectPooling_Subsystem* Pool = GetWorld()->GetSubsystem<UObjectPooling_Subsystem>();
    
    // Create projectile pool
    Pool->SpawnActorPoolListBySoftClass(
        TSoftClassPtr<AObjectPoolingEntry>(AProjectile::StaticClass()),
        100,    // Initial: 100
        300,    // Max: 300
        true,   // Expandable: Yes
        0.02f   // Batch rate: 50 per second
    );
}

Blueprint:

Event BeginPlay
│
└─ Spawn Actors Pool List By Class
   ├─ Element Class: BP_Projectile
   ├─ Spawn Amount: 100
   ├─ Max Spawn Amount: 300
   ├─ Expand On Empty: True
   └─ Spawn Timer Rate: 0.02

Notes:

Creates pool asynchronously (batched over frames)
Safe to call multiple times for same class (updates config)
SpawnTimerRate of 0.02 = 50 batches/second, ~40-50 actors per batch typical
Use lower rate (0.05) for smoother but slower setup

SpawnActorFromActorListBySoftClass

C++ Signature:

AObjectPoolingEntry* SpawnActorFromActorListBySoftClass(
    TSoftClassPtr<AObjectPoolingEntry> ClassToSpawn,
    const FTransform& SpawnTransform,
    AActor* Owner = nullptr,
    bool bReturnAfterLifetime = false,
    float Lifetime = 0.0f
);

Blueprint Signature:

Spawn Actor From Pool
├─ Actor Class: AObjectPoolingEntry class reference (REQUIRED)
├─ Spawn Transform: Transform Struct (REQUIRED)
├─ Owner: Actor (Optional)
├─ Return After Lifetime: Boolean (Optional, default False)
├─ Lifetime: Float (Optional, default 0.0)
└─ Return: AObjectPoolingEntry (output)

Parameters:

Name	Type	Required	Default	Description
ClassToSpawn	TSoftClassPtr	✓	N/A	Which pool class
SpawnTransform	FTransform	✓	N/A	Position/rotation
Owner	AActor*	✗	nullptr	Actor that owns this
bReturnAfterLifetime	bool	✗	false	Auto-return?
Lifetime	float	✗	0.0f	Seconds before return

Return Value: AObjectPoolingEntry* (nullptr if pool exhausted)

Usage Examples:

C++:

void AWeapon::Fire()
{
    UObjectPooling_Subsystem* Pool = GetWorld()->GetSubsystem<UObjectPooling_Subsystem>();
    
    FVector Start = GetActorLocation();
    FVector Dir = GetActorForwardVector();
    FTransform Transform(Dir.Rotation(), Start);
    
    AObjectPoolingEntry* Entry = Pool->SpawnActorFromActorListBySoftClass(
        TSoftClassPtr<AObjectPoolingEntry>(AProjectile::StaticClass()),
        Transform,
        this,           // Owner: this weapon
        false,          // Manual despawn
        0.0f            // No auto-return
    );
    
    if (AProjectile* Proj = Cast<AProjectile>(Entry))
    {
        Proj->Launch(Dir * 2000.0f);
    }
}

Blueprint:

Event Input Fire
│
├─ Get Actor Location (self)
│
├─ Spawn Actor From Pool
│  ├─ Actor Class: BP_Projectile
│  ├─ Spawn Transform: [Based on location]
│  ├─ Owner: Self
│  ├─ Return After Lifetime: False
│  └─ Out Actor
│
├─ Is Valid (Out Actor)
│  ├─ True: Use actor
│  └─ False: Pool exhausted (rare)

Notes:

Returns nullptr if pool doesn't exist (create it first!)
Returns nullptr if pool exhausted AND not expandable
Both auto-return (Lifetime > 0) and manual (Lifetime = 0) supported
Call DespawnActor manually if auto-return disabled
For effects: Use auto-return with lifetime
For interactive objects: Use manual return

DestroyActorListBySoftClass

C++ Signature:

void DestroyActorListBySoftClass(
    TSoftClassPtr<AObjectPoolingEntry> ClassToDestroy,
    AActor* ActorToDestroy
);

Blueprint Signature:

Despawn Actor
├─ Actor Class: AObjectPoolingEntry class reference (REQUIRED)
└─ Actor: Actor to despawn (REQUIRED)

Parameters:

Name	Type	Required	Description
ClassToDestroy	TSoftClassPtr	✓	Pool class type
ActorToDestroy	AActor*	✓	Actor to return

Return Value: void

Usage Examples:

C++:

void AEnemy::OnDeath()
{
    // Play death effects...
    PlayDeathEffect();
    
    // Return to pool
    UObjectPooling_Subsystem* Pool = GetWorld()->GetSubsystem<UObjectPooling_Subsystem>();
    Pool->DestroyActorListBySoftClass(
        TSoftClassPtr<AObjectPoolingEntry>(AEnemy::StaticClass()),
        this
    );
}

Blueprint:

Event On Death
│
├─ Play Death Effect
│
└─ Despawn Actor
   ├─ Actor Class: BP_Enemy
   └─ Actor: Self

Notes:

Hides actor from world
Disables collision and physics
Triggers OnDespawnActor event in actor
Queues for batch destruction (frame-rate friendly)
Actor ready for reuse immediately after call

FindFreeEntryOnContainer

C++ Signature:

AObjectPoolingEntry* FindFreeEntryOnContainer(
    const TArray<AObjectPoolingEntry*>& EntryArray
);

Availability: C++ only (internal use)

Parameters:

Name	Type	Description
EntryArray	const TArray<AObjectPoolingEntry*>&	Pool to search

Return Value: AObjectPoolingEntry* (nullptr if all in use)

Implementation:

for (AObjectPoolingEntry* Entry : EntryArray)
{
    if (Entry && Entry->IsFreeInPool())
    {
        return Entry;
    }
}
return nullptr;

GetObjectActorPoolContainer

C++ Signature:

AObjectPoolingPlaceholder* GetObjectActorPoolContainer();

Availability: C++ only (internal use)

Return Value: AObjectPoolingPlaceholder* (creates if doesn't exist)

Purpose: Gets or creates the scene actor that organizes pools

Properties

Name	Type	Default	Description
ActorPoolMap	TMap<TSoftClassPtr, FObjectPoolList>	Empty	All active pools
SpawnPoolQueue	TArray	Empty	Queued spawn tasks
DestroyingActorList	TArray<AActor*>	Empty	Queued despawn tasks
TH_SpawnTick	FTimerHandle	N/A	Spawn timer
TH_DestroyActorsTick	FTimerHandle	N/A	Destroy timer

AObjectPoolingEntry {#aobjectpoolingentry}

Overview

Location: GameFramework/Actor/ObjectPoolingEntry.h

Base Class: AActor

Purpose: Base class for all poolable actors

Flags:

Abstract: No (can create directly)
Blueprintable: Yes
Placeable: Yes (but typically spawned via pool)

Functions

OnInitializeInPool_Implementation

C++ Signature:

virtual void OnInitializeInPool_Implementation();

Blueprint Event:

Event On Initialize In Pool

Default Behavior: Empty (can override)

Called:

Pool creation time
Every return to pool

Purpose: Reset actor to default state

Example C++:

void AMyPooledActor::OnInitializeInPool_Implementation()
{
    Super::OnInitializeInPool_Implementation();
    
    CurrentHealth = MaxHealth;
    SetActorScale3D(FVector(1.0f, 1.0f, 1.0f));
    SetActorRotation(FRotator::ZeroRotator);
}

Example Blueprint:

Event On Initialize In Pool
│
├─ Set Health to Max Health
├─ Set Actor Scale to (1,1,1)
└─ [Other resets]

OnSpawnActor_Implementation

C++ Signature:

virtual void OnSpawnActor_Implementation(float Lifetime, bool bForceReturnToPool);

Blueprint Event:

Event On Spawn Actor
├─ Lifetime: Float input
└─ Force Return To Pool: Boolean input

Default Behavior: Empty (can override)

Called: When actor is activated from pool

Parameters:

Name	Type	Description
Lifetime	float	Auto-return duration (0 = no auto-return)
bForceReturnToPool	bool	Is auto-return enabled?

Purpose: Setup gameplay-specific logic

Example C++:

void AProjectile::OnSpawnActor_Implementation(float Lifetime, bool bForceReturnToPool)
{
    Super::OnSpawnActor_Implementation(Lifetime, bForceReturnToPool);
    
    SetActorHiddenInGame(false);
    GetCollisionComponent()->SetCollisionEnabled(ECC_WorldDynamic);
    PlaySpawnEffect();
}

Example Blueprint:

Event On Spawn Actor
│
├─ Set Actor Hidden In Game to False
├─ Set Collision Enabled
├─ Play Spawn Sound
└─ Start Movement

OnDespawnActor_Implementation

C++ Signature:

virtual void OnDespawnActor_Implementation();

Blueprint Event:

Event On Despawn Actor

Default Behavior: Empty (can override)

Called: Before actor is hidden/returned to pool

Purpose: Cleanup gameplay state

Example C++:

void AEnemy::OnDespawnActor_Implementation()
{
    Super::OnDespawnActor_Implementation();
    
    StopMovement();
    StopAnimations();
    StopAllAudioComponents();
}

Example Blueprint:

Event On Despawn Actor
│
├─ Stop All Movement
├─ Stop All Audio
└─ Stop Particle Effects

IsFreeInPool

C++ Signature:

UFUNCTION(BlueprintPure, Category = "Object Pooling")
bool IsFreeInPool() const;

Blueprint Function:

Is Free In Pool
└─ Return: Boolean

Return Value: true if in pool (free), false if in use

Usage Examples:

C++:

if (PooledActor && PooledActor->IsFreeInPool())
{
    UE_LOG(LogTemp, Warning, TEXT("Actor is in pool"));
}

Blueprint:

Is Free In Pool
├─ True: Actor in pool, available
└─ False: Actor active in game

DespawnActor

C++ Signature:

UFUNCTION(BlueprintCallable, Category = "Object Pooling")
void DespawnActor(AActor* Actor);

Blueprint Function:

Despawn Actor
└─ Actor: Actor reference (REQUIRED)

Parameters:

Name	Type	Description
Actor	AActor*	Actor to return to pool

Return Value: void

Usage Examples:

C++:

if (CurrentHealth <= 0.0f)
{
    DespawnActor(this);  // Return self to pool
}

Blueprint:

On Something Happens
│
└─ Despawn Actor
   └─ Actor: Self

Notes:

Safe to call on nullptr (no-op)
Triggers OnDespawnActor event
Hides actor internally
Queued for batch processing

Properties

Name	Type	Default	Description
bIsFreeInPool	bool	true	In pool?
TH_ReturnToPool	FTimerHandle	N/A	Auto-return timer

Events

Name	Signature	Description
OnInitializeInPool	N/A	Actor added to pool
OnSpawnActor	(float, bool)	Actor activated
OnDespawnActor	N/A	Actor returning

AObjectPoolingPlaceholder {#aobjectpoolingplaceholder}

Overview

Location: GameFramework/Actor/ObjectPoolingPlaceholder.h

Base Class: AActor

Purpose: Invisible container organizing pooled actors

Typically: Not spawned manually (created automatically by subsystem)

Properties

Name	Type	Description
SpriteComponent	UBillboardComponent*	Editor-only visual

Notes

Automatically created per-world
All pooled actors attached as children
Hidden in game (editor only)
Useful for organization in outliner

UObjectPooling {#uobjectpooling}

Overview

Location: GameFramework/Lib/ObjectPooling.h

Type: Blueprint Function Library

Purpose: Convenience wrappers for common operations

Functions

SpawnActorsPoolListByClass

C++ Signature:

UFUNCTION(BlueprintCallable, Category = "Object Pooling")
static AObjectPoolingEntry* SpawnActorsPoolListByClass(
    AObjectPoolingEntry* DefaultObject,
    int32 NumberToSpawn,
    int32 MaxSize,
    bool bExpandable,
    float SpawnRate
);

Blueprint:

Spawn Actors Pool List By Class
├─ Default Object: Object reference (used for type inference)
├─ Number To Spawn: Integer
├─ Max Size: Integer
├─ Expand: Boolean
└─ Spawn Rate: Float

SpawnActorFromActorListByClass

C++ Signature:

UFUNCTION(BlueprintCallable, Category = "Object Pooling")
static AObjectPoolingEntry* SpawnActorFromActorListByClass(
    AObjectPoolingEntry* DefaultObject,
    const FTransform& Transform,
    bool bReturnAfterLifetime = false,
    float Lifetime = 0.0f
);

Blueprint:

Spawn Actor From Actor List By Class
├─ Default Object: Object reference
├─ Transform: Transform struct
├─ Return After Lifetime: Boolean
└─ Lifetime: Float

DestroyActorListByClass

C++ Signature:

UFUNCTION(BlueprintCallable, Category = "Object Pooling")
static void DestroyActorListByClass(
    AObjectPoolingEntry* ActorToDestroy,
    AActor* ActorToRemove
);

Blueprint:

Destroy Actor List By Class
├─ Actor To Destroy: Actor reference
└─ Actor To Remove: Actor to despawn

GetObjectPoolingPlaceholder

C++ Signature:

UFUNCTION(BlueprintCallable, Category = "Object Pooling", Meta = (WorldContext = "WorldContext"))
static AObjectPoolingPlaceholder* GetObjectPoolingPlaceholder(UWorld* WorldContext);

Blueprint:

Get Object Pooling Placeholder
├─ World: World context
└─ Return: Actor reference

CleanupRedundantPlaceholders

C++ Signature:

UFUNCTION(BlueprintCallable, Category = "Object Pooling")
static void CleanupRedundantPlaceholders(AObjectPoolingPlaceholder* Placeholder);

Blueprint:

Cleanup Redundant Placeholders
└─ Placeholder: Placeholder to cleanup

Data Structures {#data-structures}

FObjectPoolList

struct FObjectPoolList
{
    UPROPERTY()
    TArray<AObjectPoolingEntry*> ActorArray;
    
    UPROPERTY()
    int32 CurrentPoolSize = 0;
    
    UPROPERTY()
    int32 MaxSize = 100;
    
    UPROPERTY()
    bool bExpandable = false;
};

Members:

Name	Type	Description
ActorArray	TArray<AObjectPoolingEntry*>	Pooled actors
CurrentPoolSize	int32	Number created
MaxSize	int32	Maximum allowed
bExpandable	bool	Auto-grow?

FPendingPoolTask

struct FPendingPoolTask
{
    UPROPERTY()
    TSoftClassPtr<AObjectPoolingEntry> ClassToPool;
    
    UPROPERTY()
    int32 Remaining = 0;
    
    UPROPERTY()
    int32 MaxSize = 100;
    
    UPROPERTY()
    bool bExpandable = false;
};

Members:

Name	Type	Description
ClassToPool	TSoftClassPtr	Actor class
Remaining	int32	Actors to spawn
MaxSize	int32	Pool maximum
bExpandable	bool	Auto-expand?

Enums {#enums}

(None currently defined in public API)

Quick Reference Tables

Function Categories

Pool Management:

SpawnActorPoolListBySoftClass - Create pool
SpawnActorFromActorListBySoftClass - Get actor
DestroyActorListBySoftClass - Return actor

Query:

IsFreeInPool - Check state
GetObjectActorPoolContainer - Get placeholder

Events:

OnInitializeInPool - Pool setup
OnSpawnActor - Activation
OnDespawnActor - Deactivation

Default Parameter Values

Function	Parameter	Default
SpawnActorPoolListBySoftClass	SpawnTimerRate	0.02
SpawnActorFromActorListBySoftClass	Owner	nullptr
SpawnActorFromActorListBySoftClass	bReturnAfterLifetime	false
SpawnActorFromActorListBySoftClass	Lifetime	0.0f

Return Types

Function	Returns	Null When
SpawnActorFromActorListBySoftClass	AObjectPoolingEntry*	Pool exhausted
FindFreeEntryOnContainer	AObjectPoolingEntry*	All in use
GetObjectActorPoolContainer	AObjectPoolingPlaceholder*	Never null

See Also:

HOW_TO_USE.md - Usage examples
HOW_IT_WORKS.md - Technical deep dive
BLUEPRINT_GUIDE_DETAILED.md - Blueprint guide

FilesExpand file tree

API_REFERENCE.md

Latest commit

History

API_REFERENCE.md

File metadata and controls

ObjectPoolingSubsystem - API Reference

UObjectPooling_Subsystem {#uobjectpooling_subsystem}

Overview

Functions

SpawnActorPoolListBySoftClass

SpawnActorFromActorListBySoftClass

DestroyActorListBySoftClass

FindFreeEntryOnContainer

GetObjectActorPoolContainer

Properties

AObjectPoolingEntry {#aobjectpoolingentry}

Overview

Functions

OnInitializeInPool_Implementation

OnSpawnActor_Implementation

OnDespawnActor_Implementation

IsFreeInPool

DespawnActor

Properties

Events

AObjectPoolingPlaceholder {#aobjectpoolingplaceholder}

Overview

Properties

Notes

UObjectPooling {#uobjectpooling}

Overview

Functions

SpawnActorsPoolListByClass

SpawnActorFromActorListByClass

DestroyActorListByClass

GetObjectPoolingPlaceholder

CleanupRedundantPlaceholders

Data Structures {#data-structures}

FObjectPoolList

FPendingPoolTask

Enums {#enums}

Quick Reference Tables

Function Categories

Default Parameter Values

Return Types