这系列文章会对Cocos Creator的资源加载和管理进行深入的剖析。主要包含以下内容:

  • cc.loader与加载管线
  • Download部分
  • Load部分
  • 额外流程(MD5 Pipe)
  • 从编辑器到运行时
  • 场景切换流程

准备工作

在开始之前我们需要解决这几个问题:

  • 如何阅读代码?
  • 如何调试代码?

框架结构

首先我们从整体上观察CCLoader大致的类结构,这个密密麻麻的图估计没有人会仔细看,所以这里简单介绍一下:

  • 我们的CCLoader继承于Pipeline,CCLoader提供了友好的资源管理接口(加载、获取、释放)以及一些辅助接口(如自动释放、对Pipeline的修改)。
  • Pipeline中主要包含了多个Pipe和多个LoadingItems,这里实现了一个Pipe到Pipe衔接流转的过程,以及Pipe和LoadingItems的管理接口。
  • Pipe有多种子类,每一种Pipe都会对资源进行特定的加工,后面会对每一种Pipe都作详细介绍。
  • LoadingItems为一个加载队列,继承于CallbackInvoker,管理着LoadingItem(注意没有复数),一个LoadingItem就是资源从开始加载到加载完成的上下文。这里说的上下文,指的是与加载该资源相关的变量的集合,比如当前加载的状态、url、依赖哪些资源、以及加载完成后的对象等等。

Cocos Creator 资源加载流程剖析【一】——cc.loader与加载管线-LMLPHP

资源加载

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在后面的章节中会详细介绍)。

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),启动由本队列进行加载的部分资源。

Pipeline的流转

在LoadingItems的append方法中,调用了flowIn启动了Pipeline,传入的accepted数组为新加载的资源——即未加载完成,也不处于加载中的资源。

Pipeline的flowIn方法中获取this._pipes的第一个pipe,遍历所有的item,调用flow传入该pipe来处理每一个item。如果获取不到第一个pipe,则调用flowOut来处理所有的item,直接将item从Pipeline中流出。

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的地方,在一个开发到后期的项目中测试发现对资源加载这块毫无影响。

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;
03-22 18:00