com.amanotes.prefabpool 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [1.0.3] - 2026-04-07
+
+### Fixed
+- `PoolEntry.Return`: renamed pooled GameObjects back to their entry `id` in Editor for easier hierarchy debugging (`PrefabPool.cs`)
+
+## [1.0.2] - 2026-04-06
+
+### Fixed
+- `PoolEntry.Return`: deactivate GameObject before `SetParent` to prevent `Cannot set the parent of the GameObject while activating or deactivating the parent GameObject` error during scene shutdown
+- `PoolEntry.Get`: explicit `SetActive(true)` to match — objects are now consistently inactive in pool, active when in use
+- `PoolEntry.PreAllocate`: prewarm objects are now spawned inactive, consistent with the return state
+- `PrefabPool.DestroyPool`: `_customPool` (Resize<T>) entries are now properly destroyed on shutdown
+- `PrefabPool.Initialize`: added `_isInitializing` guard to prevent double-prewarm if called concurrently
+- `PoolEntry.PurgeDestroyed`: new method, called on `Register` to remove stale destroyed-object refs when a PoolGroup ScriptableObject is reused across scene loads
+- `PrefabPool.PurgeStaleInstanceMap`: cleans up `_instanceTypeMap` entries for externally-destroyed objects (Editor only)
+
+## [1.0.1]
+
+- Initial release

package/CHANGELOG.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 9d04aecc1aeab42d8b4f2c41cd72ccd5
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Docs/PrefabPool-API.md

