# Subpackage Loading

Weixin 6.6.7 client, 2.1.0 and above base library are supported, please update to the latest client version and use Developer Tool with version of 1.02.1806120 and above. It’s available at Click here to download

As the gameplay of Mini Game becomes more and more abundant, the developer's demand for expanding the package size becomes more and more intense, so we introduced the function of subpackage loading of Mini Game. The so-called subpackage loading means splitting the game content into several packages according to certain rules, and the necessary packages are downloaded first when starting up. The necessary package is called "main package", and the developer can trigger the downloading of other subpackages in the main package, which dissipates the downloading time spent on the first launch to the game.

# Subpackage Load Packet Size Limit

At present, the size of the Mini Game subpackage has following restrictions:

• The size of all subpackage of the entire Mini Game can not exceed 8M
• The size of single subpackage / main package can not exceed 4M

# Instructions

# 1. Subpackage Configuration

You need to configure subpackage information in game.json first.

Suppose the directory structure of the game is as follows:

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

Configuration in game.json:

{
  ...
  "subpackages": [
    {
      "name": "stage1",
      "root": "stage1/" // can specify a directory. The game.js in the root directory will be used as the entry file. All resources in the directory will be packaged together.
    }, {
      "name": "stage2",
      "root": "stage2.js" // can also specify a JS file
    }
  ]
  ...
}

The directories or js files configured in the subpackages field will be packaged into "subpackages" according to the configuration. The directories and js that are not configured in subpackages will be packaged into the main package.

Note: The open data domain directory (ie openDataContext configuration directory) is not supported to be set to be a subpackage or placed under a certain subpackage.

# 2. Subpackage Loading

We provide the wx.loadSubpackage() API to trigger the download of the subpackage. After calling wx.loadSubpackage, the download and load of the package will be triggered. After the loading is completed, there will be notice of loading completion through wx.loadSubpackage success callback.

At the same time, wx.loadSubpackage will return a [LoadSubpackageTask] ((LoadSubpackageTask)), the current download progress can be obtained through LoadSubpackageTask.

Example Code:

const loadTask = wx.loadSubpackage({
  name: 'stage1', // name can be filled in with name or root
  success: function(res) {
    // Callback through success after successful subpackge loading
  },
  fail: function(res) {
    // Callback through fail after subpackge loading failed
  }
})

loadTask.onProgressUpdate(res => {
  Console.log('download progress', res.progress)
  console.log('length of data already downloaded', res.totalBytesWritten)
  console.log('total length of data expected to be downloaded', res.totalBytesExpectedToWrite)
})

# Old Version Compatible

The compatibility of the old version of the client is handled by compilation at Weixin background, the background will compile two code packages, one is the subpackaged code, and the other is the compatible code of the whole package. For the old client, the whole package code will be downloaded to start.

The developer with the base library version below 2.1.0 does not need to call wx.loadSubpackage to trigger loading. The wx.loadSubpackage method does not exist in versions below 2.1.0.

In the old version, the developer needs to call require to trigger the loading of the subpackage entry file, for example:

require('stage1/game.js')

If you do not plan to be compatible with older versions, developers can block users of the base version below 2.1.0 through the MP Mini Programs background configuration.

# Known BUG

Currently Android can't load the font file under the subpackage, it is expected to be fixed in the next Weixin client version.