3-4-对象池模块.md

3-4. 对象池模块 - ObjectModule

🎮 模块概述

对象池模块是 TEngine 框架中的中量级对象管理工具，在客户端开发中是一个经常使用的技术。对象池通过对象复用机制，减少 GameObject 的创建和销毁开销，提升游戏性能。

✨ 核心优势

1. 🔄 对象复用

   • 减少 GameObject 的创建和销毁
   • 降低内存分配和 GC 压力
   • 提升游戏性能

2. 🎯 灵活的对象池类型

   • 支持单次获取对象池
   • 支持允许多次获取对象池
   • 可配置对象池容量和过期时间

3. 🛡️ 自动生命周期管理

   • 对象获取时自动初始化
   • 对象释放时自动清理
   • 支持对象池自动释放

---

📖 使用指南

1. 定义对象类

对象类需要继承 ObjectBase：

/// <summary>
/// Actor 对象。
/// </summary>
public class Actor : ObjectBase
{
    private GameObject _target;
    
    /// <summary>
    /// 创建 Actor 对象。
    /// </summary>
    /// <param name="name">对象名称。</param>
    /// <param name="target">对象持有实例。</param>
    /// <returns>Actor 对象实例。</returns>
    public static Actor Create(string name, object target)
    {
        var actor = MemoryPool.Acquire<Actor>();
        actor.Initialize(name, target);
        return actor;
    }
    
    /// <summary>
    /// 释放对象。
    /// </summary>
    /// <param name="isShutdown">是否是关闭对象池时触发。</param>
    protected override void Release(bool isShutdown)
    {
        _target = null;
    }
}

2. 创建对象池

public class ActorManager
{
    /// <summary>
    /// Actor 对象池。
    /// </summary>
    private IObjectPool<Actor> _actorPool;
    
    void Start()
    {
        // 创建允许单次获取的对象池
        _actorPool = GameModule.ObjectPool.CreateSingleSpawnObjectPool<Actor>(
            Utility.Text.Format("Actor Instance Pool ({0})", name)
        );
    }
}

3. 使用对象池

/// <summary>
/// 创建 Actor 对象。
/// </summary>
/// <param name="actorName">对象名称。</param>
/// <param name="target">对象持有实例。</param>
/// <returns>Actor 对象实例。</returns>
public Actor CreateActor(string actorName, GameObject target)
{
    Actor ret = null;
    
    if (_actorPool.CanSpawn())
    {
        // 从对象池中获取
        ret = _actorPool.Spawn();
    }
    else
    {
        // 创建新对象并注册到对象池
        ret = Actor.Create(actorName, target);
        _actorPool.Register(ret, true);
    }
    
    return ret;
}

/// <summary>
/// 释放 Actor 对象。
/// </summary>
/// <param name="actor">要释放的对象。</param>
public void ReleaseActor(Actor actor)
{
    if (actor != null)
    {
        _actorPool.Unspawn(actor);
    }
}

---

🔧 API 参考

对象池创建

/// <summary>
/// 创建允许单次获取的对象池。
/// </summary>
/// <typeparam name="T">对象类型（必须继承 ObjectBase）。</typeparam>
/// <param name="name">对象池名称。</param>
/// <param name="capacity">对象池容量。</param>
/// <param name="expireTime">对象过期时间（秒）。</param>
/// <param name="priority">对象池优先级。</param>
/// <returns>对象池实例。</returns>
IObjectPool<T> CreateSingleSpawnObjectPool<T>(
    string name,
    int capacity = int.MaxValue,
    float expireTime = float.MaxValue,
    int priority = 0
) where T : ObjectBase;

/// <summary>
/// 创建允许多次获取的对象池。
/// </summary>
IObjectPool<T> CreateMultiSpawnObjectPool<T>(
    string name,
    int capacity = int.MaxValue,
    float expireTime = float.MaxValue,
    int priority = 0
) where T : ObjectBase;

对象池操作

/// <summary>
/// 从对象池获取对象。
/// </summary>
T Spawn();

/// <summary>
/// 释放对象回对象池。
/// </summary>
void Unspawn(T obj);

/// <summary>
/// 注册对象到对象池。
/// </summary>
void Register(T obj, bool spawned);

/// <summary>
/// 检查是否可以获取对象。
/// </summary>
bool CanSpawn();

---

💡 最佳实践

1. 适合使用对象池的场景

• ✅ 频繁创建/销毁的 GameObject（如子弹、特效）
• ✅ UI 列表项（如背包物品、聊天消息）
• ✅ 游戏实体（如敌人、NPC）

2. 对象池类型选择

// 单次获取对象池：同一时间只能有一个对象被获取
// 适合：唯一对象（如玩家、主摄像机）
var singlePool = GameModule.ObjectPool.CreateSingleSpawnObjectPool<Player>("PlayerPool");

// 多次获取对象池：可以同时获取多个对象
// 适合：可复用的对象（如子弹、特效）
var multiPool = GameModule.ObjectPool.CreateMultiSpawnObjectPool<Bullet>("BulletPool");

3. 正确实现 Release 方法

// ✅ 推荐：在 Release 中清理所有引用
protected override void Release(bool isShutdown)
{
    _target = null;
    _data = null;
    // 清理所有引用，避免内存泄漏
}

---

🔗 相关链接

• 内存池模块文档 - 了解内存池模块（适合小对象）
• 资源模块文档 - 了解资源管理