H5 游戏开发 2：搭建 Egret 开发环境

猫哥学前班

发布于 2020-02-11 17:58:50

4.8K1

发布于 2020-02-11 17:58:50

文章被收录于专栏：猫哥学前班猫哥学前班

在上一期的“H5 游戏开发”教程中，猫哥介绍了如何通过 Whistle 工具对 Egret 文档进行资源修复和搜索增强。本期，我们以 Hello World 项目为例，看看如何搭建一个好用的 Egret 项目开发环境。

1. 使用 Egret Launcher 创建项目

游戏开发是一个复杂的工程，它涉及到代码、UI 界面和动效三者的结合。Egret 官方为开发者和设计师提供了丰富的系列工具产品，帮助提升游戏开发体验和效率。

我们可以通过 Egret 官网下载最新版 Egret Engine Launcher 客户端，再通过 Launcher 来安装 Egret 引擎和工具链。

Egret Launcher

DragonBones：用于编辑龙骨动画（类似 Flash 的关键帧补间动画）
Egret Feather：粒子效果编辑器
Res Depot：资源管理器，用于对游戏资源进行定义、分组，编辑九宫格图片
Texture Merger：图集打包工具，可生成关键帧动画资源（Movie Clip）、图集（Sprite Sheet）、位图字体（Bitmap Font）
Egret Inspector：Egret Chrome 扩展工具，用于开发调试
Egret Wing：Egret IDE

除此之外，Launcher 还提供了 GUI 界面的项目创建和发布功能。

你可以先通过 Egret Launcher 安装一个最新稳定版的 Engines，然后参考官方文档或自行摸索，创建一个 HelloWorld 项目，并使用 Egret Wing 将其打开。

2. 使用 VSCode 代替 Egret Wing

打开 Egret Wing 后，你会发现它的界面和 VSCode 十分相似，事实上 Wing 是在 VSCode 基础之上定制而来。除了 VSCode 的代码编辑功能以外，Wing 还默认集成了游戏预览和发布的快捷工具栏，以及简化版的 Res Depot 资源管理功能。

然而，由于 Egret 团队当前的工作重心在于集美术场景界面编辑和程序开发为一体的 Egret Pro IDE 上（类似 Cocos Creator），所以 Egret Wing（以及即将废弃的 Egret UI Editor）已经相当长时间未得到更新。

这里，我们可以直接使用 VSCode 来代替 Egret Wing 作为游戏开发的 IDE，以便提升开发体验。

2.1 命令行自动编译

