test/Assets/PerfectWorld/Scripts/PoolingManager/poolingManager.md

Pooling Manager Execution Flow

Purpose

The pooling system recycles Addressables-backed GameObject instances instead of repeatedly calling Instantiate and Destroy. Each Addressables key owns one runtime pool that tracks active objects, idle objects, and a memory-release timer.

Runtime Files

• IPoolable.cs: prefab-side lifecycle interface.
• ObjectPool.cs: owns instances and the loaded Addressables prefab handle for one key.
• PoolManager.cs: singleton service used by gameplay, server packet handlers, and UI code.

Spawn Flow

1. Call PoolManager.Instance.SpawnAsync(...) or PoolManager.Instance.Spawn(...).
2. PoolManager finds or creates an ObjectPool for the Addressables key.
3. The pool updates its memoryReleaseTTL from the spawn parameter.
4. If a memory release countdown is running, the pool cancels it.
5. The pool reuses an idle object when available.
6. If no idle object exists, the pool loads the prefab with Addressables.LoadAssetAsync<GameObject>() and instantiates it.
7. The instance is parented, positioned, rotated, activated, and all IPoolable.OnSpawn() hooks are called.
8. If autoDespawnTime > 0, PoolManager starts a version-checked auto despawn coroutine.
9. The spawned GameObject is returned to the caller.

Despawn Flow

1. Call PoolManager.Instance.Despawn(gameObject) or PoolManager.Instance.Despawn(addressableKey, gameObject).
2. The target pool validates that the object is currently active.
3. All IPoolable.OnDespawn() hooks are called.
4. The object is deactivated, parented under the pool root, and pushed into the idle stack.
5. When the active count reaches zero, the pool starts the memory release countdown.

Memory Release Flow

1. The countdown waits for the latest memoryReleaseTTL value supplied by spawn calls for that key.
2. A new spawn for the same key cancels the countdown and keeps the prefab handle in memory.
3. If the countdown completes while active count is still zero, the pool:
   • unregisters itself from PoolManager;
   • destroys all pooled instances;
   • releases the Addressables prefab handle with Addressables.Release();
   • destroys the pool root object.

Auto Despawn Safety

Auto despawn stores the instance spawn version when the coroutine starts. If the object is manually despawned and reused before the timer completes, the version changes and the old coroutine will not despawn the new lifecycle.

Example

GameObject fx = await PoolManager.Instance.SpawnAsync(
    "effects/fireball.prefab",
    hitPosition,
    Quaternion.identity,
    memoryReleaseTTL: 15f,
    autoDespawnTime: 2f);

For coroutine-based callers:

PoolManager.Instance.Spawn(
    "effects/fireball.prefab",
    hitPosition,
    Quaternion.identity,
    memoryReleaseTTL: 15f,
    autoDespawnTime: 2f,
    onComplete: spawned => { /* use spawned */ });