NodePool

重要 注意 提醒

Coding Style wiki

---

NodePool 是 PoolSystem 的簡易 GameObject 物件池組件 (MonoBehaviour)，以 Queue (先進先出) 管理閒置物件，支持異步分散幀加載 (負載平衡)、自動增長 (Auto Put) 與最大數量限制 (Max Size)；透過 Add Component -> OxGKit -> PoolSystem -> NodePool 掛載至場景節點上使用 (該節點即為物件池的容器節點)。

命名空間	OxGKit.PoolSystem
類型	public class NodePool : MonoBehaviour
原始碼	NodePool.cs

using OxGKit.PoolSystem;

注意 分散幀加載基於 UniTask 實現，啟用時 Initialize 會異步分批建立物件，可透過 IsLoadFinished 確認完成時機。

快速上手

using OxGKit.PoolSystem;
using UnityEngine;

// 於 Inspector 指定場景上的 NodePool (已配置 Source GameObject)
public NodePool objPool;

// 手動初始物件池 (勾選 initializeOnStart 則會於 Start 自動初始)
this.objPool.Initialize();

// 從物件池取出並指定父節點 (池中無可用物件且未開啟 autoPut 時會回傳 null)
var go = this.objPool.Get(this.transform);

// 使用完畢歸還物件池
this.objPool.Put(go);

通用規則

生命週期

1. 初始：勾選 initializeOnStart (預設) 會於 Start 自動呼叫 Initialize；取消勾選則自行決定初始時機。
2. 取出/歸還：以 Get 取出物件 (自動 SetActive(true))，使用完畢以 Put 歸還 (自動 SetActive(false) 並歸位至池節點下)。
3. 清空：組件 OnDestroy 時會自動呼叫 Clear，取消未完成的加載任務並銷毀池中物件。

重要 Source GameObject (go) 不能為空，未指定來源時初始物件池會擲出 ArgumentNullException；另外請勿自行 Destroy 池化物件，務必以 Put 歸還，否則物件池數量會逐漸縮減。

物件狀態重置

池化物件是重複使用的，Get 取出時不會重置物件狀態，請於物件的 OnEnable 或取出後自行重置 (例如速度、拖尾、協程等)，切勿假設物件為全新實例化的狀態。

自動增長批次設定

注意 目前版本 (v1.0.2) 的自動增長 (Auto Put) 分散幀流程，「每生成 N 個物件」的批次數量沿用 initDelayFrameAfterSpawnCount 設定 (autoDelayFrameAfterSpawnCount 尚未被使用)，延遲幀數則使用 autoPutDelayFrame。

日誌輸出

本模組的日誌透過 LoggingSystem 輸出，日誌器名稱為 OxGKit.PoolSystem.Logger，可透過其配置開關與級別。

---

成員

成員	說明
public GameObject go	物件池的來源物件 (Inspector: Source GameObject)，必填。
public bool initializeOnStart	是否於 Start 自動初始物件池 (預設 true)。
public int initSize	物件池的初始數量 (預設 5)。
public bool initLoadAcrossFrames	初始時啟用分散幀加載 (預設 true)。
public int initDelayFrameAfterSpawnCount	初始時每生成 N 個物件後進行延遲 (預設 1，配置 <= 0 會自動修正為 1)。
public int initDelayFrame	初始時每批延遲的幀數 (預設 1)。
public bool autoPut	池中無可用物件時，是否自動增生 (預設 false)。
public int autoPutSize	每次自動增生的數量 (預設 1)。
public bool autoPutLoadAcrossFrames	自動增生時啟用分散幀加載 (預設 true)。
public int autoDelayFrameAfterSpawnCount	自動增生時每生成 N 個物件後進行延遲 (預設 1，詳見自動增長批次設定)。
public int autoPutDelayFrame	自動增生時每批延遲的幀數 (預設 1)。
public int maxSize	物件池上限，0 或 -1 為不限制，> 0 時 initSize 與 autoPut 增生皆會受限 (預設 0)。

---

初始與管理

方法總覽

方法	說明
Initialize	初始物件池 (會先清空再依 initSize 重新建立)。
IsLoadFinished	初始或自動增生的加載流程是否完成。
Count	當前池中的閒置物件數量。
Clear	清空物件池 (取消加載任務並銷毀池中物件)。

---

Initialize

public void Initialize()

初始物件池：會先呼叫 Clear 清空，再依 initSize 建立物件並放入池中 (maxSize > 0 時以 Min(initSize, maxSize) 為準)；啟用 initLoadAcrossFrames 時，會以異步分散幀方式分批建立。

提醒 勾選 initializeOnStart 會於 Start 自動呼叫；重複呼叫等同於重建物件池。

// 手動初始物件池 (取消勾選 initializeOnStart 時)
this.objPool.Initialize();

IsLoadFinished

public bool IsLoadFinished()

回傳初始或自動增生的加載流程是否已完成；啟用分散幀加載時，建議在需要完整物件池的時機前 (例如大量生成前) 先行確認。

if (this.objPool.IsLoadFinished())
{
    // 物件池已就緒
}

Count

public int Count()

回傳當前池中的閒置物件數量 (Get 取出會遞減、Put 歸還會遞增)。

int count = this.objPool.Count();

Clear

public void Clear()

清空物件池：取消尚未完成的加載任務，銷毀池中所有物件並將計數歸零；組件 OnDestroy 時會自動呼叫。

注意 清空僅會銷毀池中閒置物件，已被 Get 取出的物件不受影響；請留意功能關閉順序，物件池銷毀後不應再對其呼叫 Put。

---

取出與歸還

方法總覽

方法	說明
Get	從物件池取出物件 (支持指定父節點、座標與旋轉)。
Put	將物件歸還物件池 (超出 maxSize 會直接銷毀)。

---

Get

public GameObject Get()

public GameObject Get(Transform parent)

public GameObject Get(Transform parent, Vector3 position)

public GameObject Get(Transform parent, Vector3 position, Quaternion rotation)

從物件池取出物件並自動 SetActive(true)：

• 無參數：物件會脫離池節點 (父節點設為 null)。
• parent：取出後掛至指定的父節點下。
• position：設置物件的 localPosition (局部座標)。
• rotation：設置物件的 rotation (世界空間旋轉)。

池中無可用物件時：

• 已啟用 autoPut 且 autoPutSize > 0 → 自動增生並返回物件 (即使開啟分散幀加載，第一個物件仍會同幀建立並立即返回)。
• 未啟用 autoPut → 回傳 null，呼叫端需自行判空。

注意 position 設置的是 localPosition，會受父節點 Transform 影響；rotation 則為世界空間旋轉。

// 取出並指定父節點
var go = this.objPool.Get(this.transform);
if (go != null)
{
    // 使用物件...
}

// 取出並指定父節點、局部座標與旋轉
var go2 = this.objPool.Get(parent, Vector3.zero, Quaternion.identity);

Put

public void Put(GameObject go)

將物件歸還物件池：自動歸位至池節點下並 SetActive(false)；若 maxSize > 0 且池中數量已達上限，則直接銷毀該物件並輸出日誌提醒。

提醒 maxSize 統計的是池中閒置物件數量，場上使用中的物件歸還時若池已滿即會被銷毀，請以尖峰同時使用量評估上限。

// 使用完畢歸還物件池
this.objPool.Put(go);