找物源码导读Cocos Creator 3.8 · assets/scripts
0%
已读 0 / 424
目录— 个文件
目录加载中…
…/scripts/framework/FrameworkEntry.ts
1import { _decorator, Camera, Component, director, DynamicAtlasManager, game, Game, Node, sys } from 'cc';
2import EditorConfigScript from './core/base/EditorConfigScript';
3import { IFrameworkManager } from './core/base/IFrameworkManager';
4import { Framework } from './Framework';
5import { SdkChannel } from './module/sdk/SdkChannel';
6import { SdkConfig } from './module/sdk/SdkConfig';
7
8// 公司固定启动流程由框架维护,项目只选择初始流程和玩法恢复行为。
9// Polyfill Promise.prototype.finally for minigame runtimes that don't support ES2018
10if (typeof Promise.prototype.finally !== 'function') {
11 Promise.prototype.finally = function <T>(this: Promise<T>, onFinally?: (() => void) | undefined | null): Promise<T> {
12 return this.then(
13 (value) => { onFinally?.(); return value; },
14 (reason) => { onFinally?.(); throw reason; },
15 );
16 };
17}
18
19const { ccclass, property } = _decorator;
20
21@ccclass('FrameworkEntry')
22export abstract class FrameworkEntry extends Component {
23
24 @property(Camera)
25 camera: Camera = null!;
26 @property(Node)
27 private sceneRoot: Node = null!; //场景根节点
28 @property(Node)
29 private uiRoot: Node = null!; //UI根节点
30
31 // 公司统一达人挂载点,保留原字段名以继承现有场景绑定。
32 @property(Node)
33 private talentRoot: Node = null!;
34
35 // 保留原序列化字段名,GameEntry 继承现有场景中的配置引用。
36 @property(EditorConfigScript)
37 private editorConfigScript: EditorConfigScript = null!;
38
39 get SceneRoot(): Node {
40 return this.sceneRoot;
41 }
42 get UIRoot(): Node {
43 return this.uiRoot;
44 }
45
46 get TalentRoot(): Node {
47 return this.talentRoot;
48 }
49
50 get Camera(): Camera {
51 return this.camera;
52 }
53
54 private static instance: FrameworkEntry = null!;
55
56 public static get Instance(): FrameworkEntry | null {
57 if (this.instance == null) {
58 console.error("FrameworkEntry.Instance is null");
59 return null;
60 }
61 return this.instance;
62 }
63
64 public static ProjectName: string = ""; //项目名称
65
66 // 存储管理器实例的数组
67 private managerArray: IFrameworkManager[] = [];
68
69 onLoad() {
70 // 固定配置同步必须在管理器初始化前,计时与实例赋值顺序保持不变。
71 Framework.Sdk.LaunchStartMs = Date.now();
72 FrameworkEntry.instance = this;
73 game.frameRate = 60;
74 // 先注入配置并选择加载器,再由编辑器及发行包覆盖;此处不初始化或加载资源。
75 this.ConfigurePackage();
76 this.ConfigureResource();
77 this.ConfigureUI();
78 this.editorConfigScript.SyncConfig();
79 // 可选配置与实验都依赖同步后的最终发行包。
80 this.ConfigureConfig();
81 // 实验参与范围依赖最终发行包,仅装配;分桶仍等待玩家存档就绪。
82 this.ConfigureAB();
83
84 // 微信真机存在动态合图 UV 串图问题,关闭动态合图;其他渠道保留原有行为。
85 DynamicAtlasManager.instance.enabled = SdkConfig.Channel !== SdkChannel.Wechat;
86
87 director.addPersistRootNode(this.node); //节点常驻 切换场景不销毁
88
89 //***核心框架模块************************************************************//
90 this.managerArray.push(Framework.Data);
91 this.managerArray.push(Framework.Procedure);
92 this.managerArray.push(Framework.Scene);
93 this.managerArray.push(Framework.Res);
94 this.managerArray.push(Framework.UI);
95 this.managerArray.push(Framework.Audio);
96 this.managerArray.push(Framework.Log);
97 this.managerArray.push(Framework.Event);
98 this.managerArray.push(Framework.Pool);
99 this.managerArray.push(Framework.Timer);
100 this.managerArray.push(Framework.Tsrpc);
101 this.managerArray.push(Framework.Version);
102
103 //***通用业务模块************************************************************//
104 this.managerArray.push(Framework.Sdk);
105 this.managerArray.push(Framework.Config);
106 this.managerArray.push(Framework.Package);
107 this.managerArray.push(Framework.Server);
108 this.managerArray.push(Framework.Login);
109 this.managerArray.push(Framework.AB);
110
111 this.InitFramework();
112 }
113
114 async start() {
115 // 固定启动链只执行一次;资源加载能力本身不在本轮修改。
116 await Framework.Res.LoadResourceInfo();
117 const loginResult = await Framework.Login.Login();
118 // 登录要求重启时保持原语义,不准备存档、不进入玩法、不注册监听。
119 if (!loginResult) return;
120 await Framework.Data.PrepareData(loginResult.Success);
121
122 // 项目仅选择具体初始流程,前后台监听仍在启动项目流程之后注册。
123 this.StartGame();
124 game.on(Game.EVENT_HIDE, this.OnGameHide, this);
125 game.on(Game.EVENT_SHOW, this.OnGameShow, this);
126 }
127
128
129 /** 项目必须指定初始流程,框架不依赖具体流程枚举。 */
130 protected abstract StartGame(): void;
131
132 update(deltaTime: number) {
133 this.UpdateFramework(deltaTime);
134 }
135
136 onDestroy() {
137 // 入口销毁后不再接收前后台事件。
138 game.off(Game.EVENT_HIDE, this.OnGameHide, this);
139 game.off(Game.EVENT_SHOW, this.OnGameShow, this);
140 this.DeInitFramework()
141 }
142
143
144 /**
145 * 初始化框架
146 */
147 private InitFramework(): void {
148 this.managerArray.forEach((manager) => {
149 manager.Init();
150 });
151 }
152
153 /**
154 * 更新框架
155 * @param deltaTime 时间增量
156 */
157 private UpdateFramework(deltaTime: number) {
158 this.managerArray.forEach(manager => {
159 manager.Update(deltaTime);
160 });
161 }
162
163 /**
164 * 销毁框架
165 */
166 private DeInitFramework() {
167 //todo System 销毁
168
169 this.managerArray.forEach(manager => {
170 manager.DeInit();
171 });
172
173
174 }
175
176 /**
177 * 重新开始游戏
178 */
179 public RestartGame() {
180 // 手动触发垃圾回收
181 sys.garbageCollect();
182 // 重启游戏
183 game.restart();
184 }
185
186 /**
187 * 游戏进入后台时的处理
188 */
189 protected OnGameHide(): void {
190 console.log("游戏进入后台");
191 Framework.Sdk.ReportGameLifecycle(false);
192 Framework.Audio.HandleAppHide();
193 // 尽力立即提交尚未上传的完整存档;本地模式下 Flush 不会发起请求。
194 Framework.Data.Flush();
195 }
196
197 /**
198 * 游戏回到前台时的处理
199 */
200 protected OnGameShow(): void {
201 console.log("游戏回到前台");
202 Framework.Sdk.ReportGameLifecycle(true);
203 Framework.Audio.HandleAppShow();
204 }
205
206 /** 注入项目资源配置并选择加载器;构造时不得读取最终配置,初始化在 SyncConfig 后执行。 */
207 protected ConfigureResource(): void { }
208
209 /** 项目发行表必须先于编辑器配置同步装配。 */
210 protected abstract ConfigurePackage(): void;
211
212 /** 最终发行配置同步后,由项目选择本次参与的实验。 */
213 protected abstract ConfigureAB(): void;
214
215 /** 注入项目 UI 配置,不提前创建面板;公司固定 UI 配置由框架自身维护。 */
216 protected abstract ConfigureUI(): void;
217
218 /** 注入项目启动配置清单和远端目录规则,不提前加载配置。 */
219 protected abstract ConfigureConfig(): void;
220
221
222}
讲解223 行
框架启动基类人工通读

