# Resource cache

# Resource Cache

The file directory of the mini game on the real machine is divided into a temporary file directory and a user file directory:

-The size of the temporary file directory is not limited, but it will be cleaned regularly -The user file directory has a limited size of 200MB, but it can be retained forever.

When loading resources, if you set cacheable: true, then the file will be downloaded to the user file directory, otherwise it will be downloaded to the temporary file directory. The resource file in the user file directory is the resource cache.

engine.loader.load("resource/Aircraft.prefab", {
  cacheable: true
}).promise.then((spriteFrame) => {
  console.log(spriteFrame)
})

The caching behavior of resource files is controlled and scheduled internally by the resource loading module, and developers do not need to care. Take the above code as an example, after "resource/Aircraft.prefab" is loaded, the corresponding resource file has been cached in the user file directory.

# Cache directory

wx.env.USER_DATA_PATH is the root directory of the user file directory of the mini game, ${wx.env.USER_DATA_PATH}/engine-cache is the root directory of the resource cache, and all cache files are in this directory.

You can directly use the wx file API to access this directory.

const fs = wx.getFileSystemManager();
try {
  const files = fs.readdirSync(`${wx.env.USER_DATA_PATH}/engine-cache`);
  console.log(files);
}
catch (error) {
  console.error("engine-cache has not been created yet", error)
}

The structure of the cache directory is as follows:

-wxfile://usr -engine-cache (root directory) -res_ui_accepting_applications_bid_e61c12ce@combine_0.bin -res_ui_accepting_applications_bid_e61c12ce@assets_ui.png -dep_00131089c86875e2ff637d09ff5038a8_9a089497@combine_0.bin -userData.json (other files in the user file directory) -...

The file name of the cache file is saved and read in the format of ${resource group name}@${resource file name}. The @ character is the separator that separates the resource group name and the resource file name, so the file name should not contain the @ character, otherwise it will cause the cache module to report an error.

If the resource file name must contain the @ character, you can replace it with a separator. But this step must be set before engine.cache.init().

// Replace the delimiter with #
engine.cache.delimiter = "#";
// If the cache module is manually initialized, it must be set before engine.cache.init()
engine.cache.init();
// If the cache module is not initialized manually, it must be set before engine.init()
engine.init(canvas);

# Cache limit

In addition to the resource cache, the game may also need to write some business files in the user file directory, such as the player's offline archive. Therefore, the user file directory cannot be filled with resource files. The cache size can be limited by setting CacheManager.sizeLimit.

engine.cache.sizeLimit = 180*1024*1024;

sizeLimit is just an attribute value that the JS layer limits the write of the cache file, and cannot affect the setting of the upper limit of the file directory size of the mini game user. Even if sizeLimit is set to 500*1024*1024, writing will fail when the total file size exceeds 200 MB.

# Cache Update

The resource group name is also the resource group id, and the end of the id is an 8-bit hash. When the content of the file in the resource group changes, the hash at the end will also change. The new and old version resource groups with different hashes will be regarded as two different resource groups. The resources of the old version will be deleted in the elimination process because they are not used.

For example, the combine_0.bin files of the two res_ui_accepting_applications_bid resource groups with different hashes at the end are two different cache files.

res_ui_accepting_applications_bid_9a089497@combine_0.bin res_ui_accepting_applications_bid_e61c12ce@combine_0.bin

# Cache elimination

When a new cache is written and the current cache space is insufficient, the cache elimination will be triggered. Insufficient cache space includes two situations:

1. The existing cache size plus the new cache size exceeds sizeLimit.
2. The write failed due to reaching the upper limit of the file directory size of the mini game user.

When the cache space is insufficient, the cache module will call the callback function onNeedRelease() exposed to the game business side. The game business side returns a value indicating the size of the buffer space to be released.

engine.cache.onNeedRelease = (res) => {
  console.log(`The remaining cache space is insufficient, the existing cache: ${res.currentSize} B, the new write cache ${res.cacheSize}`)
  // Eliminate 80 MB cache
  return 80*1024*1024;
}

Returning a value less than 0 means that the cache will not be eliminated this time, and writing to the new cache will fail.

engine.cache.onNeedRelease = (res) => {
  return -1;
}

If engine.cache.onNeedRelease is not set, the size of the cache to be eliminated is the size of the newly written cache. If the cache file to be written is 5 MB, then release >= 5MB of cache space.

# Elimination strategy

In addition to the basic LRU, the game business side also hopes to customize the elimination strategy. Therefore, the cache module exposes the compare function. The usage of compare is the same as Array.prototype.sort. After sorting, a resource with ascending weight is obtained Cache array. The cache module is eliminated in turn from the head of the array until the space to be freed is satisfied.

In the parameters of the compare function, the loading information of each cached resource group in this game is exposed, and the game business side can customize the loading strategy accordingly.

The default sorting is based on useTimes, that is, LRU.