使用 VSCode 打开项目目录后，借助 Egret 命令行我们可以方便的实现项目的自动编译。打开 VSCode Terminal 面板（快捷键 Ctrl `），运行以下命令，可以在本地启动一个 Egret HTTP Server 服务：

egret run -a

其中，a 参数代表监听到文件变化后自动编译 autoCompile。服务启动后，会自动使用浏览器打开项目的局域网 IP 预览地址（你也可以选择使用本地 IP http://127.0.0.1:3000/index.html 来访问）。

补充：使用 port 参数能改变项目的监听端口（默认为 3000），使用serverOnly 参数能禁用打开 Chrome 浏览器的默认行为。如：

egret run -a -port 3333 -serverOnly

2.2 VSCode Chrome Debugger

在 Chrome 浏览器中，虽然我们可以直接通过 Sources 面板来对 JS 文件进行断点调试，但实际上使用 VSCode 的 Debug 面板，体验会更好。

首先，我们在 VSCode 中安装一个 Debugger for Chrome 扩展。安装完成后，运行 Start Debugging（快捷键 F5），VSCode 会在项目根目录的 .vscode 目录中自动创建一个 launch.json 配置文件。其默认内容如下

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "chrome",
            "request": "launch",
            "name": "Launch Chrome against localhost",
            "url": "http://localhost:8080",
            "webRoot": "${workspaceFolder}"
        }
    ]
}

我们只需要将上面的 url 属性值替换成 2.1 中提到的本地预览地址 http://127.0.0.1:3000/index.html 即可。

Egret 和大部分的 H5 游戏引擎类似，默认使用 TypeScript，所以我们还需要确保项目生成了 SourceMap，能将浏览器中运行的 JavaScript 和编辑器中的 TypeScript 关联起来。

所以，我们需要修改项目根目录的 tsconfig.json 文件，在 CompilerOptions 中加入 SourceMap 的配置。

示例如下：

{
    "compilerOptions": {
    
        "target": "es5",
        "outDir": "bin-debug",
        "experimentalDecorators": true,
        "lib": [
            "es5",
            "dom",
            "es2015.promise"
        ],
        "types": [],
        "sourceMap": true
    },
    "include": [
        "src",
        "libs"
    ]
}

注：修改了 tsconfig.json 文件后，本地的 Egret HTTP Server 服务会自动终止，需要重新执行 egret run -a 来启动。

VSCode Debugging

最终，如上图所示，我们实现了 Egret 项目的 VSCode Debugging 功能，它比 Egret Wing 的体验更好。

在实际的游戏开发过程中，Debugging 断点调试用的不多。更多时候，我们需要确认游戏 UI 元素的层级和布局渲染是否正确。这就需要用到 Egret Inspecter Chrome 扩展。

3. Egret Inspector Chrome 扩展

由于 H5 游戏界面都是渲染在 Canvas 画布中，因此仅使用 Chrome DevTools 默认的 Elements Inspect 功能只能看到一个孤零零的 Canvas 节点，而无法看到所有 UI 层级细节。

Egret 官方提供了一个 Chrome 扩展，安装完成后，我们能通过 Chrome DevTools Egret 面板查看到具体的元素层级和布局信息。

3.1 安装 Egret Inspector

我们只能使用 Chrome 开发者模式手动安装 Egret Inspector 扩展：

使用 Egret Launcher 下载 Egret Inspector 插件，下载完成后打开目录；
将插件 zip 包解压缩，选中名字为 EgretInspector-install 的子目录；
打开 Chrome 浏览器的扩展程序管理界面，将右上角的“开发者模式“开关打开；
将 EgretInspector-install 目录拖入至 Chrome 浏览器，完成安装。

Egret Inspector

最终效果如上图所示。在使用时，需要注意两个问题：

Egret 虚拟画布节点通常不会自动刷新，需要手动点击“选中点击对象”后的刷新按钮来强制刷新；
控制台偶尔会报错 Uncaught TypeError: this.addChild is not a function 。

这是 Egret Inspector 插件的一个 Bug。插件依赖页面中的 Egret 引擎，当它在加载时，游戏页面中的 Egret 引擎可能还未完全加载，所以调用 this.addChild 方法导致报错。

3.2 解决 this.addChild is not a function 报错

前文提到过 Egret 官方团队工作重心已放在新架构的设计上，很多引擎和工具链上的问题，需要开发者自己动手解决。好在 Egret 源码开放，问题分析和解决起来并不复杂。

我们找到上文提到的 EgretInspector-install 目录中的 contentScripts.min.js 文件，将压缩后的代码进行格式化还原。再将还原后的 313 - 320 行代码进行替换，原代码：

        if (EGRETRELEASE) {
          n = ["injectScripts.min.js"];
        }
        e.addScript(n);
        window.setTimeout(function() {
          t.startInspectIfDevToolOpen();
        }, 200);

替换后代码：

        if (EGRETRELEASE) {
          n = ["injectScripts.min.js"];
        }
        
        window.setTimeout(function() {
          e.addScript(n);
          t.startInspectIfDevToolOpen();
        }, 500);

接下来，我们通过 Chrome 扩展程序管理界面将该插件重新加载更新、关闭/开启，以确保修改已经生效。

最后，我们重新关闭/打开 Chrome DevTools Egret 面板，问题得到修复。

4. Egret Live Reload 配置

在进行 Web 项目开发时，很多时候我们需要一边编写代码，一边刷新预览页面的呈现效果，H5 游戏开发也不例外。借助 Whistle Live Reload 插件，我们能很容易的实现这个功能。

4.1 安装 Whistle & Live Reload

# 全局安装 whistle 及其 live reload 插件
npm i -g whistle whistle.livereload
# 启动 whistle 服务
w2 restart

服务启动后，我们可以使用以下任意一种方式，将浏览器代理设置为 Whistle 服务地址 127.0.0.1:8899

使用 Chrome SwitchyOmega 插件设置浏览器代理；
使用 Proxifier 配置指定应用程序的代理服务；
直接修改系统代理服务为 127.0.0.1:8899

（注：如果你不知道如何使用 Whistle，请参考 Whistle 官网或 “猫哥学前班” 网络编程系列相关教程。）

4.2 添加 .whistle.js 配置

代理配置成功后，我们在游戏项目根目录新建 .whistle.js 文件，其内容如下：

（注：本配置中包含了 Egret 文档增强功能，具体参看“H5 游戏开发”教程 1）

const currentPath = __dirname
const projectName = currentPath.split('/').pop()

exports.name = `[${projectName}]本地环境配置`
exports.rules = `
http://game.local http://127.0.0.1:3000 whistle.livereload://${currentPath}/bin-debug/

# 将 CDN 地址转发至源服务器目标地址
http://cdn.dev.egret.com/ http://developer.egret.com/cn/data/upload/

# 将经常连接超时的素材直接返回 404
https://cdn.www.egret.com/official/new-egret/img/ statusCode://404

# 在 API 站点中插入一个 JS script（若脚本更新需注意替换 url）
192.30.253.118 gist.github.com
/developer\\.egret\\.com\\/\\w+\\/apidoc\\/(?!ajaxcontent)/ jsAppend://https://gist.githubusercontent.com/kaiye/207728f7c9f187cd886353e7678197f4/raw/09e543a735da2a7212e22d967f2ce40eb2d63b8c/injectEgretApiDoc.js
# 将 gist 站点上该脚本的 content-type 设置为 javascript，解决类型嗅探错误
/injectEgretApiDoc\\.js/ resType://js
`

我们运行 w2 add 命令后，将会在 Whistle Rules 面板中添加一组规则。打开 http://127.0.0.1:8899/#rules 配置后台，可查看具体的配置细节。

在这份配置中，我将 127.0.0.1:3000 默认绑定到了 game.local 域名，以解决局域网 IP 变动后需要变更 IP 配置的问题，因此你可以通过 http://game.local/index.html 来预览游戏界面。

你可以通过 Whistle Rules 自定义这个域名，或者直接将其删除，使用默认的局域网 IP 端口访问方式。

你需要注意以下技术细节：

受操作系统限制，localhost 和 127.0.0.1 本地 IP 无法被 Whistle 和其他代理服务抓包，所以只能使用域名或者局域网 IP；
由于 Live Reload 使用了 WebSocket 来实现监听通知，因此需要确保勾选了 Whistle HTTPS 菜单项中的 “Capture TUNNEL CONNECTs” 选项，以实现 TLS 通道抓包；
勾选以上选项，还需要正确安装 Whistle CA 证书，确保其他 HTTPS 网站能正常访问。

以上配置完成后，当你在 VSCode 中修改游戏代码时，egret run -a 进程会实时监听项目文件的变化，自动编译新的代码到项目的 bin-debug 目录。此时，Whistle Live Reload 进程正在实时监听 bin-debug 目录的变化，在收到变化通知后，通过 WebSocket 通知浏览器页面进行自动刷新，从而实现我们所需的开发体验。

以上是搭建 Egret 开发环境的全部内容。在下一期，猫哥将会介绍 H5 游戏引擎的技术实现原理，希望对大家理解游戏开发有所帮助，感谢关注：）

本文参与腾讯云自媒体分享计划，分享自微信公众号。

原始发表：2020-01-01，如有侵权请联系 cloudcommunity@tencent.com 删除

ide