分包加载

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

分包加载包大小的限制

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

• 整个小游戏所有分包大小不超过 20M
• 单个分包/主包大小不能超过 4M

使用方法

1. 分包配置

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

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

├── game.js
├── game.json
├── images
│ ├── a.png
│ ├── b.png
├── stage1
│ └── game.js
│ └── images
│ ├── 1.png
│ ├── 2.png
└── stage2.js

game.json 中的配置：

{
    ...
    "subpackages": [
        {
            "name": "stage1",
            "root": "stage1/" // 可以指定一个目录，目录根目录下的 game.js 会作为入口文件，目录下所有资源将会统一打包
        },
        {
            "name": "stage2",
            "root": "stage2.js" // 也可以指定一个 JS 文件
        }
    ]
    ...
}

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

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

由于当前构建打包依赖分包配置顺序，请确保子目录/文件的分包配置在父目录之前 (如下示例说明)

• 可通过的分包配置

"subpackages": [
    {
        "name": "res_500_1",
        "root": "res/res_4700/res_500_1" // 打包前大小: 500K | 打包后: 500K
    },
    {
        "name": "res_500_2",
        "root": "res/res_4700/res_500_2" // 打包前大小:500K | 打包后:500K
    },
    {
        "name": "res_4700",
        "root": "res/res_4700" // 打包前大小:4700K | 4700 - 500 - 500 = 打包后:3700K
    }
]

• 不能通过的分包配置 （分包大小超限）

"subpackages": [
    {
        "name": "res_4700",
        "root": "res/res_4700" // 打包前大小: 4700K | 打包后: 4700K
    },
    {
        "name": "res_500_1",
        "root": "res/res_4700/res_500_1" // 打包前大小: 500K | 打包后: 500K
    },
    {
        "name": "res_500_2",
        "root": "res/res_4700/res_500_2" // 打包前大小: 500K | 打包后: 500K
    }
]

2. 分包加载

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

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

示例代码：

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

loadTask.onProgressUpdate(res => {
    console.log('下载进度', res.progress);
    console.log('已经下载的数据长度', res.totalBytesWritten);
    console.log('预期需要下载的数据总长度', res.totalBytesExpectedToWrite);
});