Comprehensive explanation of CocosCreator hot update

Preface

This article mainly quotes the official documentation of Cocos on hot updates, and on this basis, summarizes the current hot update process of Sprout.

What is Hot Change

Hot updates essentially download the required resources from the server to the local device and execute new game logic so that the new resources can be used by the game. It allows developers to fix bugs and release features without releasing a new version, allowing developers to bypass Apple's review mechanism and avoid long review waits and the costs of multiple rejections.

The default hot update mechanism of Cocos is not based on the patch package update mechanism. Traditional hot updates often generate patch packages for multiple versions, download the patch packages in sequence and update to the latest version. Cocos' hot update mechanism generates and updates a difference list by directly comparing the latest version with the local version.

Cocos Hot Update Overview

manifest

Before understanding cocos hot update, you must first understand manifest. In Cocos, manifest is a file format, and its corresponding file is referred to as resource description file, which is used to describe the resource list and resource version contained locally or remotely.

The manifest format is modeled after the JSON format, and the meanings of its key fields are as follows:

{
    "packageUrl": local cache root path of remote resources"remoteVersionUrl": [optional] path of remote version file, used to determine whether there is a new version of the resource on the server side"remoteManifestUrl": path of remote resource Manifest file, including version information and all resource information"version": resource version"engineVersion": engine version"assets": list of all resources"key": relative path of resource (relative to resource root directory)
        "md5": md5 value represents the version information of the resource file "compressed": [optional] If the value is true, the file will be automatically decompressed after being downloaded. Currently only zip compression format is supported "size": [optional] The byte size of the file, used to quickly obtain progress information "searchPaths": The search path list that needs to be added to FileUtils}

The manifest file can be automatically generated by the Version Generator script in the Cocos Creator hot update example.

The difference between project resources and game package resources

When you create a Cocos Creator project, you can see an assets directory under it, which stores your scenes, scripts, prefabs, etc., corresponding to the assets panel in the editor. However, these project resources are not equivalent to the packaged resources. When using the build panel to build the native version, we will find the res and src folders in the build directory. These two folders contain the game package resources that actually make the game run. src contains all scripts and res contains all resources.

Therefore, our hot update of resources should naturally update the built resources instead of the assets directory of the project.

In creator2.4.3, the resource management module was reconstructed, and bundle modularization was used to manage resources. Here is an API to get the resource path through uuid

cc.assetmanager.utils.getUrlWithUuid //Convert uuid to url. The url returned here is the resource path in the runtime game package

searchPathsSearch Paths

Before talking about hot updates, it is necessary to understand the concept of searchPaths. Most of the time, when we describe the path of a file, we will give the corresponding "relative path" based on a "root directory" and will not directly write it as an "absolute path". This is more conducive to maintenance and migration. In game development, it is actually difficult to ensure the certainty and uniqueness of our "root directory". Take the hot update function as an example. We have an image. Assume that the relative path of its corresponding bundle directory (the default is resources) is "./png/icon1.png". When our game version is updated and the image needs to be updated, since the resources in the package are not writable, we can only let it read the new image from another place. In order to ensure the consistency of the code, if we can change the corresponding "root directory", the previous relative paths in the code do not need to be modified, and the new image can be found.

In creator, it maintains a set of search path strategies. For the corresponding APIs, please refer to jsb.fileUtils.getSearchPaths, jsb.fileUtils.fullPathForFilename, etc. The principle is briefly described here. FileUtils stores an array of "root directories". The lower the index, the higher the priority. When searching for resources, if we specify a "relative path", it will be spliced ​​into an "absolute path" according to the priority of the "root directory" in searchPaths to search for resources. If the path is valid and the file is found, it will stop searching.

In the installation directory of the game package, there must be a directory to store the various scripts and resources we packaged. We call it the "game package directory" here. In the hot update logic, we need to specify a "hot update directory" to store our hot update content. Both directories should be set as search paths, and the versions need to be controlled so that the higher the priority of the directory, the higher the corresponding search path priority. In this way, we can find the latest files. Generally speaking, the priority of "hot change directory" needs to be higher than that of "game package directory".

Basic hotfix process of cocos

This is the flow chart of the cocos official website. Please note that the current process is the first time the user checks the server version update after installing the app. The complete hot update process will be more complicated, and we will slowly add to it later.

This article mainly helps you understand the process logic of hot update itself. Its details, such as breakpoint resumption, download progress, concurrent downloads, error detection, decompression, error recovery and other details, will not be discussed for now. Therefore, the appeal flowchart can be simply summarized as follows:

According to the remoteVersionUrl field of the manifest in the current package, download the current version description file, and then compare it with the local version. If an update is required, update it to the corresponding latest version. Otherwise, no update is required and continue with the subsequent process.

Here we need to further analyze several key points:

_localManifest: the manifest in the current package

