f8-features-gameobjectpool-workflow

GameObjectPool Feature Workflow

⚠️ IMPORTANT: Before using this feature, you MUST formally initialize F8Framework in the launch sequence. Ensure ModuleCenter.Initialize(this); has run first, then create the required module, for example FF8.GameObjectPool = ModuleCenter.CreateModule<GameObjectPool>();.

Use this skill when

• The task is about GameObject pooling, preloading, and spawn/despawn.
• The user needs to manage pooled object lifecycle events.
• Troubleshooting pool exhaustion, capacity overflow, or despawn issues.

Path resolution

1. Prefer project source at Assets/F8Framework.
2. If F8Framework is installed as a package, use Packages/F8Framework.
3. For usage docs, read: Assets/F8Framework/Tests/GameObjectPool/README.md

Sources of truth

• Runtime module: Assets/F8Framework/Runtime/GameObjectPool
• Editor module: Assets/F8Framework/Editor/GameObjectPool
• Test docs: Assets/F8Framework/Tests/GameObjectPool

Key classes and interfaces

API quick reference

Spawn and despawn

// Spawn by name, prefab, or component
GameObject clone = FF8.GameObjectPool.Spawn("prefabName");
GameObject clone = FF8.GameObjectPool.Spawn(prefab);
MyComp comp = FF8.GameObjectPool.Spawn(compPrefab, Vector3.zero, Quaternion.identity, parent);

// Despawn (with optional delay)
FF8.GameObjectPool.Despawn(clone, delay: 0.5f);

// Particle auto-despawn on complete
FF8.GameObjectPool.Spawn(particlePrefab).DespawnOnComplete();

Pool management

// Install preset pools (from ScriptableObject)
FF8.GameObjectPool.InstallPools(poolsPreset);

// Get pool reference
F8GameObjectPool pool = FF8.GameObjectPool.GetPoolByPrefab(prefab);
F8GameObjectPool pool = FF8.GameObjectPool.GetPoolByPrefabName("PrefabName");

// Clone status
PoolableStatus status = FF8.GameObjectPool.GetCloneStatus(clone);
bool isClone = FF8.GameObjectPool.IsClone(clone);

// For each clone/pool
FF8.GameObjectPool.ForEachPool((pool) => { });
FF8.GameObjectPool.ForEachClone((clone) => { });

// Safe destroy (avoids pool errors)
FF8.GameObjectPool.DestroyClone(clone);
FF8.GameObjectPool.DestroyAllPools(immediately: false);

Pool configuration

pool.Init();                            // Init with cached prefab
pool.Init(prefab);
pool.PopulatePool(16);                  // Pre-instantiate
pool.SetCapacity(32);                    // Max capacity
pool.SetBehaviourOnCapacityReached(BehaviourOnCapacityReached.Recycle);
pool.SetDespawnType(DespawnType.DeactivateAndHide);
pool.SetCallbacksType(CallbacksType.Interfaces);
pool.SetWarningsActive(true);

Pool operations

pool.ForEachClone((obj) => { });
pool.ForEachSpawnedClone((obj) => { });
pool.ForEachDespawnedClone((obj) => { });
pool.DestroySpawnedClones();
pool.DestroyDespawnedClones();
pool.DestroyAllClones();
pool.DestroySpawnedClonesImmediate();
pool.DestroyDespawnedClonesImmediate();
pool.DestroyAllClonesImmediate();
pool.DespawnAllClones();
pool.DestroyPool();
pool.DestroyPoolImmediate();
pool.Clear();

Lifecycle events

pool.GameObjectInstantiated.AddListener(OnInstantiated);
pool.GameObjectSpawned.AddListener(OnSpawned);
pool.GameObjectDespawned.AddListener(OnDespawned);

IPoolable interface

public class MyPooledObject : MonoBehaviour, IPoolable
{
    public void OnSpawn() { /* Reset state */ }
    public void OnDespawn() { /* Cleanup */ }
}

Workflow

1. Create prefabs to pool or define PoolsPreset ScriptableObjects.
2. Optionally pre-populate pools with PopulatePool().
3. Spawn objects via FF8.GameObjectPool.Spawn().
4. Despawn to return objects to pool instead of Destroy.
5. Implement IPoolable on pooled objects for reset/cleanup callbacks.
6. Set capacity and overflow behavior for production use.
7. Use DespawnOnComplete() for particles.

Common error handling

Cross-module dependencies

• AssetManager: Pool prefabs can be loaded via AssetManager.

Output checklist

• Pool strategy defined (preload count, capacity, overflow behavior).
• Spawn/Despawn lifecycle verified.
• Files changed and why.
• Validation status and remaining risks.