@@ -0,0 +1,366 @@
+# PrefabPool API Reference
+
+**Package:** `com.amanotes.prefabpool` | **Version:** 1.0.1 | **Namespace:** `Amanotes.Core`
+
+Generic object pooling system to eliminate garbage collection spikes from frequent instantiation/destruction.
+
+---
+
+## Core Interfaces
+
+### `IPrefabPool`
+
+Main interface for object pool management.
+
+```csharp
+public interface IPrefabPool
+{
+    bool IsReady { get; }                    // Pool initialization status
+    
+    void RegisterGroup(PoolGroup group, Transform spawnParent);
+    void SetSpawnParent(string groupId, Transform spawnParent);
+    GameObject Get(PoolGroup group, string prefabId, Vector3 localPosition = default, Transform customParent = null);
+    void Return(PoolGroup group, GameObject gameObject);
+    IEnumerator Initialize();                // Pre-allocate pooled objects
+}
+```
+
+**Example:**
+```csharp
+// Setup pool
+var pool = gameObject.AddComponent<PrefabPool>();
+var group = new PoolGroup
+{
+    id = "enemies",
+    entries = new List<PoolEntry>
+    {
+        new PoolEntry { id = "basic", prefab = enemyPrefab, prewarmCount = 10 }
+    }
+};
+pool.RegisterGroup(group, transform);
+StartCoroutine(pool.Initialize());
+
+// Use pool
+var enemy = pool.Get(group, "basic");
+pool.Return(group, enemy);
+```
+
+---
+
+### `IPoolPrefab`
+
+Lifecycle callback interface for pooled objects.
+
+```csharp
+public interface IPoolPrefab
+{
+    void OnGet();      // Called when retrieved from pool
+    void OnReturn();   // Called when returned to pool
+}
+```
+
+**Implementation:**
+```csharp
+public class PooledTile : MonoBehaviour, IPoolPrefab
+{
+    public void OnGet()
+    {
+        gameObject.SetActive(true);
+        ResetState();
+    }
+    
+    public void OnReturn()
+    {
+        gameObject.SetActive(false);
+    }
+}
+```
+
+---
+
+## Core Classes
+
+### `PrefabPool`
+
+Main implementation of IPrefabPool.
+
+```csharp
+public class PrefabPool : MonoBehaviour, IPrefabPool
+{
+    public bool IsReady { get; }             // True after Initialize() completes
+    
+    public void RegisterGroup(PoolGroup group, Transform spawnParent);
+    public void SetSpawnParent(string groupId, Transform spawnParent);
+    public GameObject Get(PoolGroup group, string prefabId, Vector3 localPosition = default, Transform customParent = null);
+    public void Return(PoolGroup group, GameObject gameObject);
+    public IEnumerator Initialize();
+    public void Resize<T>(GameObject prefab, List<T> list, int count, Transform parent) where T : Component;
+    public void DestroyPool();
+}
+```
+
+**Example:**
+```csharp
+// Dynamic list resizing
+List<Enemy> enemies = new List<Enemy>();
+pool.Resize(enemyPrefab, enemies, 10, transform);
+// enemies.Count == 10
+```
+
+---
+
+### `PoolGroup`
+
+Organizes related pool entries.
+
+```csharp
+[Serializable]
+public class PoolGroup
+{
+    public string id;                        // Group identifier
+    public List<PoolEntry> entries;          // Pool entries in this group
+    public PoolEntry fallbackEntry;          // Used when prefabId not found
+    public Transform SpawnParent { get; }    // Spawn parent transform
+    
+    public GameObject Get(string prefabId, Vector3 localPosition = default, Transform customParent = null);
+    public T Get<T>(string prefabId, Vector3 localPosition = default) where T : class;
+    public void Return(GameObject gameObject);
+}
+```
+
+**Example:**
+```csharp
+// Get with component type
+var enemy = enemyGroup.Get<Enemy>("basic_enemy");
+var handler = tileGroup.Get<IInputHandler>("tile_short");
+
+// Fallback entry
+var group = new PoolGroup
+{
+    id = "tiles",
+    entries = new List<PoolEntry> { /* specific tiles */ },
+    fallbackEntry = new PoolEntry { id = "default", prefab = defaultPrefab, prewarmCount = 20 }
+};
+```
+
+---
+
+### `PoolEntry`
+
+Configuration for single pooled prefab.
+
+```csharp
+[Serializable]
+public class PoolEntry
+{
+    public string id;                        // Prefab identifier
+    public GameObject prefab;                // Prefab to pool
+    public int prewarmCount;                 // Pre-allocate count (0-10)
+    
+    public GameObject Get(Transform poolParent, Transform spawnParent, Vector3 localPosition);
+    public void Return(GameObject gameObject, Transform poolParent);
+    public void DestroyPool();
+    public IEnumerator PreAllocate(Transform poolParent);
+}
+```
+
+---
+
+## Material Pooling
+
+### `MaterialPool`
+
+Static utility for pooling material instances.
+
+```csharp
+public static class MaterialPool
+{
+    public static Material Take(Material sourceOrClone, int borrowId);
+    public static void Return(int borrowId);
+}
+```
+
+**Example:**
+```csharp
+// Borrow material
+Material mat = MaterialPool.Take(originalMaterial, GetInstanceID());
+renderer.material = mat;
+mat.SetAlpha(0.5f);
+
+// Return on destroy
+void OnDestroy()
+{
+    MaterialPool.Return(GetInstanceID());
+}
+```
+
+---
+
+### `MaterialExtensions`
+
+Extension methods for material operations.
+
+```csharp
+public static class MaterialExtensions
+{
+    public static void SetAlpha(this Material m, float a);  // Set alpha channel
+}
+```
+
+**Example:**
+```csharp
+material.SetAlpha(0.5f); // 50% transparent
+```
+
+---
+
+## Extension Methods
+
+### `PrefabPoolExtensions`
+
+Extension methods for list operations with pooling.
+
+```csharp
+public static class PrefabPoolExtensions
+{
+    public static void DestroyLast<T>(this List<T> list) where T : Component;
+    public static T ClonePrefab<T>(this GameObject prefab, Transform parent) where T : Component;
+    public static void ResetAndClear<T>(this List<T> list, GameObject prefab, PrefabPool pool = null) where T : Component;
+    public static void Resize<T>(this List<T> list, int count, GameObject prefab, Transform parent, PrefabPool pool) where T : Component;
+}
+```
+
+**Example:**
+```csharp
+// Resize list using pool
+List<Tile> tiles = new List<Tile>();
+tiles.Resize(10, tilePrefab, transform, pool);
+// tiles.Count == 10
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Basic Pool Setup
+
+```csharp
+// When to use: Standard object pooling
+var pool = gameObject.AddComponent<PrefabPool>();
+
+var enemyGroup = new PoolGroup
+{
+    id = "enemies",
+    entries = new List<PoolEntry>
+    {
+        new PoolEntry { id = "basic_enemy", prefab = enemyPrefab, prewarmCount = 10 }
+    }
+};
+
+pool.RegisterGroup(enemyGroup, transform);
+StartCoroutine(pool.Initialize());
+
+// Spawn
+var enemy = enemyGroup.Get<Enemy>("basic_enemy");
+
+// Despawn
+enemyGroup.Return(enemy.gameObject);
+```
+
+### Pattern 2: Pooled Component with Lifecycle
+
+```csharp
+// When to use: Custom initialization/cleanup logic
+public class PooledEnemy : MonoBehaviour, IPoolPrefab
+{
+    private Rigidbody rb;
+    
+    void Awake()
+    {
+        rb = GetComponent<Rigidbody>();
+    }
+    
+    public void OnGet()
+    {
+        gameObject.SetActive(true);
+        rb.velocity = Vector3.zero;
+    }
+    
+    public void OnReturn()
+    {
+        gameObject.SetActive(false);
+    }
+}
+```
+
+### Pattern 3: Dynamic List Resizing
+
+```csharp
+// When to use: Variable number of active objects
+List<Tile> activeTiles = new List<Tile>();
+
+void UpdateTileCount(int count)
+{
+    pool.Resize(tilePrefab, activeTiles, count, transform);
+    
+    for (int i = 0; i < activeTiles.Count; i++)
+    {
+        activeTiles[i].UpdatePosition(i);
+    }
+}
+```
+
+### Pattern 4: Material Pooling
+
+```csharp
+// When to use: Dynamic color/alpha changes without creating material instances
+public class ColoredTile : MonoBehaviour
+{
+    private Material instanceMaterial;
+    private int borrowId;
+    
+    void Start()
+    {
+        borrowId = GetInstanceID();
+        instanceMaterial = MaterialPool.Take(GetComponent<Renderer>().sharedMaterial, borrowId);
+        GetComponent<Renderer>().material = instanceMaterial;
+    }
+    
+    public void SetColor(Color color)
+    {
+        instanceMaterial.color = color;
+    }
+    
+    void OnDestroy()
+    {
+        MaterialPool.Return(borrowId);
+    }
+}
+```
+
+### Pattern 5: Fallback Entry
+
+```csharp
+// When to use: Default prefab when specific ID not found
+var group = new PoolGroup
+{
+    id = "tiles",
+    entries = new List<PoolEntry>
+    {
+        new PoolEntry { id = "special", prefab = specialPrefab, prewarmCount = 5 }
+    },
+    fallbackEntry = new PoolEntry { id = "default", prefab = defaultPrefab, prewarmCount = 20 }
+};
+
+// Gets special prefab
+var special = group.Get("special");
+
+// Gets default prefab (fallback)
+var unknown = group.Get("unknown_id");
+```
+
+---
+
+## See Also
+
+- [PrefabPool README](../README.md)

package/Docs/PrefabPool-API.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: c642e9208f6d946acaff8b89526ce88d
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Docs.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 7775acaa127c04e849f099a57796fd3f
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/README.md

@@ -1,105 +1,116 @@
-# Prefab Pool
+# PrefabPool
 
-Generic object pooling system for Unity.
+**Package:** `com.amanotes.prefabpool`  
+**Version:** 1.0.3
+
+Generic object pooling system for Unity with lifecycle callbacks and material pooling support.
+
+---
 
 ## Features
 
-- ✅ Simple API for Get/Return pattern
-- ✅ Automatic prefab instantiation
-- ✅ `IPoolPrefab` interface for lifecycle callbacks
-- ✅ Pre-warming support
-- ✅ Material pooling support
-- ✅ No dependencies on other packages
+- 🎮 Simple Get/Return API pattern
+- 🎯 Automatic prefab instantiation and reuse
+- 🎨 Lifecycle callbacks via IPoolPrefab interface
+- 🚀 Pre-warming support for performance
+- 🔧 Material pooling for dynamic instances
+
+---
+
+## Documentation
+
+**Complete documentation:** [`Docs/PrefabPool-API.md`](Docs/PrefabPool-API.md)
+
+---
 
 ## Installation
 
-Add to your `manifest.json`:
+Add the package to your Unity project via `Packages/manifest.json`:
+
 ```json
 {
   "dependencies": {
-    "com.amanotes.prefabpool": "1.0.0"
-  }
+    "com.amanotes.prefabpool": "1.0.3"
+  },
+  "scopedRegistries": [
+    {
+      "name": "npmjs",
+      "url": "https://registry.npmjs.org/",
+      "scopes": [
+        "com.amanotes.prefabpool"
+      ]
+    }
+  ]
 }
 ```
 
+---
+
 ## Quick Start
 
 ```csharp
