vivo小游戏Unity/团结快适配

Appearance

代码(wasm)分包工具 ​

背景 ​

unity 导出小游戏项目后，代码是在一个 wasm 文件里，放在 unitySubPkg 目录下，vivo平台下其 wasm 对应的文件名为webgl.wasm.code.unityweb；

一般小游戏的 wasm 大小都为 30M 左右，压缩后为 6M 左右；

启动阶段，小游戏需要先下载完 wasmcode 再编译，这里会占用较高的内存和时间；

因此我们提供了代码分包工具，将原来的 wasm 拆分为两个，一个用于启动加载（主包），另一个可以延迟加载（子包）；

使得小游戏可以先加载较小的首包进入主场景，再异步加载剩下的分包。

作用 ​

分包的作用在于：

  • 优化启动时间；
  • 减少内存使用；
  • 减少编译时间，降低了游戏前期的发烫情况。

使用要求 ​

1.以下为必要条件 ​

  • unity引擎支持2021版本及以上，2019版本待支持；
  • 安装分包工具，脚手架qg-wasmsplit
bash
npm i -g @buhuo/qg-wasmsplit-ci

2.导出小游戏 ​

注意点1："首包资源加载方式"必须选择 -> "vivo分包" 方式导出小游戏，否则无法正常开启后续分包流程。

注意点2：对于首次接入的新游，建议最小平台版本号填写1206，效果更佳。

alt text

分包工具说明 ​

vivo小游戏wasm分包工具提供两种模式：

  • 图形化界面模式：启动浏览器窗口，全程可视化拆分（强烈推荐👍）；
  • CLI 模式：全程支持使用命令行拆分。

图形化界面模式分包使用流程 ​

1.初始界面 ​

  • openpanel 打开分包可视化面板

本地启动一个工作面板，用于进行可视化进行wasm分包流程

bash
Usage: qg-wasmsplit openpanel [options]
open panel ui
Options:  -p, --project-path <projectPath>         
      project path, 小游戏项目路径, 必填
  -d, --version-description <versionDescription>  
      version description, 版本描述
  -r, --refer-md5 <originalMd5>                   
      original code md5, 历史代码包md5
  -h, --help                               
      display help for command
  • 示例
bash
qg-wasmsplit openpanel -p /Users/../test/webgl_vivo  -d \"v1.0.0\"" --release
  • 输入项说明
    • -p:必填，小游戏项目路径（一般指的就是unity导出的文件路径下的webgl_vivo目录）；
    • -d:必填，版本描述（针对此次分包版本的描述）；
    • -r:可选，具体见下文增量分包小节说明，可在分包面板中手动选择；
    • --release:可选，添加该参数表示对release包进行分包，否则为debug包。

当首次进行wasm分包时，或者选择的WebGL包文件中的wasm代码发生变化，则会打开工具界面如下：

alt text

2.启动代码分包 ​

在初始界面上有一个【启用代码分包】按钮，点击该按钮，会将WebGL构建产物上传到服务器端，服务器端会对Wasm文件进行预处理： 请注意，这个【启用代码分包】并不是做wasm分包，只是为wasm分包前函数收集做准备，你需要收集一些函数后，再点击后续步骤中的【收集完成，开始分包】，才是最终的wasm分包。

a.上传分包以及预处理： ​

此步耗时将需要数分钟，一般为3-5分钟，如果超过10分钟处于此状态，请重启开发者工具。

alt text

b.预处理完成 ​

服务端预处理完成代码之后，将跳转到以下界面。

alt text

界面将包含以下信息：

【小游戏项目路径】：此次分包所选中的文件

【函数收集信息】：

  • 当前首包函数个数：表示当前正在运行过程中，所收集到函数个数。这个数值会在游戏运行过程中变化，当这个数值长时间未发生变化并大于0时，可以认为函数收集完成，可以点击【收集完成，开始分包】进行Wasm分包；
  • 历史首包函数个数：已经分好的Wasm首包中的函数个数；
  • 新增函数个数：当前首包函数对比历史首包函数，出现新增的函数个数，一般多次分包或增量分包时关注；
  • 总函数个数：原始Wasm文件中的函数总个数。

【加载预览，开始收集函数】：

点击此按钮将在页面上显示一个预览二维码，可通过真机扫描预览，进行函数收集。

3.预览收集 ​

点击【加载预览，开始收集函数】,将会自动执行预览操作，预览成功后显示二维码

  • 显示预览二维码

此时可使用手机扫码预览运行游戏，在运行期间将会观察到新增函数个数增加。

注：需要确保扫码的手机同当前分包服务处于同一局域网。

alt text

  • 扫码收集

使用调试器扫码预览进行函数收集，请尽可能的覆盖新手教学以及最初的关卡内容，防止玩家进入游戏，在启动游戏过程中便触发了子包函数加载，而产生负向的效果。

调试器真机扫码效果
alt textalt text

尽量在真机上覆盖更多的场景，尽量将子包的加载延后，将很大程度提升游戏体验。

收集到函数，新增函数数值有变化。

