目录— 个文件
⌕
目录加载中…
…/core/scene/SceneManager.ts
1import { IFrameworkManager } from "../base/IFrameworkManager";
2import { Singleton } from "../base/Singleton";
3import { Framework } from "../../Framework";
4import { Node, instantiate, Prefab } from 'cc';
5import { SceneBase } from "./SceneBase";
6import { FrameworkEntry } from "../../FrameworkEntry";
7import { frameworkManager } from "../base/FrameworkClassRegistry";
8
9
10/**
11 * 场景管理器
12 * 场景以预制体的形式存在
13 */
14@frameworkManager()
15export class SceneManager extends Singleton<SceneManager> implements IFrameworkManager {
16
17 Name: string = "SceneManager";
18
19 //当前的场景
20 currScene: Node | null = null;
21 // 等待外部手动销毁的旧场景(当 SwitchScene 以 exitDelayTime < 0 调用时赋值)
22 private pendingDestroyScene: Node | null = null;
23 // 场景就绪任务计数(用于等待关键资源加载完成后再销毁旧场景)
24 private readyPendingCount: number = 0;
25 private readyPromise: Promise<void> | null = null;
26 private readyResolve: (() => void) | null = null;
27 private isReadyScene: boolean = false; //是否已经就绪
28
29 /**
30 * 初始化
31 */
32 public async Init(): Promise<void> {
33 // 记录管理器初始化入口,便于排查启动顺序。
34 Framework.Log.Log(this.Name, "Init", "初始化场景管理器");
35 }
36
37 /**
38 * 反初始化
39 */
40 public DeInit() {
41 // 重启后节点由引擎销毁,清除旧场景引用及就绪状态,供下一次启动重新建立。
42 this.currScene = null;
43 this.pendingDestroyScene = null;
44 this.readyPendingCount = 0;
45 this.readyPromise = null;
46 this.readyResolve = null;
47 this.isReadyScene = false;
48 }
49
50
51 Update(deltaTime: number): void {
52 }
53
54 /**
55 * 切换场景
56 * @param path
57 * @param args 场景参数
58 * @param callback 场景加载完成回调
59 * @param exitDelayTime 退出场景延迟时间;< 0 表示不自动销毁旧场景,由外部手动调用 DestroyPendingScene
60 * @constructor
61 */
62 SwitchScene(path: string, args?: any, callback?: Function, exitDelayTime: number = 0) {
63 if (!path) {
64 Framework.Log.Error(this.Name, "SwitchScene", "path is Null");
65 return;
66 }
67
68 Framework.Res.LoadAsset(path, Prefab, null, (err, prefab) => {
69 if (err) {
70 Framework.Log.Error(this.Name, "SwitchScene", "LoadAsset Error");
71 return;
72 }
73 let newScene = instantiate(prefab as Prefab);
74 let newScr = newScene.getComponent(SceneBase);
75 if (!newScr) {
76 Framework.Log.Error(this.Name, "SwitchScene", "SceneBase is Null");
77 return;
78 }
79 let oldScene = this.currScene;
80 //之前的场景存在
81 if (oldScene) {
82 //退出场景
83 oldScene.getComponent(SceneBase)?.ExitScene();
84 }
85
86 newScene.active = true;
87 newScene.setParent(FrameworkEntry.Instance!.SceneRoot);
88 //设置新场景为第一个节点
89 newScene.setSiblingIndex(0);
90
91 // 重置就绪任务状态(针对新场景)
92 this.readyPendingCount = 0;
93 this.readyPromise = null;
94 this.readyResolve = null;
95
96 this.currScene = newScene;
97 newScr.EnterScene(args);
98
99 if (callback) callback();
100
101 // 在新场景初始化与回调完成后,根据配置处理旧场景销毁
102 if (oldScene) {
103 if (exitDelayTime < 0) {
104 // 由外部手动决定何时销毁旧场景
105 this.pendingDestroyScene = oldScene;
106 } else if (exitDelayTime > 0) {
107 // 按延迟时间自动销毁旧场景
108 Framework.Timer.Delay(exitDelayTime, () => {
109 this.DestoryScene(oldScene);
110 }, this);
111 } else {
112 // 立即销毁旧场景
113 this.DestoryScene(oldScene);
114 }
115 }
116 }, { 'preloadAllBundleAssets': true });
117 }
118
119 /**
120 * 销毁挂起的旧场景(仅当 SwitchScene 传入 exitDelayTime < 0 时才会有挂起场景)
121 */
122 public DestroyPendingScene(): void {
123 if (!this.pendingDestroyScene) return;
124 Framework.Log.Log(this.Name, "DestroyPendingScene", "手动销毁挂起的旧场景", this.pendingDestroyScene.name);
125 this.DestoryScene(this.pendingDestroyScene);
126 this.pendingDestroyScene = null;
127 }
128
129 /**
130 * 开始场景就绪
131 */
132 public StartSceneReady(): void {
133 // Framework.Log.Log(this.Name, "StartSceneReady", "开始场景就绪");
134 this.readyPendingCount = 0;
135 this.readyPromise = null;
136 this.readyResolve = null;
137 this.isReadyScene = true;
138 }
139
140 /**
141 * 注册一个“场景就绪”任务(如关键资源加载),所有注册任务完成后 WaitSceneReady 才会 resolve
142 */
143 public RegisterReadyTask(promise: Promise<any>): void {
144 if (!this.isReadyScene) {
145 // Framework.Log.Log(this.Name, "RegisterReadyTask", "场景未就绪,不注册就绪任务");
146 return;
147 }
148
149 this.readyPendingCount++;
150 // Framework.Log.Log(this.Name, "RegisterReadyTask", "注册就绪任务: " + this.readyPendingCount);
151 // 创建(或复用)readyPromise,用于外部等待
152 if (!this.readyPromise) {
153 this.readyPromise = new Promise<void>((resolve) => {
154 this.readyResolve = resolve;
155 });
156 }
157
158 promise.finally(() => {
159 this.readyPendingCount--;
160 // Framework.Log.Log(this.Name, "RegisterReadyTask", "注册就绪任务完成: " + this.readyPendingCount);
161 if (this.readyPendingCount === 0 && this.readyResolve) {
162 this.readyResolve();
163 this.readyResolve = null;
164 }
165 });
166 }
167
168 /**
169 * 等待当前场景内所有已注册的就绪任务完成。
170 *
171 * 推荐用法:先通过 RegisterReadyTask 注册所有需要等待的任务,再调用 WaitSceneReady。
172 * 若当前没有任何任务(readyPendingCount === 0),则立即返回已完成的 Promise。
173 */
174 public WaitSceneReady(): Promise<void> {
175
176 // 没有任何就绪任务,视为已就绪
177 if (this.readyPendingCount === 0) {
178 // Framework.Log.Log(this.Name, "WaitSceneReady", "没有任何就绪任务,视为已就绪");
179 this.isReadyScene = false; // 任务结束,重置为false
180 return Promise.resolve();
181 }
182
183 // 已存在等待中的 Promise,直接复用
184 if (this.readyPromise) {
185 // Framework.Log.Log(this.Name, "WaitSceneReady", "已存在等待中的 Promise,直接复用");
186 // 通过 Promise 的回调,完成后设置 isReadyScene 为 false
187 return this.readyPromise.then(() => {
188 this.isReadyScene = false;
189 });
190 }
191
192 // 第一次等待,创建等待中的 Promise
193 // Framework.Log.Log(this.Name, "WaitSceneReady", "第一次等待,创建等待中的 Promise");
194 this.readyPromise = new Promise<void>((resolve) => {
195 this.readyResolve = () => {
196 resolve();
197 this.isReadyScene = false; // 任务全部完成时设置为false
198 };
199 });
200 return this.readyPromise;
201 }
202
203
204 /**
205 * 销毁场景
206 * @param scene需要销毁的场景
207 * @constructor
208 */
209 DestoryScene(scene: Node) {
210 if (!scene) return;
211 scene.active = false;
212 scene.destroy();
213
214 Framework.UI.DestoryAllPanels();
215 }
216
217
218 /**
219 * 获取当前场景
220 * @constructor
221 */
222 GetCurScene(): SceneBase | null {
223 if (!this.currScene) return null;
224 return this.currScene.getComponent(SceneBase);
225 }
226}
讲解227 行
场景管理器人工通读
SceneManager.ts
以预制体方式管理场景,负责加载并实例化新场景、挂到场景根节点、处理旧场景退出与销毁,同时维护场景就绪任务计数。入口或流程切换场景时调用 SwitchScene,关键资源可用 RegisterReadyTask 参与就绪等待。
先看 SwitchScene 的加载与旧场景处理分支,再看 StartSceneReady、RegisterReadyTask、WaitSceneReady 三件套,最后看 DestoryScene。
特殊处理与易错点
- 异常兜底Prefab 加载失败或预制体缺少 SceneBase 时直接返回,旧场景不会退出,新场景也不会创建。L68
- 初始化顺序依赖先 EnterScene 与外部 callback,再按 exitDelayTime 处理旧场景,旧场景销毁晚于新场景进入。L99
- 特殊处理exitDelayTime 小于零时旧场景只挂到 pendingDestroyScene,必须外部调用 DestroyPendingScene 才会真正销毁。L103
- 易错点RegisterReadyTask 只在 isReadyScene 为真时计数,场景未开始就绪或已结束时的注册会被静默忽略。L143
- 设计没有任何就绪任务时 WaitSceneReady 立即返回已完成 Promise,并把 isReadyScene 复位为 false。L177
- 销毁时机DestoryScene 销毁节点后无条件调用 UIManager 的 DestoryAllPanels,场景销毁会连带清空所有界面。L214
14注释场景管理器 场景以预制体的形式存在
15注释SceneManager:Prefab 场景管理器:SwitchScene 实例化场景、延迟销毁旧场景,并提供 Reg
17属性名称(string):模块/组件名称,用于日志、缓存 Key 或资源查找。
20属性当前场景节点,SwitchScene 写入,GetCurScene 与旧场景处理读取。
22属性延迟销毁模式下暂存的旧场景,等待 DestroyPendingScene 清理。
24属性未完成的场景就绪任务数,注册时加一,任务结束减一。
25属性等待所有就绪任务的 Promise,首次注册或等待时创建。
27属性就绪任务收集窗口标记,StartSceneReady 置真,等待完成后置假。
32方法只写一条初始化日志,不创建场景节点也不预加载资源。
34注释记录管理器初始化入口,便于排查启动顺序。
40方法清空当前场景与挂起场景引用,重置就绪计数、Promise 和就绪标记,供下次启动重建。
42注释重启后节点由引擎销毁,清除旧场景引用及就绪状态,供下一次启动重新建立。
51方法空实现,场景切换完全由异步回调驱动。
62方法异步加载场景预制体,校验组件后让旧场景退出,挂载新场景并重置就绪状态,再按延迟策略销毁旧场景。
81注释之前的场景存在
83注释退出场景
89注释设置新场景为第一个节点
92注释重置就绪任务状态(针对新场景)
102注释在新场景初始化与回调完成后,根据配置处理旧场景销毁
105注释由外部手动决定何时销毁旧场景
108注释按延迟时间自动销毁旧场景
113注释立即销毁旧场景
122方法若存在挂起旧场景则调用销毁流程并清空引用。
132方法清空就绪计数与等待 Promise,并把就绪窗口标记置真,允许后续注册任务。
134注释Framework.Log.Log(this.Name, "StartSceneReady", "开始场景就绪");
143方法就绪窗口开启时计数加一并挂到传入 Promise 的 finally,计数归零时唤醒等待者。
146注释Framework.Log.Log(this.Name, "RegisterReadyTask", "场景未就绪,不注册就绪任务");
152注释Framework.Log.Log(this.Name, "RegisterReadyTask", "注册就绪任务: " + this.readyPendingCount); 创建(或复用)readyPromise,用于外部等待
161注释Framework.Log.Log(this.Name, "RegisterReadyTask", "注册就绪任务完成: " + this.readyPendingCount);
174方法无任务时立即返回已完成 Promise,已有等待 Promise 时复用它,否则新建并挂上复位标记。
177注释没有任何就绪任务,视为已就绪
179注释Framework.Log.Log(this.Name, "WaitSceneReady", "没有任何就绪任务,视为已就绪");
184注释已存在等待中的 Promise,直接复用
187注释Framework.Log.Log(this.Name, "WaitSceneReady", "已存在等待中的 Promise,直接复用"); 通过 Promise 的回调,完成后设置 isReadyScene 为 false
194注释第一次等待,创建等待中的 Promise Framework.Log.Log(this.Name, "WaitSceneReady", "第一次等待,创建等待中的 Promise");
209方法把场景节点置为不可见并销毁,随后清空全部界面。
222方法读取当前场景节点上的 SceneBase 组件,没有场景或组件时返回空。