Poolwright

Overview

Poolwright is a runtime plugin that pre-allocates and recycles AActor and UObject instances so hot paths — projectiles, tracers, impact FX, pickups, short-lived AI — stop paying spawn cost and stop feeding the garbage collector. A single subsystem owns every pool for the life of the game instance, exposing the same operations to Blueprint and C++ with no per-spawn allocation once a pool has warmed up.

Key Features

• One UGameInstanceSubsystem registry for actor and object pools, reachable from anywhere and surviving level transitions
• Full Blueprint/C++ parity — acquire nodes return the caller’s actor class directly, no casting required
• Opt-in auto-sizing: batch growth on misses and idle-triggered shrink-to-grace-count trimming, off by default so a plain pool behaves like a simple free list
• IPoolable reset contract (OnPooled / OnUnpooled) standing in for the BeginPlay/EndPlay cycle a reused instance never gets again
• Server-authoritative networked pooling via UPooledLifecycleComponent, with dormancy-aware wake/park so idle pooled actors cost nothing on the wire
• Single code path across Unreal Engine 4.26–5.8, with every version divergence isolated behind one macro header

Technical Decisions

Pools live on a UGameInstanceSubsystem rather than a hand-rolled singleton or per-world subsystem, since pooled instances must outlive level streaming. Deferred actor spawn uses SpawnActor with bDeferConstruction plus FinishSpawningActor instead of SpawnActorDeferred, because the latter’s parameter list changed shape across the UE4→UE5 range and the two-call form stays stable on every supported version; the same discipline — never placing a reflection macro behind an engine-version #if — keeps the whole 4.26–5.8 span on one code path.