FrameworkEntry.ts

所有项目的启动基类,固定了“配置装配 → 管理器注册 → Init → 资源信息加载 → 登录 → 存档准备 → 进入首个流程”的启动链。GameEntry 继承它并实现四个抽象配置方法和 StartGame。

按 onLoad → start → StartGame 的顺序看,注意 onLoad 里配置方法的调用次序,那是整个框架最容易踩坑的地方。

特殊处理与易错点

10注释公司固定启动流程由框架维护,项目只选择初始流程和玩法恢复行为。 Polyfill Promise.prototype.finally for minigame runtimes that don't support ES2018
22注释FrameworkEntry:项目必须指定初始流程,框架不依赖具体流程枚举。
25属性camera(Camera):该模块的运行态字段。
27属性场景根节点,子类通过 SceneRoot 取用,业务节点挂在这里。
29属性UI 根节点,UIManager 的分组节点会挂在它下面。
32注释公司统一达人挂载点,保留原字段名以继承现有场景绑定。
33属性公司统一的达人挂载点,保留字段名以兼容场景绑定。
36注释保留原序列化字段名,GameEntry 继承现有场景中的配置引用。
37属性编辑器配置脚本引用,onLoad 时调用 SyncConfig 把编辑器里的配置同步到运行时。
39方法暴露编辑器绑定的场景根节点供场景管理器挂载游戏场景。
42方法暴露编辑器绑定的UI根节点供界面管理器创建分层容器。
46方法暴露统一达人内容挂载节点,沿用现有场景序列化绑定。
50方法暴露入口绑定的Cocos相机组件供框架和业务查询使用。
56方法读取onLoad记录的框架入口单例,尚未设置时记录错误。
67属性注册进框架的所有管理器实例,Init/Update/DeInit 三个循环都遍历它;顺序即执行顺序。
69方法固定装配配置并同步编辑器值,注册常驻节点和管理器后依次初始化。
71注释固定配置同步必须在管理器初始化前,计时与实例赋值顺序保持不变。
75注释先注入配置并选择加载器,再由编辑器及发行包覆盖;此处不初始化或加载资源。
80注释可选配置与实验都依赖同步后的最终发行包。
82注释实验参与范围依赖最终发行包,仅装配;分桶仍等待玩家存档就绪。
85注释微信真机存在动态合图 UV 串图问题,关闭动态合图;其他渠道保留原有行为。
90注释核心框架模块
104注释通用业务模块
114方法先加载资源信息再登录准备存档,启动项目流程后注册前后台监听。
116注释固定启动链只执行一次;资源加载能力本身不在本轮修改。
119注释登录要求重启时保持原语义,不准备存档、不进入玩法、不注册监听。
123注释项目仅选择具体初始流程,前后台监听仍在启动项目流程之后注册。
130方法抽象方法,子类在这里启动具体初始流程;框架不依赖任何具体流程枚举。
132方法每帧把 deltaTime 转发给 managerArray 里的所有管理器。
136方法移除前后台事件监听,并调用 DeInit 让所有管理器释放资源。
138注释入口销毁后不再接收前后台事件。
147方法遍历 managerArray 依次调用 Init,建立管理器之间的依赖状态。
157方法遍历 managerArray 依次调用 Update,把帧时间交给每个管理器。
166方法按注册顺序销毁所有管理器,业务系统额外销毁仍留有待办。
169注释todo System 销毁
179方法先请求JavaScript垃圾回收,再调用引擎重新启动整个游戏。
181注释手动触发垃圾回收
183注释重启游戏
189方法切后台回调:上报生命周期事件、通知音频管理器暂停、并尽力把未上传的存档 Flush 一次。
194注释尽力立即提交尚未上传的完整存档;本地模式下 Flush 不会发起请求。
200方法回前台回调:上报生命周期事件并通知音频管理器恢复播放。
207方法默认空实现,项目可覆写以注入资源配置并选择资源加载器。
210方法抽象方法,项目必须装配发行表;它先于编辑器配置同步执行。
213方法抽象方法,项目在最终发行配置同步之后选择本次参与的实验。
216方法抽象方法,项目注入 UI 配置与分组,不提前创建面板。
219方法抽象方法,项目注入配置清单与远端目录规则,不提前加载配置。