First of all, there should be a default manifest file in the "game package directory" that describes the current game version (the "version" field). This manifest is generally updated when the game package is uninstalled or installed. Then there will also be a manifest file in the "hot change directory" that describes the version information under the current hot change directory. Every time we start the game, we should determine whether the "game package directory" or the "hot change directory" is the latest version in the current environment, and adjust the corresponding priority in searchPaths. The newer manifest is also called the manifest in the current package, and is recorded in the code using _localManifest.
Note that there is no such step in the above cocos basic hot update process because it represents the first installation of the package. There is no manifest file in the hot update directory, so _localManifest is the "game package directory". The complete hot update process requires this step of judgment.
For the code corresponding to the above logic, please refer to the init, loadLocalManifest and other functions of AssetsManagerEx.

Request the remote version manifest first

In the "remoteVersionUrl" field of the manifest, it corresponds to the version file of the remote server. Here is a version.manifest of the official demo for your understanding.

{
    "packageUrl":"http://192.168.50.220:5555/tutorial-hot-update/remote-assets/",
    "remoteManifestUrl":"http://192.168.50.220:5555/tutorial-hot-update/remote-assets/project.manifest",
    "remoteVersionUrl":"http://192.168.50.220:5555/tutorial-hot-update/remote-assets/version.manifest",
    "version":"2.0"
}

As you can see above, version.manifest has a "version" field, which is also the basis for our quick version comparison. Download version.manifest, and then compare it with the local _localManifest version to detect whether the current package needs to be updated. This process is generally named checkUpdate in the code.

The necessity of temporary folders

During the hot update process, because we download multiple resources in sequence, various problems are likely to occur during this period. Therefore, we need a temporary folder to temporarily store our downloads. After all files are downloaded, we also need to check whether the files are complete before replacing the old resources in the "hot update directory". Do not download directly to the "hot update directory". Once a problem occurs, you will not be able to figure out which part is new and which part is old. This idea can also be used in program design. When maintaining the data and fields we are responsible for, we should try to replace and update them as a whole, rather than modifying and assigning values ​​arbitrarily.

Hotter is hotter and more differentiated files, how do we do this?

In the manifest file, under the "assets" field, record the key and md5 information of each resource. You only need to compare the resources recorded in the remote _remoteManifest. New keys are newly added resources, and resources without keys need to be deleted. Files with different md5s are files that need to be updated.
For the corresponding code, please refer to: Manifest's genDiff and other functions.

After the heat is better, how to make it effective

When we have added new resources, how can we make them take effect without adjusting the code? Haha, as I have just introduced above, we just need to adjust our searchPaths so that the "hot change directory" has a higher priority than the "game package directory".
In the above flowchart, cocos recommends using cc.sys.localStorage to store the path corresponding to _localManifest, and at the beginning of the subsequent app startup, read the corresponding path from cc.sys.localStorage and set it to searchPaths.
The above solution is certainly feasible, but for a complete client framework, especially for lobby-type games with multiple sub-projects, I personally think that this dynamic storage path and setting path is not a more appropriate solution. In terms of architectural design, we need to first determine the "hot change directory" of the entire client and determine the priority, that is, the searchPaths of the entire project are fixed according to the logic we set, rather than being adjusted dynamically. The advantage of this is that the searchPaths logic is determined in a unique place, and then only the resources under the corresponding path need to be added or deleted according to the logic, which should be more conducive to expansion and maintenance. However, it should also be noted that for this solution with fixed searchPaths, when the app is installed and replaced, the comparison between the new "game package directory" version and the previous version in the "hot change directory" must be maintained. For example, if the version after the local installation and upgrade of the app is higher than the previous version of the "hot change directory", you can consider clearing all the resources under the previous "hot change directory". Another more troublesome logic is that the version after the app is installed and upgraded is still lower than the version of the "hot change directory". It should be noted that the "hot change directory" stores differential files relative to the "game package directory" before the upgrade. After the upgrade, the files in the "game package directory" change, then the differential files in the "hot change directory" may not be compatible with the current "game package directory". In this case, the "hot change directory" can also be re-compared and the differential files can be hot-changed.

How to deal with old version resources

Although the hot update of cocos is a differential file, its manifest script records all the resources of the corresponding bundle. We can know which resources are no longer needed. The genDiff function is also mentioned above, but I personally think that the deletion of old resources needs to be cautious, at least make sure that the new resources are updated before deleting the old resources.

Summarize

If readers digest the above knowledge and use the basic functions provided by Cocos, they can completely customize their own hot update process. Hot update, in a nutshell, downloads the latest remote resources to replace the existing resources in the current package. For example, for some small projects, you can download and replace the entire package, and ignore the details such as version comparison, searchPath adjustment, file verification, etc.

The above is a comprehensive explanation of the details of CocosCreator hot update. For more information about CocosCreator hot update, please pay attention to other related articles on 123WORDPRESS.COM!