# GameObjectPool 最优架构设计文档 ## 1. 文档目标 本文档定义 `GameObjectPool` 模块的目标形态，用于支撑游戏内所有 `GameObject` 相关对象的统一池化，包括但不限于： - 怪物 / NPC - 子弹 / 投射物 - 特效 / 粒子 / VFXGraph - 掉落物 / 临时交互物 - 飘字 / World UI - 音效壳对象 - 可复用的场景装饰物 目标不是做一个“能复用 prefab 的基础对象池”，而是做一个“可覆盖全项目高频对象生命周期管理”的统一池化体系。 --- ## 2. 现状结论 当前实现可以作为基础版对象池使用，但不是最优方案，主要原因如下： - 只处理 `SetActive`、`SetParent`、Transform 复位，不具备统一的业务状态重置协议 - 池满时只会返回 `null`，没有按对象类型区分溢出策略 - 预热只支持静态固定值，不支持场景级、战斗级、波次级预热 - 淘汰策略只基于时间，不包含优先级、预算、低内存策略 - 清理调度依赖全量扫描，不适合大量池并存 - 配置维度不足，无法精细支撑怪物、特效、子弹等不同对象类型 - 缺少自动回收能力 - 缺少运行时统计闭环，无法逼近最优容量配置 结论： - 当前实现可以继续作为底层雏形 - 不建议直接扩写成最终方案 - 最优方向应升级为“分层池化架构” --- ## 3. 设计目标 ### 3.1 功能目标 - 统一管理所有 `GameObject` 池化对象 - 支持同步获取、异步获取、预热、回收、自动回收 - 支持对象在复用前后执行自定义重置 - 支持按对象类型定义不同的容量与淘汰策略 - 支持运行时统计与调优建议导出 - 支持低内存场景下的激进回收 ### 3.2 性能目标 - 高频借还路径保持 O(1) 或近似 O(1) - 避免重复加载同一 prefab - 避免单帧大量 Instantiate / Destroy - 清理与预热都采用预算驱动，而不是无上限循环 - 复杂对象允许使用轻量休眠，而非强制全量 `SetActive` ### 3.3 工程目标 - 配置清晰，可由策划 / TA / 程序共同维护 - 业务接入方式统一，不让每个系统各自发明对象池 - 支持逐步迁移，兼容现有 `GameObjectPoolManager` --- ## 4. 总体架构 推荐采用三层结构。 ### 4.1 第一层：Prefab 池层 职责： - prefab 资源加载与引用持有 - 单 prefab 实例池管理 - 容量控制 - 预热 - 淘汰 - 调度 建议保留当前 `RuntimePrefabPool` 的职责方向，但增强其策略能力。 ### 4.2 第二层：实例生命周期层 职责： - 统一对象创建后初始化 - 对象借出前重置 - 对象归还前清理 - 对象销毁前释放内部资源 - 管理自动回收与上下文注入 该层是当前模块最缺失的部分，也是怪物、子弹、特效能够统一纳入池化的关键。 ### 4.3 第三层：业务门面层 职责： - 向业务提供强类型 API - 隐藏字符串路径、组名、预热细节 - 承载特定对象的默认策略 示例： ```csharp Enemy enemy = enemyPool.Spawn(enemyId, spawnContext); Bullet bullet = bulletPool.Spawn(bulletConfigId, spawnContext); FxHandle fx = fxPool.Play(fxId, position, rotation, autoRecycle: true); ``` 不建议把字符串 `assetPath` 作为业务层唯一入口。 字符串路径池应作为底层资源定位方式，而不是最终业务接口。 --- ## 5. 生命周期协议设计 统一池化必须提供明确的生命周期协议。 ### 5.1 核心接口 ```csharp public interface IGameObjectPoolable { void OnPoolCreate(); void OnPoolGet(in PoolSpawnContext context); void OnPoolRelease(); void OnPoolDestroy(); } ``` 语义建议： - `OnPoolCreate` 仅在实例第一次创建后调用一次 - `OnPoolGet` 每次借出时调用，用于注入上下文、重置运行态 - `OnPoolRelease` 每次归还时调用，用于停止逻辑、清理状态 - `OnPoolDestroy` 实例真正销毁前调用，用于释放自持资源 ### 5.2 可选扩展接口 ```csharp public interface IPoolAutoRecycle { bool TryGetAutoRecycleDelay(out float delaySeconds); } public interface IPoolResettablePhysics { void ResetPhysicsState(); } public interface IPoolResettableVisual { void ResetVisualState(); } public interface IPoolResettableAnimation { void ResetAnimationState(); } public interface IPoolSleepable { void EnterSleep(); void ExitSleep(in PoolSpawnContext context); } ``` 说明： - `IPoolSleepable` 主要给怪物 / NPC 这类重对象使用 - `IPoolResettablePhysics` 适合子弹、投射物、掉落物 - `IPoolResettableVisual` 适合特效、Trail、VFXGraph、Renderer 状态清理 ### 5.3 PoolSpawnContext `OnPoolGet` 需要统一上下文，避免靠外部脚本到处手动赋值。 建议结构： ```csharp public readonly struct PoolSpawnContext { public readonly string AssetPath; public readonly string Group; public readonly Transform Parent; public readonly Vector3 Position; public readonly Quaternion Rotation; public readonly object UserData; public readonly int OwnerId; public readonly int TeamId; public readonly uint SpawnFrame; } ``` 说明： - `UserData` 用于挂通用扩展参数 - 高频场景可以进一步拆成强类型上下文 --- ## 6. 池实例状态机 每个实例建议具备明确状态： - `Uninitialized` - `Inactive` - `Active` - `Releasing` - `Destroying` 状态转换： ```text Create -> Inactive -> Active -> Releasing -> Inactive Create -> Inactive -> Destroying -> Destroy Active -> Destroying -> Destroy ``` 价值： - 避免重复回收 - 避免回收中再次借出 - 便于统计与调试 - 便于做自动回收与异步保护 --- ## 7. 配置模型设计 当前 `PoolConfig` 维度不够，建议升级为两层配置： - `PoolProfile` - `PoolRule` ### 7.1 PoolProfile 定义一类对象的默认策略，例如： - `BulletProfile` - `FxProfile` - `EnemyProfile` - `UiWorldProfile` 示例字段： ```csharp public sealed class PoolProfile { public string profileName; public PoolObjectKind objectKind; public PoolOverflowPolicy overflowPolicy; public PoolTrimPolicy trimPolicy; public PoolActivationMode activationMode; public PoolResetMode resetMode; public int minRetained; public int softCapacity; public int hardCapacity; public float idleTrimDelay; public float prefabUnloadDelay; public float autoRecycleDelay; public int trimBatchPerTick; public int warmupBatchPerFrame; public float warmupFrameBudgetMs; public bool allowRuntimeExpand; public bool preloadOnInitialize; public bool keepPrefabResident; public bool aggressiveTrimOnLowMemory; } ``` ### 7.2 PoolRule 定义具体资源命中规则。 ```csharp public sealed class PoolRule { public string group; public string assetPath; public PoolMatchMode matchMode; public PoolResourceLoaderType loaderType; public string profileName; public bool overrideCapacity; public int minRetained; public int softCapacity; public int hardCapacity; public bool overridePrewarm; public int prewarmCount; public PoolPrewarmPhase prewarmPhase; public int priority; } ``` 设计原则： - `Profile` 管类型策略 - `Rule` 管具体命中 - 高频热点对象优先使用 `Exact` - `Prefix` 只做默认兜底 --- ## 8. 核心枚举草案 ### 8.1 对象类型 ```csharp public enum PoolObjectKind { Default = 0, Bullet = 1, Effect = 2, Enemy = 3, Npc = 4, Pickup = 5, WorldUi = 6, AudioProxy = 7, SceneProp = 8 } ``` ### 8.2 池满策略 ```csharp public enum PoolOverflowPolicy { FailFast = 0, InstantiateOneShot = 1, AutoExpand = 2, RecycleOldestInactive = 3, DropNewestRequest = 4 } ``` ### 8.3 清理策略 ```csharp public enum PoolTrimPolicy { None = 0, IdleOnly = 1, IdleAndPriority = 2, AggressiveOnLowMemory = 3 } ``` ### 8.4 激活模式 ```csharp public enum PoolActivationMode { SetActive = 0, SleepWake = 1, Custom = 2 } ``` ### 8.5 重置模式 ```csharp public enum PoolResetMode { TransformOnly = 0, PoolableCallbacks = 1, FullReset = 2, Custom = 3 } ``` ### 8.6 预热阶段 ```csharp public enum PoolPrewarmPhase { None = 0, AppInitialize = 1, SceneLoad = 2, BattlePrepare = 3, WavePrepare = 4, OnDemand = 5 } ``` --- ## 9. 不同对象类型的推荐策略 ### 9.1 子弹 建议： - `softCapacity` 较高 - `hardCapacity` 可比 `softCapacity` 高 1.5 到 2 倍 - 默认支持 `AutoExpand` 或 `InstantiateOneShot` - 必须支持自动回收 - 必须清理 `Rigidbody / Collider / TrailRenderer` - prefab 通常常驻，不建议频繁 unload ### 9.2 特效 / 粒子 建议： - 区分关键特效与普通特效 - 普通特效允许 `DropNewestRequest` - 回收时必须清理所有粒子系统、Trail、音效播放状态 - 支持“播完自动回池” - 预热由场景和技能装配共同驱动 ### 9.3 怪物 / NPC 建议： - 不建议只依赖通用 `SetActive` - 必须实现 `IGameObjectPoolable` - 推荐支持 `SleepWake` - 必须有 `minRetained` - 池满时不建议直接 `null` - 场景切换 / 波次结束后再做结构性收缩 ### 9.4 掉落物 / 临时交互物 建议： - 适合通用池 - 支持超时自动回收 - 支持来源信息重置 ### 9.5 飘字 / World UI 建议： - 高度适合池化 - 必须自动回收 - 必须重置 tween / alpha / scale / text / follow target --- ## 10. 预热策略设计 ### 10.1 预热阶段 预热必须是分阶段的，而不是只靠初始化时一次性完成。 建议阶段： - `AppInitialize` - `SceneLoad` - `BattlePrepare` - `WavePrepare` - `OnDemand` ### 10.2 预热预算 预热不允许无限制同步创建。 建议加入： - 每帧最大创建数 `warmupBatchPerFrame` - 每帧时间预算 `warmupFrameBudgetMs` - 大对象延迟到非关键帧创建 ### 10.3 自适应预热 建议收集以下统计并用于反哺配置： - `peakActive` - `peakTotal` - `missCount` - `expandCount` - `poolExhaustedCount` 由此生成： - 推荐 `softCapacity` - 推荐 `prewarmCount` - 推荐 `minRetained` --- ## 11. 淘汰策略设计 ### 11.1 默认原则 淘汰不能只看时间，还应结合： - 空闲时间 - 对象优先级 - 当前是否战斗中 - 当前内存压力 - 当前池容量是否超过软上限 ### 11.2 推荐容量模型 - `minRetained` 最低保有量，正常回收不低于该值 - `softCapacity` 常态推荐容量 - `hardCapacity` 绝对上限 ### 11.3 销毁预算 回收策略必须预算化： - 每 tick 最多回收 `trimBatchPerTick` - 必要时可以带时间预算，例如每帧不超过 `X ms` 这样可避免同一帧大量 `Destroy` ### 11.4 低内存策略 当收到 `Application.lowMemory` 时： - 忽略部分 `minRetained` - 优先回收低优先级池 - 优先卸载不常用 prefab - 进入短时激进回收模式 --- ## 12. 调度策略设计 当前全量扫描策略不适合作为最终版。 推荐： - 用最小堆维护池的下次清理时间 - 池状态变化时只更新自己的 `nextDueTime` - 调度器只处理到期池 - 清理和预热都按 budget 驱动 这样可以避免： - 每次回收都扫描所有池 - 大量池同时存在时的调度浪费 --- ## 13. 自动回收设计 推荐提供一组通用 helper / component： - `ReturnToPoolAfterSeconds` - `ReturnToPoolOnParticleStopped` - `ReturnToPoolOnAnimatorStateExit` - `ReturnToPoolOnAudioFinished` - `ReturnToPoolOnDistanceExceeded` - `ReturnToPoolOnCollision` 目标： - 业务不重复造轮子 - 自动回收行为可视化配置 - 减少“忘记 Release”导致的泄漏 --- ## 14. 运行时统计设计 最优方案必须带统计闭环。 每个池建议统计： - `acquireCount` - `releaseCount` - `hitCount` - `missCount` - `peakActive` - `peakTotal` - `expandCount` - `exhaustedCount` - `autoRecycleCount` - `destroyCount` - `avgLifetime` - `avgIdleTime` - `avgAcquireCostMs` - `avgReleaseCostMs` 调试用途： - Inspector 面板 - 运行时快照 - CSV / JSON 导出 - 自动生成调优建议 --- ## 15. 推荐默认配置区间 以下是默认建议值，不是硬编码结论，应由运行时统计修正。 ### 15.1 通用默认 - `minRetained = 2 ~ 8` - `softCapacity = 8 ~ 32` - `hardCapacity = softCapacity * 1.5 ~ 2` - `idleTrimDelay = 15s ~ 60s` - `prefabUnloadDelay = 60s ~ 300s` - `trimBatchPerTick = 1 ~ 4` ### 15.2 子弹默认 - `minRetained = 16` - `softCapacity = 64` - `hardCapacity = 128` - `overflowPolicy = AutoExpand` - `prefabUnloadDelay = 300s` ### 15.3 普通特效默认 - `minRetained = 4` - `softCapacity = 16` - `hardCapacity = 32` - `overflowPolicy = DropNewestRequest` - `idleTrimDelay = 20s` ### 15.4 怪物默认 - `minRetained = 2` - `softCapacity = 8` - `hardCapacity = 16` - `overflowPolicy = AutoExpand` - `activationMode = SleepWake` --- ## 16. 与当前实现的映射关系 当前模块中可保留的部分： - `GameObjectPoolManager` 继续作为总入口和调度器雏形 - `RuntimePrefabPool` 继续作为单 prefab 池雏形 - `PoolConfig` 升级为新配置模型的一部分 - `IResourceLoader` 可继续作为资源加载抽象 需要重点重构的部分： - 实例生命周期协议 - 池满策略 - 预热与清理预算调度 - 统计系统 - 自动回收组件 - 怪物/特效/子弹的分类默认策略 --- ## 17. 迁移路线 建议分四个阶段落地。 ### 阶段 1：补生命周期协议 目标： - 引入 `IGameObjectPoolable` - Acquire / Release 时统一回调 - 允许对象自定义重置 ### 阶段 2：补配置模型 目标： - 引入 `PoolProfile + PoolRule` - 加入 `minRetained / softCapacity / hardCapacity / overflowPolicy` - 兼容旧 `PoolConfig` ### 阶段 3：补自动回收与预算调度 目标： - 自动回收 helper - 分帧 warmup - 预算式 trim - 低内存模式 ### 阶段 4：补统计与业务门面 目标： - 运行时统计面板 - 容量推荐导出 - `EnemyPool / BulletPool / FxPool` 业务门面 --- ## 18. 最终结论 最优对象池方案不是单一 `GameObject` 缓存容器，而是： - 以 prefab 池为底层 - 以生命周期协议为核心 - 以分类策略为手段 - 以预算调度为性能保障 - 以统计闭环为调优依据 如果后续按本文档实施，建议优先级如下： 1. `IGameObjectPoolable` 与 `PoolSpawnContext` 2. `PoolProfile + PoolRule` 3. `PoolOverflowPolicy` 4. 自动回收 helper 5. 分帧预热与预算清理 6. 运行时统计与调优导出