# F8 Features Gameobjectpool Workflow

> F8 Features Gameobjectpool Workflow is an Agent Skill for development published in the TippingGame/F8Framework repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when implementing or troubleshooting GameObjectPool feature workflows — object pooling, preloading, spawn/despawn, and lifecycle events in F8Framework.

- Skill name: `f8-features-gameobjectpool-workflow`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/TippingGame/F8Framework/blob/HEAD/Tests/AISkills/f8framework-skills/features/f8-features-gameobjectpool-workflow/SKILL.md
- Repository: TippingGame/F8Framework (866 GitHub stars when collected)

## SKILL.md

# 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

| Class | Role |
|-------|------|
| `GameObjectPoolManager` | Core module. Access via `FF8.GameObjectPool`. |
| `F8GameObjectPool` | Individual pool instance with capacity, callbacks, and settings. |
| `PoolsPreset` | ScriptableObject for pre-configured pool definitions. |
| `IPoolable` | Interface for spawn/despawn callbacks on pooled objects. |
| `PoolableStatus` | Enum: Spawned / Despawned / SpawnedOverCapacity. |

## API quick reference

### Spawn and despawn
```csharp
// 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
```csharp
// 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
```csharp
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
```csharp
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
```csharp
pool.GameObjectInstantiated.AddListener(OnInstantiated);
pool.GameObjectSpawned.AddListener(OnSpawned);
pool.GameObjectDespawned.AddListener(OnDespawned);
```

### IPoolable interface
```csharp
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

| Error | Cause | Solution |
|-------|-------|----------|
| Pool exhausted | All clones in use, no recycle policy | Set `BehaviourOnCapacityReached.Recycle` or increase capacity |
| Destroy/Despawn mismatch | Using `Destroy()` on pooled object | Always use `Despawn()` or `DestroyClone()` |
| OnSpawn not called | IPoolable not implemented or wrong CallbacksType | Implement `IPoolable` and set `CallbacksType.Interfaces` |

## 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.

---

Source: https://www.openparable.com/skill/development/f8-features-gameobjectpool-workflow (OpenParable). Cite the canonical URL above.
