Package Loading

As the gameplay of mini-games becomes more and more diverse, developers have an increasingly strong demand for expanding package sizes, so we have launched the mini-game sub-package loading function. The so-called sub-package loading means splitting the game content into several packages according to certain rules, and downloading the necessary packages first at the first startup. This necessary package is called the main package. Developers can trigger the download of other sub-packages in the main package, thereby dispersing the time-consuming download of the first startup to the game operation.

Developers can use the sub-package loading capability encapsulated by the framework, or directly use game.json to configure sub-packages without using the framework. The relevant details are as follows.

Usage restrictions:

Currently, the size of the mini-game sub-package has the following restrictions:

• The size of the entire mini-game main package + sub-package does not exceed 20M
• The main package does not exceed 4M
• There is no size limit for a single ordinary sub-package
• A single independent sub-package does not exceed 4M

Use subpackages

Configuration method

Assume that the directory structure of the mini program that supports subpackages is as follows:

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

Configuration in game.json:

{
  ...
  "subpackages": [
    {
      "name": "stage1",
      "root": "stage1/" // Specify a directory; the game.js in the root directory will be the entry file, and all resources in the directory will be packaged together
    }, {
      "name": "stage2",
      "root": "stage2.js" // You can also specify a JS file
    }
  ]
  ...
}

In subpackages, the configuration of each subpackage has the following items:

Fields	Type	Description
root	String	Subpackage root directory
name	String	Subpackage alias,,Subpackage pre-downloadCan be used
independent	String	Is the subpackageIndependent subpackage

Packaging principle

• After declaring subpackages, they will be packaged according to the subpackage configuration path, and the directories outside the subpackage configuration path will be packaged into the main package.
• The root directory of a subpackage cannot be a subdirectory in another subpackage.

Reference principle

• packageA cannot require packageB JS files, but can require JS files in the main package and packageA; this restriction does not apply when using
• packageA cannot use packageB's resources, but can use resources in the main package and packageA.

Independent Subpackage

Independent subpackages are a special type of subpackage in mini-games that can run independently of the main package and other subpackages. When starting a mini-game with an independent subpackage path, the client will only download the independent subpackage and start the game, and will not download the main package, so as to meet the needs of quickly starting the game in some scenarios. Developers can configure certain pages with certain functional independence into independent subpackages as needed, which can greatly improve the page opening speed.

After the independent subpackage is started, developers can use the wx.loadSubpackage interface to pre-download the main package or other subpackages as needed, and execute the downloaded code package logic at the right time (for example, when the user clicks to start the game).

Configuration method

Assume that the directory structure of the mini-game is as follows:

.
├── game.js
├── game.json
├── moduleA
│   └── game.js
├── moduleB
│   └── game.js
└── utils

The developer declares the corresponding subpackage as an independent subpackage by defining the independent field in the corresponding subpackage configuration item in the subpackages field of game.json.

{
  "subPackages": [
    {
      "name": "moduleA",
      "root": "/moduleA/", // Regular subpackage
    },
    {
      "independent": true, // Independent subpackage, specify a directory; the game.js in the root directory will be the entry file, and all resources in the directory will be packaged together
      "name": "moduleB",
      "root": "/moduleB/",
    }
  ]
}

Share the specified independent subpackage page in the game:

// Share with friends or groups
wx.shareAppMessage({
  title: 'Share the title',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path corresponds to the root of the independent subpackage as configured in game.json
})
Share on Moments
wx.onShareTimeline({
  title: 'Share the title',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path corresponds to the root of the independent subpackage as configured in game.json
})
// Add to Favorites
wx.addToFavorites({
  title: 'Favorite title',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path corresponds to the root of the independent subpackage as configured in game.json
})

Download other subpackages in the independent subpackage:

const loadTask = wx.loadSubpackage({
  name: "/moduleA/", // Download another subpackage
  success(res) {
    console.log("load moduleA success", res);
  },
  fail(err) {
    console.error("load moduleA fail", err);
  },
});

Notes

• There can be multiple independent subpackages in a mini-game.
• Starting the independent subpackage of the mini-game is only valid for cold start.
• Independent subpackages are a type of subpackages. All restrictions of ordinary subpackages are valid for independent subpackages.
• Independent subpackages cannot rely on the content in the main package and other subpackages, including JS files and resource files.
• The path in the wx.shareAppMessage parameter or the wx.onShareAppMessage return parameter must be the root field of the independent subpackage defined in game.json.

Package Loading

We provide the wx.loadSubpackage() API to trigger the download of subpackages. After calling wx.loadSubpackage, the download and loading of subpackages will be triggered. After the loading is completed, the success callback of wx.loadSubpackage will be used to notify the completion of the loading.

At the same time, wx.loadSubpackage will return a LoadSubpackageTask, and the current download progress can be obtained through LoadSubpackageTask.

Sample code:

const loadTask = wx.loadSubpackage({
  name: "stage1", // name can be either the name or the root
  success: function (res) {
    // Callback for successful subpackage loading
  },
  fail: function (res) {
    // Callback for failed subpackage loading
  },
});

loadTask.onProgressUpdate((res) => {
  console.log("Download progress", res.progress);
  console.log("Downloaded data length", res.totalBytesWritten);
  console.log("Expected total data length", res.totalBytesExpectedToWrite);
});

Subpackage pre-download

我们提供了 wx.preDownloadSubpackage() API 来触发分包的预下载，调用 wx.preDownloadSubpackage 后，将触发分包的下载与加载，在加载完成后，通过 wx.preDownloadSubpackage 的 success 回调来通知加载完成。预加载完成后，需要使用 wx.loadSubpackage 执行分包代码。

The difference between wx.preDownloadSubpackage and wx.loadSubpackage: wx.preDownloadSubpackage only downloads the code package and does not automatically execute the code; wx.loadSubpackage automatically executes the code after downloading the code package.

Sample code:

// Preload
const loadTask = wx.preDownloadSubpackage({
  name: "stage1",
  success: function (res) {
    // Callback for successful subpackage preloading
  },
  fail: function (res) {
    // Callback for failed subpackage preloading
  },
});

loadTask.onProgressUpdate((res) => {
  console.log("Download progress", res.progress);
  console.log("Downloaded data length", res.totalBytesWritten);
  console.log("Expected total data length", res.totalBytesExpectedToWrite);
});

// Execute subpackage code logic at an appropriate time
wx.loadSubpackage({
  name: "stage1",
});