-using Amanotes.PrefabPool;
-
-public class Example : MonoBehaviour
+public class PoolExample : MonoBehaviour
 {
+    private PrefabPool pool;
+    private PoolGroup enemyGroup;
+    
     void Start()
     {
-        var pool = new PrefabPool();
-        var group = CreatePoolGroup();
-        pool.RegisterGroup(group, transform);
+        pool = gameObject.AddComponent<PrefabPool>();
         
-        // Get object from pool
-        var obj = pool.Get<SpriteRenderer>("enemy");
+        enemyGroup = new PoolGroup
+        {
+            id = "enemies",
+            entries = new List<PoolEntry>
+            {
+                new PoolEntry { id = "basic_enemy", prefab = enemyPrefab, prewarmCount = 10 }
+            }
+        };
         
-        // Return to pool when done
-        pool.Return(obj.gameObject);
-    }
-}
-```
-
-## Usage
-
-### Implement IPoolPrefab
-
-```csharp
-public class Enemy : MonoBehaviour, IPoolPrefab
-{
-    public void OnGet()
-    {
-        // Called when retrieved from pool
-        gameObject.SetActive(true);
-        ResetState();
+        pool.RegisterGroup(enemyGroup, transform);
+        StartCoroutine(pool.Initialize());
     }
     
-    public void OnReturn()
+    void SpawnEnemy()
     {
-        // Called when returned to pool
-        gameObject.SetActive(false);
+        var enemy = enemyGroup.Get<Enemy>("basic_enemy");
+        enemy.transform.position = GetSpawnPosition();
     }
 }
 ```
 
-### Create Pool Configuration
-
-```csharp
-var poolGroup = ScriptableObject.CreateInstance<PoolGroup>();
-poolGroup.name = "Enemies";
-poolGroup.entries = new List<PoolEntry>
-{
-    new PoolEntry
-    {
-        id = "enemy",
-        prefab = enemyPrefab,
-        prewarmCount = 10
-    }
-};
-```
+---
 
 ## API Reference
 
-### IPrefabPool Interface
+### Key Classes
 
-```csharp
-void RegisterGroup(PoolGroup group, Transform parent);
-T Get<T>(string type) where T : Component;
-void Return(GameObject obj);
-IEnumerator Initialize();
-```
+**IPrefabPool**
+- Purpose: Core interface for pool management
+- Key methods: `RegisterGroup()`, `Get()`, `Return()`, `Initialize()`
 
-### IPoolPrefab Interface
+**PrefabPool**
+- Purpose: Main implementation of IPrefabPool
+- Key methods: `RegisterGroup()`, `Get()`, `Return()`, `Resize<T>()`
 
-```csharp
-void OnGet();    // Called when retrieved
-void OnReturn(); // Called when returned
-```
+**PoolGroup**
+- Purpose: Organizes related pool entries
+- Key methods: `Get()`, `Get<T>()`, `Return()`
+
+**IPoolPrefab**
+- Purpose: Lifecycle callbacks for pooled objects
+- Key methods: `OnGet()`, `OnReturn()`
+
+**See:** [Complete API Reference](Docs/PrefabPool-API.md)
+
+---
+
+## Dependencies
+
+- Unity 2022.3+
+
+---
 
-## License
+## Version History
 
-Copyright © Amanotes
+See [CHANGELOG.md](CHANGELOG.md)

package/Runtime/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("Amanotes.Core.PrefabPool.Tests")]

package/Runtime/AssemblyInfo.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: dbb42ee06dab541b2a794f805c10c871
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: