H5 游戏开发 1：Egret 文档有多难用

[kaiye]

来源：猫哥学前班

最近猫哥开始转行做游戏开发，主要的业务场景是 Hybrid H5 休闲游戏。作为游戏行业的新人，自然少不了一些精彩的技术预研和踩坑经历，今天开始挖个“H5 游戏开发系列”的坑，每周分享一下。

技术选型

国内有三大 H5 游戏引擎，Cocos、Egret 和 Laya，他们都能支持使用 TypeScript 编写跨平台（H5、各类小游戏平台、Native App）的游戏。

具体引擎的对比细节不属于本文探讨的主题，我直接抛出（个人）结论：

2D 游戏选 Egret，3D 选 Laya，其他选 Cocos Creator。

上面的“其他”指的是，你一脸懵逼，不知道怎么选的时候：）

Egret 白鹭引擎

Egret 联合创始人马鉴是 Flash （原属 Macromedia 公司，后被 Adobe 收购）团队的第一位中国员工，也是 Adobe 中国第一位 Technology evangelist。

为了能获得最好的游戏性能和开发灵活性，我们当前的这款游戏选用的是 Egret 白鹭引擎。

然而，生活中总是充满着意外和惊喜，从看开发文档到安装 IDE 上手开发调试，Egret 一点都没让人省心。

今天我们来吐槽下 Egret 的文档有多难用，以及我对它的改造方法，希望能启发大家解决技术文档类问题的思路。

1. CDN 资源不稳定

Egret 文档中的图片主要存放在 cdn.dev.egret.com 域名，而这个服务器经常不可用，同时 cdn.www.egret.com 域名也经常连接超时。怎么办？

借助两条 Whistle 配置搞定：

# 将 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

补充：如果你还不知道 Whistle，可以看下猫哥以前的文章：《8102 年的程序员不需要 Hosts 和 Fiddler》、《使用 Whistle 作为 API 服务网关》

2. 文档打不开

很难想象作为一个小有名气的游戏引擎厂商， Egret 的文档站点能做到如此的不靠谱：中文文档站点经常无法访问，所有页面重定向到首页；文档搜索功能不可用，搜索结果直接跳转报错页。

虽然 Egret 还提供了英文文档站点（将 URL 上的 cn 改为 en 即可），但其缺乏及时更新，且无法解决文档搜索问题。

中文 Hello World 地址：http://developer.egret.com/cn/github/egret-docs/Engine2D/getStarted/helloWorld/index.html

英文 Hello World 地址：http://developer.egret.com/en/github/egret-docs/Engine2D/getStarted/helloWorld/index.html

好在 Egret 文档是基于其 Github 仓库 egret-labs/egret-docs 生成的，所以我们可以直接将其下载至本地，使用 VSCode 进行预览和搜索，或者使用 Chrome Sourcegraph 扩展来在线预览和搜索文档。

如上图所示，为 Sourcegraph 的过滤搜索功能。

3. API 文档搜索功能太弱

Egret API 文档 反人性的地方在于，它只提供了按照 Class 类名的搜索功能，这对初学者相当的不友好。

初学者通常是只知道某些属性或方法名，或它们的描述关键词，然后想通过 API 文档来搜索出具体的类名和使用方法。

由于它的 API 文档没有开源在 Github 上，所以猫哥只好基于它的文档站点设计了一个 API 搜索增强脚本。

如上图红框所示，使用该增强脚本后，将支持 Egret API 文档的全文搜索。脚本具体实现思路如下：

使用 AJAX 将所有 API 文档内容缓存至本地 indexedDB 数据库（不使用 localStorage 是因为数据大小可能会超过其容量上限），再使用正则匹配用户输入的关键词，过滤出包含内容的 Class 列表，最后复用原先的搜索交互。

脚本的注入方式，仍然推荐使用 Whistle，只需加入两条配置：

# 在 API 站点中插入一个 JS script（若脚本更新需注意替换 url） 
/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

注：请从 gist 上获取最新脚本源码，并注意替换以上配置中 raw 文件的路径https://gist.github.com/kaiye/207728f7c9f187cd886353e7678197f4

完成注入后，首次使用时，点击“Preload Docs into Local Cache” 按钮，浏览器会依次发出 200 多条 API 文档内容的请求，并将其缓存至本地。后续无需重新下载，即可直接搜索使用。

以上是猫哥对 Egret 文档站点改造的全部内容，在下一期我将会介绍实际的游戏开发，看看 Egret 的 IDE 和调试工具有多难用，感谢关注：）