alt text

  • 【收集完成，开始分包】：当认为Wasm函数收集完成，即可以点击该按钮向服务器端请求Wasm分包。

4.完成分包 ​

点击【收集完成，开始分包】，服务器将对代码进行处理，将wasm代码分为首包和子包。

alt text

a.分包中

此过程耗时较长，一般为7-8分钟，（有可能需要等待超过10分钟），如果长时间处于此状态，请重启开发者工具 alt text

b.分包完成

当前首包函数个数将变化，同时出现下载分包文件按钮，点击【下载分包文件】按钮，将会获得完整的可用于发布的文件。

5.下载分包 ​

点击【下载分包文件】按钮

alt text

下载成功后，脚本会自动打包rpk，即为最终的rpk。也可进入当前项目路径下，按需手动运行 npm run build/nom run release重新打包。

6.继续分包 ​

另外开发者可以通过再次点击【加载预览，继续收集函数】，继续收集函数，此操作可重复进行，直到新增函数不再增加，即可认为分包已经完成，点击开始分包之后，再下载分包文件用于后续的发布即可。

7.关闭分包 ​

如果想回退到未分包的版本，点击关闭代码分包即可。

注意 ​

以上收集过程中需要关注首包函数个数，一般首包函数占整包函数个数的30%以上，太少的话可能会在用户进行游戏后触发子包加载，带来更差的体验!!!

建议覆盖更多的首场景，开发可以通过再次点击【加载预览，继续收集函数】多次重复进行，直到新增函数不再增加。

增量分包说明 ​

如游戏先前版本已实施代码分包，且本次更新不涉及大规模重构、引擎更换等重大结构调整，则推荐采用增量分包模式。

该模式支持选定历史包作为基准，复用已采集的函数模块至首包，避免重复性全量检测，使函数收集范围精准聚焦于新增或修改的逻辑部分。

点击增量分包下拉列表可以显示分包历史列表，列表中会显示收集到的函数数量，md5，版本号，分包时间信息。

alt text

其他功能 ​

1.跨渠道复用 ​

alt text

支持基于微信等友商的wasm代码分包收集到函数txt文件，直接选择txt文件并上传。

2.获取首包和新增函数的函数名 ​

alt text

当收集到新增函数或者首包函数大于0时，点击此按钮将会向服务端获取函数信息，获取完成后，函数信息将在如下位置显示。

仅支持获取最新一次分包的首包函数以及新增函数。

net_monitor

CLI模式分包使用流程 ​

init 开启分包&函数收集 ​

bash
Usage: qg-wasmsplit init [options]
init miniprogram
Options:
  -p, --project-path <projectPath>                
      project path, 小游戏项目的路径, 必填
  -d, --version-description <versionDescription>  
      version description, 版本描述
  -r, --refer-md5 <originalMd5>                   
      original code md5, 历史代码包md5
  -h, --help                                      
      display help for command

流水线每次执行都需调用init命令进行初始化操作，如果本次流水线需要增量更新，则需传入供增量参考的游戏包的md5；

增量更新必须在项目首次分包时使用。

  • 示例
bash
# 首次分包，需要增量分包
qg-wasmsplit init -p ./webgl_vivo/ -d "v1.0.0" -r $REFER_MD5
# 非首次分包，或者首次但不需要增量分包
qg-wasmsplit init -p ./webgl_vivo/ -d "v1.0.0"
  • 效果如下

分包服务器开启成功后，命令行中出现以下二维码，使用vivo小游戏调试器扫码进行真机函数收集，函数实时同步到命令行中，收集完成后，直接按下 Ctrl+C 可停止面板服务，完成函数上传。

alt text

上传成功后，执行分包命令，如上图命令行中提示的qg-wasmsplit dosplit xxx，即可完成分包。

dosplit 生成分包 ​

bash
Usage: qg-wasmsplit dosplit [options]
split minigame package
Options:  -p, --project-path <projectPath>         
      project path, 小游戏项目路径, 必填
  --release                                
      release, otherwise profile, 是否release分包
  -h, --help                               
      display help for command

完成函数收集后，执行当前命令进行分包，命令执行成功后会下载分包结果，并完成打包rpk，执行失败可重复执行。

  • 示例
bash
qg-wasmsplit dosplit -p ./webgl_vivo/
#release
qg-wasmsplit dosplit -p ./webgl_vivo/ --release

disable 关闭代码分包 ​

bash
qg-wasmsplit disable -p ./webgl_vivo/

getinfo 查看当前分包信息 ​

bash
Usage: qg-wasmsplit getinfo [options]
get minigame function info
Options:  -p, --project-path <projectPath>         
      project path, 小游戏项目路径, 必填
  -h, --help                               
      display help for command

并以json格式保存在"$projectpath/.plugincache/codesplit/gameinfo.txt"中。 getinfo的json字段说明

键说明
appId当前项目AppId
wasmHash当前wasm代码md5
wasmVersionDesc当前wasm分包版本
hisFirstFuncs当前分包版本已收集到的首包函数个数
totalFuncs原始包函数总个数
  • 示例
bash
qg-wasmsplit getinfo -p ./webgl_vivo/