分包加载

随着小游戏的玩法越来越丰富,开发者对于扩大包大小的需求越来越强烈,所以我们推出了小游戏分包加载这一个功能。 所谓的分包加载,即把游戏内容按一定规则拆分这几包,在首次启动时先下载必要的包,这个必要的包我们称为「主包」,开发者可以在主包内触发其它分包的下载,从而把首次启动的下载耗时分散到游戏运行中。

分包加载包大小的限制

目前小游戏分包大小有以下限制:

  • 整个小游戏所有分包大小不超过 16M (请使用0.1.29版本开发者工具进行上传)
  • 单个分包/主包大小不能超过 4M

使用方法

1. 分包配置

需要先在 game.json 配置分包信息。

假设游戏的目录结构如下:

├── game.js
├── game.json
├── images
│   ├── a.png
│   ├── b.png
├── stage1
│   └── game.js
│   └── images
│       ├── 1.png
│       ├── 2.png
└── stage2.js
1
2
3
4
5
6
7
8
9
10
11

game.json 中的配置:

{
  ...
  "subpackages": [
    {
      "name": "stage1",
      "root": "stage1/" // 可以指定一个目录,目录根目录下的 game.js 会作为入口文件,目录下所有资源将会统一打包
    }, {
      "name": "stage2",
      "root": "stage2.js" // 也可以指定一个 JS 文件
    }
  ]
  ...
}
1
2
3
4
5
6
7
8
9
10
11
12
13

配置在 subpackages 字段内的目录或 js 文件,将按照配置打包成一个个「分包」,没有配置在 subpackages 中的目录和 js,将会被打包到主包中。

注:目前不支持将开放数据域目录(即 openDataContext 配置目录)设置为分包或置于某个分包下。

2. 分包加载

我们提供了 qq.loadSubpackage() API 来触发分包的下载,调用 qq.loadSubpackage 后,将触发分包的下载与加载,在加载完成后,通过 qq.loadSubpackage 的 success 回调来通知加载完成。

同时,qq.loadSubpackage 会返回一个 LoadSubpackageTask,可以通过 LoadSubpackageTask 获取当前下载进度。

示例代码:

const loadTask = qq.loadSubpackage({
  name: 'stage1', // name 可以填 name 或者 root
  success(res) {
    // 分包加载成功后通过 success 回调
  },
  fail(res) {
    // 分包加载失败通过 fail 回调
  }
})

loadTask.onProgressUpdate(res => {
  console.log('下载进度', res.progress)
  console.log('已经下载的数据长度', res.totalBytesWritten)
  console.log('预期需要下载的数据总长度', res.totalBytesExpectedToWrite)
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15