Optional Parameters

Author: Santy-Wang, Xunyi

For added flexibility and extensibility, most of the load interfaces in Asset Manager, including assetManager.loadAny and assetManager.preloadAny, provide options parameters. In addition to configuring the built-in parameters of Creator, options also allows you to customize any parameters to extend engine functionality. If you do not need to configure the engine’s built-in parameters or extend the engine’s functionality, you can ignore it and just use the simpler API interfaces, such as resources.load.

Parameters that are currently used by the engine in options include the following:

uuid, url, path, dir, scene, type, priority, preset, audioLoadMode, ext, bundle, onFileProgress, maxConcurrency, maxRequestsPerFrame, maxRetryCount, version, xhrResponseType, xhrWithCredentials, xhrMimeType, xhrTimeout, xhrHeader, reloadAsset, cacheAsset, cacheEnabled,

DO NOT use the above fields as your custom parameter names to avoid conflicts with engine functions.

Engine Extension

You can extend the loading capabilities of the engine by using optional parameters in the Pipeline and Custom Handlers. For example:

  1. // Extend the pipeline
  2. assetManager.pipeline.insert(function (task, done) {
  3.     let input = task.input;
  4.     for (let i = 0; i < input.length; i++) {
  5.         if (input[i].options.myParam === 'important') {
  6.             console.log(input[i].url);
  7.         }
  8.     }
  9.     task.output = task.input;
  10.     done();
  11. }, 1);
  13. assetManager.loadAny({'path': 'images/background'}, {'myParam': 'important'}, callback);
  15. // Register the handler
  16. assetManager.downloader.register('.myformat', function (url, options, callback) {
  17.     // Download the resource
  18.     const img = new Image();
  19.     if (options.isCrossOrigin) {
  20.         img.crossOrigin = 'anonymous';
  21.     }
  23.     img.onload = function () {
  24.         callback(null, img);
  25.     };
  27.     img.onerror = function () {
  28.         callback(new Error('download failed'), null);
  29.     };
  31.     img.src = url;
  33. });
  35. assetManager.parser.register('.myformat', function (file, options, callback) {
  36.     // Parse the downloaded file
  37.     callback(null, file);
  38. });
  40. assetManager.loadAny({'url': 'http://example.com/myAsset.myformat'}, {isCrossOrigin: true}, callback);

The engine can be extremely extensible by using optional parameters, combined with pipelines and custom handlers, and Asset Bundle can be seen as the first instance of extension using optional parameters.