Egret全新RES模块详解

近期Egret发布了全新的4.0版本，此次版本中最大的特色就是释放了全新的RES资源管理模块。相信不少人在官网或者直播中已经对新的RES资源管理模块有所了解。这篇文章就全新的RES进行一次介绍。与此同时，在引擎新版本中，由于引入了TypeScript 2.1.4，所以在语法糖层面也增加不少特性，我后续会在其他文章中逐步介绍。

首先来简单说面一下这次RES模块升级后的特点。相对于旧版本，变化如下：

借助新的ES规范，API使用发生明显变化
资源配置文件格式改变，减小体积的同时，增加了热更新机制。
新版本RES采用单独运行方式，和旧版本可以保持很好的共存。当然，在你的项目中你只能选择使用其中一种。
旧版本中的自定义格式解析器被废除，取而代之的是新的格式解析扩展方法。

开发者在刚刚接触新版本时，由于语法糖变化，可能会带来暂时的不习惯，当你熟悉这部分语法后，使用起来效率会比以前高很多。为了兼容旧版本，在新版本中你也可以使用旧版本的API调用方式，但不同的是，一部分API的参数和行为会发生少许变化，这对于就项目迁移尤为需要注意。

安装

新的RES模块并没有放置于引擎之中，很多人更新Egret引擎后不知道新版RES所处位置。这里需要对安装方法做一个简单介绍。

如果你想查看源码，可以访问我们的git仓，直接clone相关代码即可，git仓地址：https://github.com/egret-labs/resourcemanager

当你想使用新版本的RES模块时，你需要借助npm来记性安装，安装命令如下：

npm install egret-resource-manager -g

在这行命令中，添加 -g 参数，我们希望你能够以全局方式进行安装，保证在不同系统账户下都可以使用RES命令。

安装完成后，你即可使用新版本RES模块，但对于要使用的项目需要进行进一步操作。

将项目切换为全新的RES模块

进入到你的项目中，为了实验对比，我们新建两个项目，一名明明为old，另外一个命名为new 。然后进入到new目录下，执行如下命令：

res upgrade

如果命令执行完成后，并没有报错，即证明新版本RES切换成功。

对比新旧两个项目，我们来看一下发生了哪些变化：

新项目中，在bin目录下，新增了一个名为resourcemanager的文件夹，该文件夹存放全新RES模块代码。这个文件夹中的代码文件共有4个，四个文件也就是git仓中bin目录下的4个文件。
在egretProperties.json文件中，原有modules节点中的res节点被删除，取而代之的是名为resourcemanager的模块配置。

除了以上两点，你还需要自己修改一下tsconfig.json文件。因为全新的RES模块依赖于ES2015标准中的Promise对象，所以在编译器编译阶段，我们需要在这里添加对Promise对象的编译支持。修改后内容如下：

{
   "compilerOptions": {
      "target": "es5",
      "experimentalDecorators":true,
      "lib": [
          "es5","dom","es2015.promise"
      ]
   },
   "exclude": [
      "node_modules"
   ]
}

以上工作都完成后，我们即可使用全新的RES模块来编写代码。

RES模块代码编写第一步

在使用旧版本时候，我们所有的资源都依赖于一个名为default.res.json的资源配置文件，该文件记录这资源的相对路径和配置name属性名称。那么新版本的资源配置文件如何生成？这里需要使用RES命令的另外一个操作，build资源。进入到项目目录上一层，然后执行如下命令：

res build 你的项目名称

这里的项目名称和你的文件夹名称相同，如果没有发生任何报错，那么你在打开项目中的resource目录，会发现其中多了一个名称为config.json的文件。该文件就是新版RES模块的配置文件。我们可以来对比一下两个配置文件的不同。

旧版本

{
	"groups":[
	{
		"keys":"bg_jpg,egret_icon_png,description_json",
		"name":"preload"
	}],
	"resources":[
	{
		"name":"bg_jpg",
		"type":"image",
		"url":"assets/bg.jpg"
	},
	{
		"name":"egret_icon_png",
		"type":"image",
		"url":"assets/egret_icon.png"
	},
	{
		"name":"description_json",
		"type":"json",
		"url":"config/description.json"
	}]
}

新版本

{
	"alias": {
		"bg_jpg": "assets/bg.jpg",
		"egret_icon_png": "assets/egret_icon.png",
		"description_json": "config/description.json"
	},
	"groups": {
		"preload": [
			"bg_jpg",
			"egret_icon_png",
			"description_json"
		]
	},
	"resources": {
		"default.res.json": "default.res.json",
		"assets": {
			"bg.jpg": "assets/bg.jpg",
			"egret_icon.png": "assets/egret_icon.png"
		},
		"config": {
			"description.json": "config/description.json"
		},
		"config.json": "config.json"
	}
}

