目录— 个文件
⌕
目录加载中…
…/core/objectPool/ObjectPool.ts
1import { Node, instantiate } from 'cc';
2import { Framework } from "../../../framework/Framework";
3import { ObjectBase } from "./ObjectBase";
4
5// 跟踪对象是否为临时扩容对象
6interface PoolObjectEntry<T extends ObjectBase> {
7 obj: T;
8 isTemporary: boolean; // 是否为临时对象(超出容量上限创建的对象)
9}
10
11/**
12 * 单个对象池实现(支持Component类型对象)
13 */
14export class ObjectPool<T extends ObjectBase> {
15 // 私有变量(小驼峰)
16 private name: string;
17 private maxCount: number;
18 private objects: PoolObjectEntry<T>[] = [];
19 private normalCount = 0;
20
21 //模板节点(已挂载ObjectBase组件)
22 private templateNode: Node;
23 //从模板节点提取的组件类型
24 private componentType: new () => T;
25
26 // 可读字段(大驼峰)
27 public get Name(): string {
28 return this.name;
29 }
30
31 /**
32 * 构造函数(基于模板节点创建对象池)
33 * @param templateNode 模板节点(必须已挂载ObjectBase子类组件)
34 * @param maxCount 最大常规容量(默认10)
35 * @param preloadCount 预加载数量(默认0)
36 */
37 constructor(
38 templateNode: Node,
39 maxCount: number = 10,
40 preloadCount: number = 0
41 ) {
42 // 1. 从模板节点提取ObjectBase组件
43 const sampleComponent = templateNode.getComponent(ObjectBase);
44 if (!sampleComponent) {
45 Framework.Log.Error("模板节点未挂载ObjectBase组件");
46 throw new Error("Invalid template node: missing ObjectBase component");
47 }
48
49 // 2. 验证组件类型并存储构造函数
50 this.componentType = sampleComponent.constructor as new () => T;
51 if (!this.componentType) {
52 Framework.Log.Error("无法获取组件构造函数");
53 throw new Error("Invalid component type");
54 }
55
56 // 3. 初始化核心属性
57 this.templateNode = templateNode; // 存储模板节点用于实例化
58 this.name = `${this.componentType.name}Pool`; // 基于组件类型自动命名
59 this.maxCount = Math.max(1, maxCount);
60
61 // 4. 预加载常规对象
62 if (preloadCount > 0) {
63 this.Preload(preloadCount);
64 }
65 }
66
67 /**
68 * 预加载常规对象
69 */
70 public Preload(count: number): void {
71 const needLoad = Math.min(count, this.maxCount - this.normalCount);
72 if (needLoad <= 0) return;
73
74 for (let i = 0; i < needLoad; i++) {
75 // 调用公共创建方法
76 const { obj: newObj, node } = this.CreateNewObject()!;
77 if (!newObj) continue;
78
79 newObj.OnRecycle(); // 预加载对象默认回收状态
80 this.objects.push({ obj: newObj, isTemporary: false });
81 this.normalCount++;
82 }
83 Framework.Log.Log(`对象池[${this.name}]预加载完成,常规对象数: ${this.normalCount}/${this.maxCount}`);
84 }
85
86
87 /**
88 * 获取对象(支持临时扩容)
89 */
90 public Spawn(): T | null {
91 // 1. 优先复用常规未使用对象
92 const reusableEntry = this.objects.find(
93 entry => !entry.isTemporary && !entry.obj.IsUsing
94 );
95 if (reusableEntry) {
96 // Framework.Log.Log(`对象池[${this.name}]复用对象: ${reusableEntry.obj.PoolName}`);
97 reusableEntry.obj.OnSpawn();
98 return reusableEntry.obj;
99 }
100
101 // 2. 创建新对象(调用公共创建方法)
102 const { obj: newObj, node } = this.CreateNewObject()!;
103 if (!newObj) return null;
104
105 // Spawn特有逻辑:标记为使用中
106 newObj.OnSpawn();
107
108 // 判断是否为临时对象(超出常规容量)
109 const isTemporary = this.normalCount >= this.maxCount;
110 this.objects.push({ obj: newObj, isTemporary });
111
112 // 非临时对象计数+1
113 if (!isTemporary) {
114 this.normalCount++;
115 }
116
117 return newObj;
118 }
119
120 /**
121 * 公共对象创建方法(提取Spawn和Preload的重复逻辑)
122 * @returns 新创建的组件和节点(失败返回null)
123 */
124 private CreateNewObject(): { obj: T; node: Node } | null {
125 // Framework.Log.Log(`对象池[${this.name}]创建新对象`);
126
127 // 1. 实例化模板节点
128 const node = instantiate(this.templateNode);
129 // 2. 获取组件
130 const newObj = node.getComponent(this.componentType);
131
132 // 3. 校验组件是否创建成功
133 if (!newObj) {
134 Framework.Log.Error(`对象池[${this.name}]组件创建失败: ${this.componentType.name}`);
135 node.destroy();
136 return null;
137 }
138
139 // 4. 公共初始化逻辑
140 newObj.PoolName = this.name; // 设置池名称
141 newObj.OnCreate(); // 调用创建生命周期
142
143 return { obj: newObj, node };
144 }
145
146
147 /**
148 * 回收对象(临时对象直接销毁,常规对象入池)
149 */
150 public Recycle(obj: T): void {
151 if (!obj || obj.PoolName !== this.name) {
152 Framework.Log.Error(`对象池[${this.name}]无法回收不属于自己的对象`);
153 obj?.OnRelease(); // 安全销毁外来对象
154 return;
155 }
156
157 const entry = this.objects.find(e => e.obj === obj);
158 if (!entry) {
159 Framework.Log.Error(`对象池[${this.name}]未找到该对象,直接销毁`);
160 obj.OnRelease();
161 return;
162 }
163
164 if (!obj.IsUsing) {
165 Framework.Log.Error(`对象池[${this.name}]回收重复对象,已忽略`);
166 return;
167 }
168
169 // 临时对象:直接销毁节点
170 if (entry.isTemporary) {
171 obj.OnRecycle();
172 obj.OnRelease(); // 内部会调用node.destroy()
173 this.objects.splice(this.objects.indexOf(entry), 1);
174 return;
175 }
176
177 // Framework.Log.Log(`对象池[${this.name}]回收对象: ${obj.PoolName}`);
178 // 常规对象:入池并重置状态
179 obj.OnRecycle();
180 }
181
182
183 /**
184 * 清空对象池(销毁所有节点)
185 */
186 public Clear(forceRelease: boolean = false): void {
187 for (let i = this.objects.length - 1; i >= 0; i--) {
188 const entry = this.objects[i];
189 if (entry.obj.IsUsing && !forceRelease) continue;
190 if (entry.obj.IsUsing) //如果选择强制回收 那么正在使用的话 先回收
191 {
192 entry.obj.OnRecycle(); // 回收对象
193 }
194 entry.obj.OnRelease(); // 销毁节点
195 this.objects.splice(i, 1);
196 if (!entry.isTemporary) {
197 this.normalCount--;
198 }
199 }
200 }
201
202 /**
203 * 获取池状态(含临时对象统计)
204 */
205 public GetStatus(): string {
206 const total = this.objects.length;
207 const used = this.objects.filter(e => e.obj.IsUsing).length;
208 const temporary = this.objects.filter(e => e.isTemporary).length;
209 return `对象池[${this.name}]: 常规容量=${this.maxCount}, 常规对象=${this.normalCount}, 临时对象=${temporary}, 在用=${used}, 总数=${total}`;
210 }
211
212 /**
213 * 获取当前使用中的对象数量
214 */
215 public GetUsingCount(): number {
216 return this.objects.filter(e => e.obj.IsUsing).length;
217 }
218}
讲解218 行
单类型对象池人工通读
ObjectPool.ts
以一个挂了 ObjectBase 子类组件的模板节点为源头,维护常规对象与临时扩容对象两类实例。取用时优先复用闲置常规对象,不够才新建;回收时临时对象直接销毁、常规对象隐藏回池,清空时逐个释放并同步常规计数。
按构造函数校验、Preload、Spawn、CreateNewObject、Recycle、Clear、GetStatus 的顺序读,重点看临时对象标记的判定时机。
特殊处理与易错点
- 易错点构造函数要求模板节点必须挂 ObjectBase 组件,缺失直接抛错;池名取组件类名加 Pool,而管理器用节点名加 Pool,两套命名可能对不上。L43
- 特殊处理最大容量至少归一为一,预加载数量会被剩余常规容量夹住,不会超过上限。L59
- 缓存与销毁时机是否临时对象看创建瞬间常规计数是否已达上限,因此超容对象回收时会被销毁而不是入池,池不会无限膨胀。L109
- 异常兜底回收前校验池名,不属于本池的对象直接走释放销毁,这是防止跨池误回收的强约束。L151
- 易错点回收一个未在使用的对象被当成重复回收,只打错误日志不改变状态。L165
- 特殊处理清空默认跳过使用中对象,强制模式下先回收再释放,两者都会同步扣减常规计数。L189
6注释跟踪对象是否为临时扩容对象
7属性obj(T):该模块的运行态字段。
8属性是否 Temporary(boolean):布尔开关/状态标记,用于显隐、分支或互斥判断。
14注释ObjectPool:单个对象池实现(支持Component类型对象)
16属性池名,由组件类名加 Pool 生成,回收时校验归属。
17属性常规容量上限,至少为一。
18属性池内全部对象条目,每条记录对象实例与是否为临时扩容。
22属性模板节点,Spawn 与 Preload 都靠它实例化新对象。
24注释从模板节点提取的组件类型
27方法只读返回池名,由构造函数按组件类名生成,回收时用于校验归属。
37方法校验模板节点的 ObjectBase 组件与构造函数,生成池名与容量,必要时立即预加载。
40属性构造函数(基于模板节点创建对象池)
43注释1. 从模板节点提取ObjectBase组件
50注释2. 验证组件类型并存储构造函数
57注释3. 初始化核心属性
62注释4. 预加载常规对象
70方法按剩余常规容量与请求数的较小值创建对象,先回收隐藏再入池并累加常规计数。
76注释调用公共创建方法
90方法先找未使用的常规对象复用,没有再新建,并按常规容量是否已满决定是否标记为临时对象。
92注释1. 优先复用常规未使用对象
97注释Framework.Log.Log(`对象池[${this.name}]复用对象: ${reusableEntry.obj.PoolName}`);
102注释2. 创建新对象(调用公共创建方法)
106注释Spawn特有逻辑:标记为使用中
109注释判断是否为临时对象(超出常规容量)
113注释非临时对象计数+1
124方法实例化模板节点并取组件,失败销毁节点返回空,成功则写入池名并调用创建钩子。
128注释Framework.Log.Log(`对象池[${this.name}]创建新对象`);
130注释2. 获取组件
133注释3. 校验组件是否创建成功
140注释4. 公共初始化逻辑
150方法校验池名与归属后,临时对象直接回收加释放并移出列表,常规对象只隐藏回池。
170注释临时对象:直接销毁节点
179注释Framework.Log.Log(`对象池[${this.name}]回收对象: ${obj.PoolName}`); 常规对象:入池并重置状态
186方法从尾到头遍历对象,默认跳过使用中项,强制模式先回收再释放,并同步扣减常规计数。
205方法统计常规容量、常规数、临时数与在用数,拼成一行便于调试的字符串。
215方法统计当前 IsUsing 为真的对象数量,供管理器决定是否移除池。