Cocos Creator 资源加载流程剖析【一】——cc.loader与加载管线
这系列文章会对Cocos Creator的资源加载和管理进行深入的剖析。主要包含以下内容：
- cc.loader与加载管线
- Download部分
- Load部分
- 额外流程（MD5 Pipe）
- 从编辑器到运行时
- 场景切换流程
前面4章节介绍了完整的资源加载流程以及资源管理，以及如何自定义这个加载流程（有时候我们需要加载一些特殊类型的资源）。“从编辑器到运行时”介绍了我们在编辑器中编辑的场景、Prefab等资源是如何序列化到磁盘，打包发布之后又是如何被加载到游戏中。
准备工作
在开始之前我们需要解决这几个问题：
- 如何阅读代码？
引擎的代码大体分为js和原生c++ 两种类型，在web平台上不使用任何 c++ 代码，而是一个基于webgl编写的渲染底层。而在移动平台上仍然使用 c++ 的底层，通过jsb将原生的接口暴露给上层的js。在引擎安装目录下的resources/engine下放着引擎的所有js代码。而原生c++ 代码放在引擎安装目录下的resources/cocos2d-x目录下。我们可以在这两个目录下查看代码。这系列文章中我们要查看的代码位于引擎安装目录下的resources/engine/cocos2d/core/load-pipeline目录下。
- 如何调试代码？
JS的调试非常简单，我们可以在Chrome浏览器运行程序，按F12进入调试模式，通过ctrl + p快捷键可以根据文件名搜索源码，进行断点调试。具体的各种调试技巧可参考以下几个教程。
- https://juejin.im/entry/5804669f570c35006c828548
- http://wiki.jikexueyuan.com/project/chrome-devtools/debugging-javascript.html
- https://developers.google.com/web/tools/chrome-devtools/javascript/
原生平台的调试也可以用Chrome，官方的文档介绍了如何调试原生普通的JS代码。至于原生平台的C++ 代码调试，可以在Windows上使用Visual Studio调试，也可以在Mac上使用XCode调试。
- https://docs.cocos.com/creator/manual/zh/publish/debug-jsb.html
- https://docs.cocos.com/creator/manual/zh/publish/debug-native.html
框架结构
首先我们从整体上观察CCLoader大致的类结构，这个密密麻麻的图估计没有人会仔细看，所以这里简单介绍一下：
- 我们的CCLoader继承于Pipeline，CCLoader提供了友好的资源管理接口（加载、获取、释放）以及一些辅助接口（如自动释放、对Pipeline的修改）。
- Pipeline中主要包含了多个Pipe和多个LoadingItems，这里实现了一个Pipe到Pipe衔接流转的过程，以及Pipe和LoadingItems的管理接口。
- Pipe有多种子类，每一种Pipe都会对资源进行特定的加工，后面会对每一种Pipe都作详细介绍。
- LoadingItems为一个加载队列，继承于CallbackInvoker，管理着LoadingItem（注意没有复数），一个LoadingItem就是资源从开始加载到加载完成的上下文。这里说的上下文，指的是与加载该资源相关的变量的集合，比如当前加载的状态、url、依赖哪些资源、以及加载完成后的对象等等。
CocosCreator2.x和1.x版本对比，整个加载的流程没有太大的变化，主要的变化是引入了FontLoader，将Font初始化的逻辑从Downloader转移到了Loader这个Pipe中。将JSB的部分分开，在编译时彻底根据不同的平台编译不同的js，而不是在一个js中使用条件判断当前是什么平台来执行对应的代码。其他优化了一些写法，比如cc.Class.inInstanceOf调整为instanceof，JS.getClassName、cc.isChildClassOf等方法移动到js这个模块中。
资源加载
CCLoader提供了多种加载资源的接口，要加载的资源必须放到resources目录下，我们在加载资源的时候，除了要加载的资源url和完成回调，最好将type参数传入，这是一个良好的习惯。CCLoader提供了以下加载资源的接口：
- load(resources, progressCallback, completeCallback)
- loadRes(url, type, progressCallback, completeCallback)
- loadResArray(urls, type, progressCallback, completeCallback)
- loadResDir(url, type, progressCallback, completeCallback)
loadRes是我们最常用的一个接口，该函数主要做了3个事情：
- 调用_getResUuid查询uuid，该方法会调用AssetTable的getUuid方法查询资源的uuid。从网络上加载的资源以及SD卡中我们存储的资源，Creator并没有为它们生成uuid。所以这些不是在Creator项目中生成的资源不能使用loadRes来加载。
- 调用this.load方法加载资源。
- 在加载完成后，该资源以及其引用的资源都会被标记为禁止自动释放（在场景切换的时候，Creator会自动释放下个场景不使用的资源）。
proto.loadRes = function (url, type, progressCallback, completeCallback) {
var args = this._parseLoadResArgs(type, progressCallback, completeCallback);
type = args.type;
progressCallback = args.onProgress;
completeCallback = args.onComplete;
var self = this;
var uuid = self._getResUuid(url, type);
if (uuid) {
this.load(
{
type: 'uuid',
uuid: uuid
},
progressCallback,
function (err, asset) {
if (asset) {
// 禁止自动释放资源
self.setAutoReleaseRecursively(uuid, false);
}
if (completeCallback) {
completeCallback(err, asset);
}
}
);
}
else {
self._urlNotFound(url, type, completeCallback);
}
};
无论调用哪个接口，最后都会走到load函数，load函数做了几个事情，首先是对输入的参数进行处理，以满足其他资源加载接口的调用，所有要加载的资源最后会被添加到_sharedResources中（不论该资源是否已加载，如果已加载会push它的item，未加载会push它的res对象，res对象是通过getResWithUrl方法从AssetLibrary中查询出来的，AssetLibrary在后面的章节中会详细介绍）。
load和其它接口的最大区别在于，load可以用于加载绝对路径的资源（比如一个sd卡的绝对路径、或者网络上的一个url），而loadRes等只能加载resources目录下的资源。
proto.load = function(resources, progressCallback, completeCallback) {
// 下面这几段代码对输入的参数进行了处理，保证了load函数的各种重载写法能被正确识别
// progressCallback是可选的，可以只传入resources和completeCallback
if (completeCallback === undefined) {
completeCallback = progressCallback;
progressCallback = this.onProgress || null;
}
// 检测是否为单个资源的加载
var self = this;
var singleRes = false;
if (!(resources instanceof Array)) {
singleRes = true;
resources = resources ? [resources] : [];
}
// 将待加载的资源放到_sharedResources数组中
_sharedResources.length = 0;
for (var i = 0; i < resources.length; ++i) {
var resource = resources[i];
// 前向兼容 {id: 'http://example.com/getImageREST?file=a.png', type: 'png'} 这种写法
if (resource && resource.id) {
cc.warnID(4920, resource.id);
if (!resource.uuid && !resource.url) {
resource.url = resource.id;
}
}
// 支持以下格式的写法
// 1. {url: 'http://example.com/getImageREST?file=a.png', type: 'png'}
// 2. 'http://example.com/a.png'
// 3. 'a.png'
var res = getResWithUrl(resource);
if (!res.url && !res.uuid)
continue;
// 如果是已加载过的资源这里会把它取出
var item = this._cache[res.url];
_sharedResources.push(item || res);
}
// 创建一个LoadingItems加载队列，在所有资源加载完成后的下一帧执行完成回调
var queue = LoadingItems.create(this, progressCallback, function (errors, items) {
callInNextTick(function () {
if (completeCallback) {
if (singleRes) {
let id = res.url;
completeCallback.call(self, items.getError(id), items.getContent(id));
}
else {
completeCallback.call(self, errors, items);
}
completeCallback = null;
}
if (CC_EDITOR) {
for (let id in self._cache) {
if (self._cache[id].complete) {
self.removeItem(id);
}
}
}
items.destroy();
});
});
// 初始化队列
LoadingItems.initQueueDeps(queue);
// 真正的启动加载管线
queue.append(_sharedResources);
_sharedResources.length = 0;
};
初始化_sharedResources之后，开始创建一个LoadingItems，将调用queue.append将_sharedResources追加到LoadingItems中。特别需要注意的地方是，我们的加载完成回调，至少会在下一帧才执行，因为这里用了一个callInNextTick包裹了传入的completeCallback。
LoadingItems.create方法主要的职责包含LoadingItems的创建（使用对象池进行复用），绑定onProgress和onComplete回调到queue对象中（创建出来的LoadingItems类实例）。
queue.append完成了资源加载的准备和启动，首先遍历要加载的所有资源（urlList），检查已在队列中的资源对象，如果已经加载完成或者为循环引用对象则当做加载完成处理，否则在该资源的加载队列中添加监听，在资源加载完成后执行self.itemComplete(item.id)。
如果是一个全新的资源，则调用createItem创建这个资源的item，把item放到this.map和accepted数组中。综上，如果我们使用CCLoader去加载一个已加载完成的资源，也会在下一帧才得到回调。
proto.append = function (urlList, owner) {
if (!this.active) {
return [];
}
if (owner && !owner.deps) {
owner.deps = [];
}
this._appending = true;
var accepted = [], i, url, item;
for (i = 0; i < urlList.length; ++i) {
url = urlList[i];
// 已经在另一个LoadingItems队列中了，url对象就是实际的item对象
// 在load方法中，如果已加载或正在加载，会取出_cache[res.url]添加到urlList
if (url.queueId && !this.map[url.id]) {
this.map[url.id] = url;
// 将url添加到owner的deps数组中，以便于检测循环引用
owner && owner.deps.push(url);
// 已加载完成或循环引用（在递归该资源的依赖时，发现了该资源自己的id，owner.id）
if (url.complete || checkCircleReference(owner, url)) {
this.totalCount++;
this.itemComplete(url.id);
continue;
}
// 还未加载完成，需要等待其加载完成
else {
var self = this;
var queue = _queues[url.queueId];
if (queue) {
this.totalCount++;
LoadingItems.registerQueueDep(owner || this._id, url.id);
// 已经在其它队列中加载了，监听那个队列该资源加载完成的事件即可
// 如果加载失败，错误会记录在item.error中
queue.addListener(url.id, function (item) {
self.itemComplete(item.id);
});
}
continue;
}
}
// 队列中的新item，从未加载过
if (isIdValid(url)) {
item = createItem(url, this._id);
var key = item.id;
// 不存在重复的url
if (!this.map[key]) {
this.map[key] = item;
this.totalCount++;
// 将item添加到owner的deps数组中，以便于检测循环引用
owner && owner.deps.push(item);
LoadingItems.registerQueueDep(owner || this._id, key);
accepted.push(item);
}
}
}
this._appending = false;
// 全部完成则手动结束
if (this.completedCount === this.totalCount) {
this.allComplete();
}
else {
// 开始加载本次需要加载的资源（accepted数组）
this._pipeline.flowIn(accepted);
}
return accepted;
};
如果全部资源已经加载完成，则执行this.allComplete，否则调用this._pipeline.flowIn(accepted)，启动由本队列进行加载的部分资源。
基本上所有的资源都会有一个uuid，Creator会为它生成一个json文件，一般都是先加载其json文件，再进一步加载其依赖资源。CCLoader和LoadingItems本身并不处理这些依赖资源的加载，依赖加载是由UuidLoader这个加载器进行加载的。这个设计看上去会导致的一个问题就是加载大部分的资源都会有2个io操作，一个是json文件的加载，一个是raw资源的加载。Creator是如何处理资源的，具体可参考《从编辑器到运行时》一章。
Pipeline的流转
在LoadingItems的append方法中，调用了flowIn启动了Pipeline，传入的accepted数组为新加载的资源——即未加载完成，也不处于加载中的资源。
Pipeline的flowIn方法中获取this._pipes的第一个pipe，遍历所有的item，调用flow传入该pipe来处理每一个item。如果获取不到第一个pipe，则调用flowOut来处理所有的item，直接将item从Pipeline中流出。
默认情况下，CCLoader初始化有3个Pipe，分别是AssetLoader（获取资源的详细信息以便于决定后续使用何种方式处理）、Downloader（处理了iOS、Android、Web等平台以及各种类型资源的下载——即读取文件）、Loader（对已下载的资源进行加载解析处理，使游戏内可以直接使用）。
proto.flowIn = function (items) {
var i, pipe = this._pipes[0], item;
if (pipe) {
// 第一步先Cache所有的item，以防止重复加载相同的item！！！
for (i = 0; i < items.length; i++) {
item = items[i];
this._cache[item.id] = item;
}
for (i = 0; i < items.length; i++) {
item = items[i];
flow(pipe, item);
}
}
else {
for (i = 0; i < items.length; i++) {
this.flowOut(items[i]);
}
}
};
flow方法主要的职责包含检查item处理的状态，如果有异常进行异常处理，调用pipe的handle方法对item进行处理，衔接下一个pipe，如果没有下一个pipe则调用Pipeline.flowOut对item进行流出。
function flow (pipe, item) {
var pipeId = pipe.id;
var itemState = item.states[pipeId];
var next = pipe.next;
var pipeline = pipe.pipeline;
// 出错或已在处理中则不需要进行处理
if (item.error || itemState === ItemState.WORKING || itemState === ItemState.ERROR) {
return;
// 已完成则驱动下一步
} else if (itemState === ItemState.COMPLETE) {
if (next) {
flow(next, item);
}
else {
pipeline.flowOut(item);
}
} else {
// 开始处理
item.states[pipeId] = ItemState.WORKING;
// pipe.handle【可能】是异步的，传入匿名函数在pipe执行完时调用
var result = pipe.handle(item, function (err, result) {
if (err) {
item.error = err;
item.states[pipeId] = ItemState.ERROR;
pipeline.flowOut(item);
}
else {
// result可以为null，这意味着该pipe没有result
if (result) {
item.content = result;
}
item.states[pipeId] = ItemState.COMPLETE;
if (next) {
flow(next, item);
}
else {
pipeline.flowOut(item);
}
}
});
// 如果返回了一个Error类型的result，则要进行记录，修改item状态，并调用flowOut流出item
if (result instanceof Error) {
item.error = result;
item.states[pipeId] = ItemState.ERROR;
pipeline.flowOut(item);
}
// 如果返回了非undefined的结果
else if (result !== undefined) {
// 意为着这个pipe没有result
if (result !== null) {
item.content = result;
}
item.states[pipeId] = ItemState.COMPLETE;
if (next) {
flow(next, item);
}
else {
pipeline.flowOut(item);
}
}
// 其它情况为返回了undefined，这意味着这个pipe是一个异步的pipe，且启动handle的时候没有出现错误，我们传入的回调会被执行，在回调中驱动下一个pipe或结束Pipeline。
}
}
flowOut方法流出资源，如果item在Pipeline处理中出现了错误，会被删除。否则会保存该item到this._cache中，this._cache中是缓存所有已加载资源的容器。最后调用LoadingItems.itemComplete(item)，这个方法会驱动onProgress、onCompleted等方法的执行。
proto.flowOut = function (item) {
if (item.error) {
delete this._cache[item.id];
}
else if (!this._cache[item.id]) {
this._cache[item.id] = item;
}
item.complete = true;
LoadingItems.itemComplete(item);
};
在每一个item加载结束后，都会执行LoadingItems.itemComplete进行收尾。
proto.itemComplete = function (id) {
var item = this.map[id];
if (!item) {
return;
}
// 错误处理
var errorListId = this._errorUrls.indexOf(id);
if (item.error && errorListId === -1) {
this._errorUrls.push(id);
}
else if (!item.error && errorListId !== -1) {
this._errorUrls.splice(errorListId, 1);
}
this.completed[id] = item;
this.completedCount++;
// 遍历_queueDeps，找到所有依赖该资源的queue，将该资源添加到对应queue的completed数组中
LoadingItems.finishDep(item.id);
// 进度回调
if (this.onProgress) {
var dep = _queueDeps[this._id];
this.onProgress(dep ? dep.completed.length : this.completedCount, dep ? dep.deps.length : this.totalCount, item);
}
// 触发该id加载结束的事件，所有依赖该资源的LoadingItems对象会触发该事件
this.invoke(id, item);
// 移除该id的所有监听回调
this.removeAll(id);
// 如果全部加载完成了，会执行allComplete，驱动onComplete回调
if (!this._appending && this.completedCount >= this.totalCount) {
// console.log('===== All Completed ');
this.allComplete();
}
};
AssetLoader
AssetLoader是Pipeline的第一个Pipe，这个Pipe的职责是进行初始化，从cc.AssetLibrary中取出该资源的完整信息，获取该资源的类型，对rawAsset类型进行设置type，方便后面的pipe执行不同的处理，而非rawAsset则执行callback进入下一个Pipe处理。其实AssetLoader在这里的作用看上去并不大，因为基本上所有的资源走到这里都是直接执行回调或返回，从Creator最开始的代码来看，默认只有Downloader和Loader两个Pipe。且我在调试的时候注释了Pipeline初始化AssetLoader的地方，在一个开发到后期的项目中测试发现对资源加载这块毫无影响。
我们调用loadRes加载的资源都会被转为uuid，所以都会通过cc.AssetLibrary.queryAssetInfo查询到对应的信息。然后执行item.type = 'uuid'，对应的raw类型资源，如纹理会在UuidLoader中进行依赖加载的处理，详见Load部分。
var AssetLoader = function (extMap) {
this.id = ID;
this.async = true;
this.pipeline = null;
};
AssetLoader.ID = ID;
var reusedArray = [];
AssetLoader.prototype.handle = function (item, callback) {
var uuid = item.uuid;
if (!uuid) {
return !!item.content ? item.content : null;
}
var self = this;
cc.AssetLibrary.queryAssetInfo(uuid, function (error, url, isRawAsset) {
if (error) {
callback(error);
}
else {
item.url = item.rawUrl = url;
item.isRawAsset = isRawAsset;
if (isRawAsset) {
/* 基本上raw类型的资源也不会走到这个分支，经过各种调试都没有让程序运行到这个分支下，
因为所有的资源在加载的时候都是先获取其uuid进行加载的。而没有uuid的情况基本在这个函数的第一行判断uuid的时候就返回了。
我还尝试了直接用cc.loader.load加载resources的资源，直接传入resources下的文件会报路径错误。
提示的错误类似 http://localhost:7456/loadingBar/image.png 404错误。
正确的路径应该是在res/import/...下的，使用使用cc.url.raw可以获取到正确的路径。
我将一个纹理修改为RAW类型资源进行加载，并使用cc.url.raw进行加载，直接在函数开始的uuid判断这里返回了。
另一个尝试是加载网络中的资源，然而都在函数开始的uuid判断处返回了。
所以这段代码应该是被废弃的，不被维护的代码。*/
var ext = Path.extname(url).toLowerCase();
if (!ext) {
callback(new Error(cc._getError(4931, uuid, url)));
return;
}
ext = ext.substr(1);
var queue = LoadingItems.getQueue(item);
reusedArray[0] = {
queueId: item.queueId,
id: url,
url: url,
type: ext,
error: null,
alias: item,
complete: true
};
if (CC_EDITOR) {
self.pipeline._cache[url] = reusedArray[0];
}
queue.append(reusedArray);
// 传递给特定type的Downloader
item.type = ext;
callback(null, item.content);
}
else {
item.type = 'uuid';
callback(null, item.content);
}
}
});
};
Pipeline.AssetLoader = module.exports = AssetLoader;