两个配置文件格式存在明显区别，在新版本中，我们取消了资源的name属性，取而代之的是直接使用资源的路径作为资源获取时所传入的参数。这样就避免了开发过程中资源匹配识别错误而引发的一系列麻烦。

与此同时，该格式也有助于我们后面的资源热更新解决方案，关于热更新我们后面会有所介绍。

这里需要注意一点，当你对资源进行修改后，每一次修改都需要执行res build命令，以便生成新的资源配置文件。

编写资源加载代码

由于TypeScript编译器的升级，我们现在可以编写ES6标准代码，也可以编写ES2015标注代码。下面我们来一一介绍。至于两种标注，该如何选取，取决于你对标准的熟悉程度和习惯。

旧版本的RES模块

旧版本中，资源操作中的所有事件回调，全部依赖于Egret内部所提供的事件模型。换句话说，当你在非Egret引擎下，旧版RES模块就无法使用，代码编写风格如下：

//首先根据我们的需要注册事件侦听器，一遍当状态放生变化时，回调我们指定的函数。
RES.addEventListener(RES.ResourceEvent.CONFIG_COMPLETE, this.onConfigComplete, this);
//执行加载动作
RES.RES.loadConfig("resource/default.res.json", "resource/");

//当配置文件加载完成后，调用onConfigComplete方法
private onConfigComplete(event: RES.ResourceEvent): void {
    ...
}

上面一段代码是我们旧版本中编写一处资源加载的代码，由于大家比较熟悉，不再赘述。

ES6下的RES模块

ES6标准中，同样实现上面功能，我们可以使用Promise对象的标准异步语法，同时借助箭头函数来完成相关回调函数的定义。

RES.loadConfig().then(()=>{
	console.log("config file load complete!");
})

上面一段代码中，loadConfig方法返回一个Promise对象，该对象拥有一个then函数。当事件完成后，则回调then函数参数中的函数。

如果你想捕获资源加载失败的事件，则调用Promise对象的catch函数即可，代码如下：

RES.LoadConfig.then(()=>{
	console.log("config file load complete!");
}).catch((err)=>{
	console.log(err);
});

catch中的回调函数，可接受一个error参数，参数中是错误类型和错误信息。

ES2015下的RES

从刚才的讲解中，我们可以看到相比旧版本的API，借助ES6的语法特性，我们的代码更加简洁，并且了原有的事件帧听过程。但函数回调所带来的不仅仅是代码简约，同时也让代码看上去极为丑陋。使用ES2015中的await关键词，可极大的解决这方面的问题，但你需要注意的时，异步阻塞过程并非你想的如此简单，一些时候你可能会被自己坑掉。

解决函数回调最好的形式是让回调函数能够像正常函数调用一样，代码看上去是顺序执行。也就是完成第一行执行后，再执行第二行。而对于网络加载来说，我们的资源需要等待一段时间才能够正常使用，这个过程中，我们希望游戏的其他逻辑还能够正常执行。为了解决这个问题，你需要在使用await的同时，一并使用async异步操作。

我们来看下面一段代码：

RES.loadConfig();
RES.getResAsync("images/logo.jpg");

这段代码执行后会发生报错，简单原因在于,当第一行执行后，会立刻执行第二行语句。而此时我们的资源配置文件并没有加载完成。虽然传递了参数，但无法找到对应的资源。所以会发生报错。那么如果让代码在执行完第一行后，等待加载结束再执行第二行呢？答案是使用await阻塞。

修改代码如下：

await RES.loadConfig();
await getResAsync("images/logo.jpg");

这样修改后，我们的就可以实现想要的效果。你需要注意的是，await仅对Promise对象有效。

如果你将这样的代码放到游戏业务逻辑之中，依然存在恼人的Bug。因为此时不仅网络加载操作被阻塞，你的其他逻辑也会被阻塞。此时如果你想做其他操作，就必须等待loadConfig加载完成。这个又不是我们想要的效果。那么再次修改代码如下：

