punkfuncgames/pool-module

PoolModule Reference

Package: com.punkfuncgames.pool | Define: PUNKFUNC_POOL Location: Packages/com.punkfuncgames.pool/Runtime/PunkFuncGames.Pool/ Namespace: PunkFuncGames.Pool

IPoolService

Get:

• T Get<T>(string poolId) — get typed component from pool (null if at max)
• GameObject Get(string poolId) — get GameObject from pool

Return:

• Return<T>(T obj) / Return(GameObject obj) — return to pool (O(1) via instance map, O(n) fallback, destroys foreign objects)
• Return(string poolId, GameObject obj) / Return<T>(string poolId, T obj) — O(1) return with known poolId
• UniTask ReturnAfterDelayAsync(string poolId, GameObject obj, float delay, ct) — delayed return (VFX/particles)
• ReturnAll(string poolId) — return all active objects in a pool

Pool Management:

• CreatePool(string poolId, GameObject prefab, int initialSize = 10, int maxSize = 100) — throws on null/empty args
• ClearPool(string poolId), ClearAll()
• UniTask PreloadAsync(string poolId, int count, ct) — async preload, yields every 10 instances

Diagnostics:

• PoolInfo GetPoolInfo(string poolId) — pool stats (counts, utilization)
• bool HasPool(string poolId) — existence check

IPoolable — Optional callback interface

Implement on any component attached to pooled prefabs:

• OnGetFromPool() — called when object is retrieved
• OnReturnToPool() — called when object is returned

PoolInfo (readonly struct)

• PoolId, PrefabName, TotalCount, ActiveCount, AvailableCount, MaxSize
• float Utilization (computed), bool IsExhausted (computed), bool IsValid (computed)

Events

| Event | Key Fields | |-------|------------| | PoolCreatedEvent | PoolId, PrefabName, InitialSize, MaxSize | | PoolClearedEvent | PoolId, DestroyedCount | | PoolExhaustedEvent | PoolId | | PoolWarningEvent | PoolId, Message (fires at 80% utilization) |

Implementation: PoolService

Dependencies: 4 MessagePipe publishers (constructor DI), optional PoolConfig

• Implements IPoolService, IAsyncStartable, IDisposable
• Creates [PoolService] root (DontDestroyOnLoad) with Pool_{prefabName} children
• Internal Pool class: Queue<GameObject> (available) + HashSet<GameObject> (in-use)
• Dictionary<GameObject, string> for O(1) instance-to-pool mapping
• StartAsync processes PoolConfig entries, optionally preloading
• Max size enforcement: returns null + publishes PoolExhaustedEvent
• Utilization warning at 80% threshold via PoolWarningEvent
• Argument validation: ArgumentException/ArgumentNullException on null prefab/empty poolId

Configuration: PoolConfig (Config + Data Pattern)

PoolConfig (ScriptableObject): Thin wrapper with public PoolConfigData data; Access fields via _config.data.pools.

PoolConfigData ([Serializable] public struct):

• List<PoolEntryData> pools

PoolEntryData ([Serializable] public struct, camelCase fields): poolId, prefab, initialSize (10), maxSize (50), preloadOnStart

Extension method: IsValid() on PoolEntryData — validates non-empty poolId, non-null prefab, valid sizes

Installer

PoolInstaller.Install(builder, options, config);
// Registers: PoolService as EntryPoint with .As<IPoolService>()
// Registers: 4 event brokers (Created, Cleared, Exhausted, Warning)

Note: Installed in ProjectLifetimeScope.RegisterModules() with optional _poolConfig serialized field.

Usage Pattern

// Create pool at startup (or via PoolConfig ScriptableObject)
_poolService.CreatePool("Bullet", bulletPrefab, initialSize: 20, maxSize: 100);

// Async preload
await _poolService.PreloadAsync("Bullet", 50, ct);

// Spawn
GameObject bullet = _poolService.Get("Bullet");
bullet.transform.position = spawnPoint;

// Or get typed component
BulletComponent bulletComp = _poolService.Get<BulletComponent>("Bullet");

// Return to pool (O(1) auto-tracked)
_poolService.Return(bullet);

// Return with known poolId (fastest)
_poolService.Return("Bullet", bullet);

// Delayed return for VFX
await _poolService.ReturnAfterDelayAsync("Bullet", bullet, 2f, ct);

// Return all active bullets
_poolService.ReturnAll("Bullet");

// Query diagnostics
PoolInfo info = _poolService.GetPoolInfo("Bullet");
Debug.Log($"Utilization: {info.Utilization:P0}");

// Implement IPoolable for lifecycle hooks
public sealed class BulletComponent : MonoBehaviour, IPoolable
{
    public void OnGetFromPool() => _trail.Clear();
    public void OnReturnToPool() => _rigidbody.velocity = Vector3.zero;
}

// Subscribe to pool events
_poolExhaustedSubscriber.Subscribe(e =>
    Debug.LogWarning($"Pool {e.PoolId} exhausted!")).AddTo(_disposables);