private asyn loadRes() {
	await RES.loadConfig();
	await RES.getResAsync("images/logo.jpg);
}

我们将浙西阻塞代码全部放到一个异步函数中，从而解决刚才的问题。async关键词必须在访问权限修饰词之后。在调用时，使用方法如下：

this.loadRes();
this.runGame();

通过这种调用，我们在开始加载资源后，可以立刻执行runGame方法。

如果你需要捕获加载错误信息，可以使用try...catch方法，代码如下：

try{
	this.loadRes();
	this.runGame();
}catch(err){
	console.log( err );
}

加载进度问题

游戏资源加载过程中，通常都会存在一个loading进度条，或者能够表示加载进度的展示方法。在新的RES模块中，读取加载进度也非常的方便。在RES模块中，新增了一个名为PromiseTaskReporter的接口，借助这个接口，我们可以实现读取加载进度的效果。

PromiseTaskReporter接口包含两个方法，你可以选择实现。

onProgress：该方法类似于以前的GROUP_PROGRESS事件，用于读取加载进度。
onCancel：取消

使用时，你可以创建一个对象或者一个类，来实现PromiseTaskReporter接口，并在loadGroup加载组时，将其实例化对象作为参数传递进去。实例代码如下：

private async loadRes()
{
	await RES.loadConfig();

	let loading:RES.PromiseTaskReporter = {
		onProgress(current: number, total: number){
			console.log(current+"/"+total)
		}
	};
	await RES.loadGroup("preload",0,loading);
	this.createGameScene();
}

运行项目，你可以在控制台看到打印如下内容：

1/4
2/4
3/4
4/4

资源获取方法

由于新版的RES模块和旧版本保持较好的向前兼容性，所以在资源获取方面没有太大变化。在一些特定API下，由于资源格式定义规则发生变化，所以行为也会有少许变化。其中包含两个API存在功能类似问题，但你可以在不同场景中使用不同的API。

getResAsync：你可以直接使用该方法获取远程服务器资源，参数为资源相对路径。
getResByUrl：你可以根据资源相对路径获取服务器资源，但推荐在方位不同域资源时使用此方法。

你以前熟悉且常用的getRes等方法，他们的行为保持不变。

自定义格式解析器

当你用res命令升级项目后，会发现在Main.ts文件的class定义前多出一段代码，内容如下：

@RES.mapConfig("config.json",()=>"resource",path => {
    var ext = path.substr(path.lastIndexOf(".") + 1);
    var typeMap = {
        "jpg": "image",
        "png": "image",
        "webp": "image",
        "json": "json",
        "fnt": "font",
        "pvr": "pvr",
        "mp3": "sound"
    }
    var type = typeMap[ext];
    if (type == "json") {
        if (path.indexOf("sheet") >= 0) {
            type = "sheet";
        } else if (path.indexOf("movieclip") >= 0) {
            type = "movieclip";
        };
    }
    return type;
})

这是TypeScript中的注解语法，借助这段语法，我们可以在res build命令时配置需要的资源格式，并且在运行时，根据后缀名来判断资源类型。

如果你将这段代码中typeMap变量进行修改，例如删除jpg一行，那么资源中所有后缀名为jpg的资源都不会被放入到配置文件中。

了解以上内容，如果你要为自己的格式制作解析器，需要关注三个接口，分别是：

RES.processor.Processor
RES.ProcessHost
RES.ResourceInfo

我们来看一下具体添加一个解析器方法，我们添加一种后缀名为jsn的文件，该类型文件实际上就是json格式文件，为了方便讲解，我们不在自定义一个格式，大家可以举一反三。

第一步

我们复制description.json文件，并将其名称改为d.jsn，放置于同目录下。

第二步

创建一个新的类，名称为JsonAnalyzer的对象，并实现RES.processor.Processor接口。

代码如下：

let JsonAnalyzer: RES.processor.Processor = {
	async onLoadStart(host, resource) {
		let data = await host.load(resource, RES.processor.JsonProcessor);
		return data;
	},

	onRemoveStart(host, request) {
		return Promise.resolve();
	}
}

第三步

我们需要将新的解释器注入到RES模块中，并且修改开始的注解函数。

注入RES模块方法如下：

RES.processor.map("myjson", JsonAnalyzer);

我将这个格式内部名称定义为myjson，注解函数代码如下：

@RES.mapConfig("config.json", () => "resource", path => {
    var ext = path.substr(path.lastIndexOf(".") + 1);
    var typeMap = {
        "jpg": "image",
        "png": "image",
        "webp": "image",
        "json": "json",
        "fnt": "font",
        "pvr": "pvr",
        "mp3": "sound",
        "font": "fft",
        "jsn": "myjson"
    }
    var type = typeMap[ext];
    if (type == "json") {
        if (path.indexOf("sheet") >= 0) {
            type = "sheet";
        } else if (path.indexOf("movieclip") >= 0) {
            type = "movieclip";
        };
    }
    return type;
})

再一次执行res build，然后编写测试代码，看能否打印出你要的内容。

console.log(RES.getResAsync("config/d.jsn"));

关于新的RES模块的介绍就到这里！

enjoy!