367 lines
15 KiB
JavaScript
367 lines
15 KiB
JavaScript
|
/**
|
||
|
|
* Adds all assets to a skill,
|
||
|
|
* including custom ones from your file system
|
||
|
|
* that are not included in the template skill by default.
|
||
|
|
* Assets can include images, sounds, code, data, and other files.
|
||
|
|
*
|
||
|
|
* @example <caption> <h4>Loading a Single File </h4></caption>
|
||
|
|
* const jibo = require('jibo');
|
||
|
|
* jibo.loader.load('config.json', function(err, config) {
|
||
|
|
* // config is the parsed JSON object
|
||
|
|
* });
|
||
|
|
* // this is the same as:
|
||
|
|
* jibo.loader.load({ src: 'config.json' }, function(err, config) {
|
||
|
|
* // config is the parsed JSON object
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Loading Multiple Files</h4></caption>
|
||
|
|
* const jibo = require('jibo');
|
||
|
|
* const assets = [
|
||
|
|
* "logo.png",
|
||
|
|
* "header.jpg"
|
||
|
|
* ];
|
||
|
|
* jibo.loader.load(assets, function(err, results) {
|
||
|
|
* // results is an Array of HTMLImageElements
|
||
|
|
* });
|
||
|
|
* const jibo = require('jibo');
|
||
|
|
* const assets = [
|
||
|
|
* { id:'logo', src: "logo.png" },
|
||
|
|
* { id: 'header', src: "header.jpg" }
|
||
|
|
* ];
|
||
|
|
* jibo.loader.load(assets, function(err, results) {
|
||
|
|
* // results is an Object with keys 'logo' and 'header'
|
||
|
|
* // the values are both HTMLImageElements
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Caching Assets</h4>
|
||
|
|
* In order to cache elements, each asset must have an id field,
|
||
|
|
* which is the name of the element accessible from the loader's cache.</caption>
|
||
|
|
* const jibo = require('jibo');
|
||
|
|
* const assets = [
|
||
|
|
* { id:'logo', src: "logo.png", cache: true },
|
||
|
|
* { id: 'header', src: "header.jpg", cache: true }
|
||
|
|
* ];
|
||
|
|
* jibo.loader.load(assets, function() {
|
||
|
|
* jibo.loader.cached('logo'); // contains HTMLImageElement
|
||
|
|
* jibo.loader.cached('header'); // contains HTMLImageElement
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Options for Multiple Loading</h4></caption>
|
||
|
|
* jibo.loader.load(assets, {
|
||
|
|
* complete: function(err, results){}, // when completed
|
||
|
|
* progress: function(progress){}, // percentage of total load progress
|
||
|
|
* taskDone: function(err, result){}, // called when a task is complete
|
||
|
|
* cacheAll: false, // cache all assets
|
||
|
|
* startAll: true // start all file requests at once
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* @example <caption> <h4>Return Types</h4></caption>
|
||
|
|
* | Extension | Result Type |
|
||
|
|
* | ------------------------ | -------------------------- |
|
||
|
|
* | png, jpg, gif, bmp, webp | `HTMLImageElement` |
|
||
|
|
* | html | `HTMLDocument` |
|
||
|
|
* | css | `HTMLStyleElement` |
|
||
|
|
* | mp3, oga, ogg, wav, m4a | `ArrayBuffer` |
|
||
|
|
* | svg, xml | `Document` |
|
||
|
|
* | webm, ogm, m4v, mp4 | `Buffer` |
|
||
|
|
* | txt | `String` |
|
||
|
|
* | json | `JSON` |
|
||
|
|
* | js | return of `module.exports` |
|
||
|
|
*
|
||
|
|
* @example <caption><h4>General Asset</h4>
|
||
|
|
* An asset can be represented as a String (path to load) or Object.
|
||
|
|
* The asset Object contains several optional keys and a required src key.</caption>
|
||
|
|
* {
|
||
|
|
* src: "file.txt", // path to file
|
||
|
|
* cache: false, // save to cache
|
||
|
|
* id: "file-ref", // cache key
|
||
|
|
* complete: function(result){}, // returns
|
||
|
|
* }
|
||
|
|
*
|
||
|
|
* @example <caption> <h4>Color-Alpha Asset </h4>
|
||
|
|
* The Color-Alpha asset can be used to load an image and apply a color.
|
||
|
|
* Can be useful for compressing large spritesheets as JPGs and applying a simple alpha channel from a PNG.
|
||
|
|
* </caption>
|
||
|
|
* {
|
||
|
|
* src: "color.jpg", // path to file
|
||
|
|
* alpha: "color-alpha.png", // alpha
|
||
|
|
* complete: function(err, img){}, // returns HTMLImageElement
|
||
|
|
* }
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Texture Asset </h4>
|
||
|
|
* By default, loading images returns an HTMLImageElement.
|
||
|
|
* To return a PIXI.Texture object, you can used the Texture Asset.
|
||
|
|
* Notice the required field type.</caption>
|
||
|
|
* {
|
||
|
|
* src: "logo.png",
|
||
|
|
* type: "texture", // required
|
||
|
|
* upload: false, // upload to GPU when finished downloading
|
||
|
|
* complete: function(err, texture){} // returns PIXI.Texture object
|
||
|
|
* }
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Keys Asset </h4>
|
||
|
|
* Preload a keys file and any assets (sounds or timelines) that it uses.</caption>
|
||
|
|
* {
|
||
|
|
* src: "my-animation.keys",
|
||
|
|
* type: "keys", // required
|
||
|
|
* root: "/path/to/the/project-or-assetpack", // Can be used with PathUtils.getAssetUri
|
||
|
|
* complete: function(err, animation){} // returns jibo.rendering.animation.KeysAnimation object
|
||
|
|
* }
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Timeline Asset</h4>
|
||
|
|
* Preload a PixiAnimate animation.
|
||
|
|
* Will preload any assets used by the timeline (shapes & images). </caption>
|
||
|
|
* {
|
||
|
|
* src: "my-animation.js",
|
||
|
|
* type: "timeline", // required
|
||
|
|
* complete: function(err, timeline){} // returns jibo.rendering.animation.Timeline object
|
||
|
|
* }
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Sound Asset </h4>
|
||
|
|
* Sounds can be loaded automatically and added to jibo.sound.
|
||
|
|
* If no ID is specified, the basename of the file is used as the sound alias.
|
||
|
|
* In the example below, the alias would be "music",
|
||
|
|
* and the sound could be played by calling jibo.sound.play("music").
|
||
|
|
* </caption>
|
||
|
|
* {
|
||
|
|
* src: "music.mp3",
|
||
|
|
* type: "sound", // required
|
||
|
|
* block: false, // allow only playing at once
|
||
|
|
* volume: 1, // from 0 to 1
|
||
|
|
* panning: 0, // from -1 (left) to 1 (right)
|
||
|
|
* loop: false, // allow looping
|
||
|
|
* autoPlay: false, // play when finished
|
||
|
|
* complete: function(err, sound){} // returns jibo.sound.Sound object
|
||
|
|
* }
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Function Asset</h4>
|
||
|
|
* A function can be used as an asset like any other.
|
||
|
|
* This requires done to be called. Optionally a result can be passed as the
|
||
|
|
* first argument to done and this will be used as the cached result.
|
||
|
|
* </caption>
|
||
|
|
* function(err, done)
|
||
|
|
* {
|
||
|
|
* // do some async things here
|
||
|
|
* done();
|
||
|
|
* }
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Unloading</h4></caption>
|
||
|
|
* const assets = [
|
||
|
|
* { id:'logo', src: "logo.png", cache: 'myCache' },
|
||
|
|
* { id: 'header', src: "header.jpg", cache: 'myCache' }
|
||
|
|
* ];
|
||
|
|
* jibo.loader.unload(assets);
|
||
|
|
* jibo.loader.unload(['logo', 'header'], 'myCache'); // alternatively, remove by IDs
|
||
|
|
* jibo.loader.unloadAll(); // remove all assets
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Custom Task </h4>
|
||
|
|
* When assets are loaded by the loader module, they are converted into asynchronous Tasks.
|
||
|
|
* Custom tasks can be registered with the loader module to provide
|
||
|
|
* convenience creating complex types of objects. Here's an example:</caption>
|
||
|
|
* // Must extend the Task class
|
||
|
|
* class SpritesheetTask extends jibo.loader.Task {
|
||
|
|
* // A test method is required to test if an asset can use this task
|
||
|
|
* static test(asset) {
|
||
|
|
* return asset.image && asset.data;
|
||
|
|
* }
|
||
|
|
* // constructor takes the assetManager and asset as arguments
|
||
|
|
* constructor(manager, asset) {
|
||
|
|
* super(manager, asset, asset.image);
|
||
|
|
* this.image = asset.image;
|
||
|
|
* this.data = asset.data;
|
||
|
|
* }
|
||
|
|
* // entry point for starting async task, callback takes one argument
|
||
|
|
* // for the object we're returning
|
||
|
|
* start(callback) {
|
||
|
|
* const assets = {
|
||
|
|
* _image: this.image,
|
||
|
|
* _data: this.data
|
||
|
|
* }
|
||
|
|
* // base Task class has load and simpleLoad methods
|
||
|
|
* this.load(assets, (err, results) => {
|
||
|
|
* if (err) return callback(err);
|
||
|
|
* callback(null, new Spritesheet(results._image, results._data));
|
||
|
|
* });
|
||
|
|
* }
|
||
|
|
* }
|
||
|
|
*
|
||
|
|
* // Register with the loader module
|
||
|
|
* jibo.loader.register(SpritesheetTask, 50);
|
||
|
|
* // Note 50 is the priority, all built-in tasks are < 50, higher priority tasks
|
||
|
|
* // are tested before lower (more generalized) tasks
|
||
|
|
*
|
||
|
|
* @example <caption><h4>Custom Task Usage</h4></caption>
|
||
|
|
* const asset = {
|
||
|
|
* image: "spritesheet.png",
|
||
|
|
* data: "spritesheet_atlas.json"
|
||
|
|
* };
|
||
|
|
* jibo.loader.load(asset, function(err, spritesheet) {
|
||
|
|
* // spritesheet should be a Spritesheet object
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* @namespace jibo.loader
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Instance of the asset manager.
|
||
|
|
* @name jibo.loader#assetManager
|
||
|
|
* @type {jibo.loader.AssetManager}
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Handles any errors coming from the manager.
|
||
|
|
* @method jibo.loader#register
|
||
|
|
* @param {Function} TaskDefinition The class definition for a loader task.
|
||
|
|
* @param {int} [priority=0] The priority of the task. Higher priority tasks
|
||
|
|
* are run first and therefore should be more specific
|
||
|
|
* types of tasks. Lower priority tasks are more generalized.
|
||
|
|
* @return {jibo.loader} The loader namespace for chaining.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Performs simple load of a single file.
|
||
|
|
* @method jibo.loader#load
|
||
|
|
* @param {String} source The file to load.
|
||
|
|
* @param {jibo.loader.AssetManager~completeCallback} complete The completed callback with a single
|
||
|
|
* parameters result object.
|
||
|
|
* @param {jibo.loader.AssetManager~progressCallback} [progress=null] Callback percentage updates.
|
||
|
|
* @param {String} [cache=null] A cache id to save to the asset cache after load.
|
||
|
|
* @param {Object} [data] Optional data to pass along
|
||
|
|
* @param {Boolean} [remote=false] `true` to force remote download.
|
||
|
|
* @param {Number} [timeout=0] Number of milliseconds to timeout remote load.
|
||
|
|
* @param {String} [format] Force a format type, either:
|
||
|
|
* "image", "json", "xml", "css", "js", "svg", "text", or "html"
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Loads a single custom asset with options.
|
||
|
|
* @method jibo.loader#load
|
||
|
|
* @param {Object} asset The single asset resource to load, properties
|
||
|
|
* will depend on the type of asset loading.
|
||
|
|
* @param {jibo.loader.AssetManager~completeCallback} [asset.complete=null] Callback when finished.
|
||
|
|
* @param {String} [asset.id=null] The ID to attach to this asset.
|
||
|
|
* @param {String} [asset.cache=null] A cache id if the result should be cached for later.
|
||
|
|
* @param {Boolean} [asset.remote=false] `true` if the src should be loaded of http(s), `false` to auto-determine.
|
||
|
|
* @param {String} [asset.format] Force a format type, either:
|
||
|
|
* "image", "json", "xml", "css", "js", "svg", "text", or "html"
|
||
|
|
* @param {Number} [asset.timeout=0] Number of milliseconds to timeout remote load.
|
||
|
|
* @param {jibo.loader.AssetManager~completeCallback} [complete] The completed callback with a single
|
||
|
|
* parameters which is a result object. Will
|
||
|
|
* only use if `asset.complete` is undefined.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Loads a single file with options.
|
||
|
|
* @method jibo.loader#load
|
||
|
|
* @param {Object} asset The file resource to load.
|
||
|
|
* @param {String} asset.src The file to load.
|
||
|
|
* @param {String} [asset.cache=null] A cache id if the result should be cached for later.
|
||
|
|
* If string, then the name of the cache to use.
|
||
|
|
* @param {Boolean} [asset.remote=false] `true` if the src should be loaded of http(s), `false` to auto-determine.
|
||
|
|
* @param {String} [asset.format] Force a format type, either:
|
||
|
|
* "image", "json", "xml", "css", "js", "svg", "text", or "html"
|
||
|
|
* @param {Number} [asset.timeout=0] Number of milliseconds to timeout remote load.
|
||
|
|
* @param {jibo.loader.AssetManager~completeCallback} [asset.complete=null] Callback when finished.
|
||
|
|
* @param {jibo.loader.AssetManager~completeCallback} [complete] The completed callback with a single
|
||
|
|
* parameter which is a result object. Will
|
||
|
|
* only use if `asset.complete` is undefined.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Loads a map of multiple assets and return mapped result objects.
|
||
|
|
* @method jibo.loader#load
|
||
|
|
* @param {Object} assets Load a map of assets.
|
||
|
|
* @param {jibo.loader.AssetManager~completeCallback|object} [options] Callback where the only parameter is the
|
||
|
|
* map of the results by ID, or the collection of load options.
|
||
|
|
* @param {jibo.loader.AssetManager~completeCallback} [options.complete=null] The complete callback if using load options.
|
||
|
|
* @param {jibo.loader.Task~completeCallback} [options.taskDone=null] The callback when a single item is finished.
|
||
|
|
* @param {jibo.loader.AssetManager~progressCallback} [options.progress=null] Callback percentage updates.
|
||
|
|
* @param {Boolean} [options.cacheAll=false] `true` if tasks should be cached.
|
||
|
|
* @param {Number} [options.maxLoads=4] The maximum number of simultaneous loads, 0 to start all.
|
||
|
|
* @param {Boolean} [options.remoteAll=false] `true` to force remote calls on all assets.
|
||
|
|
* @param {Number} [options.timeoutAll=0] Number of milliseconds to timeout remote calls.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Loads a list of multiple assets and return array of result objects.
|
||
|
|
* @method jibo.loader#load
|
||
|
|
* @param {Array} assets The list of assets.
|
||
|
|
* If each object has a `id` the result will be a mapped object.
|
||
|
|
* @param {function|object} [options] Callback where the only parameter is the
|
||
|
|
* collection or map of the results, or the collection of load options.
|
||
|
|
* @param {jibo.loader.AssetManager~completeCallback} [options.complete=null] The complete callback if using load options.
|
||
|
|
* @param {jibo.loader.Task~completeCallback} [options.taskDone=null] The callback when a single item is finished.
|
||
|
|
* @param {jibo.loader.AssetManager~progressCallback} [options.progress=null] Callback percentage updates.
|
||
|
|
* @param {Boolean} [options.cacheAll=false] `true` if tasks should be cached.
|
||
|
|
* @param {Number} [options.maxLoads=4] The maximum number of simultaneous loads, 0 to start all.
|
||
|
|
* @param {Boolean} [options.remoteAll=false] `true` to force remote calls on all assets.
|
||
|
|
* @param {Number} [options.timeoutAll=0] Number of milliseconds to timeout remote calls.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Sets the base path to prepend to all loads.
|
||
|
|
* @name jibo.loader#basePath
|
||
|
|
* @type {String}
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Sets the base URL to prepend to all remote loads.
|
||
|
|
* @name jibo.loader#baseUrl
|
||
|
|
* @type {String}
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Unloads an asset or list of assets.
|
||
|
|
* @method jibo.loader#unload
|
||
|
|
* @param {jibo.loader.AssetToken|jibo.loader.AssetToken[]} assets The collection of asset ids or
|
||
|
|
* single asset id.
|
||
|
|
* @return {jibo.loader} The loader namespace for chaining.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Unloads all assets from the assets cache.
|
||
|
|
* @method jibo.loader#unloadAll
|
||
|
|
* @param {String} [cacheId] The specific cache to unload. Uses active cache if empty.
|
||
|
|
* @return {jibo.loader} The loader namespace for chaining.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Cancels all the current loads.
|
||
|
|
* @method jibo.loader#cancelAll
|
||
|
|
* @return {jibo.loader} The loader namespace for chaining.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Adds a new custom cache. This "bucket" can be unloaded later. If the cache already exists,
|
||
|
|
* nothing happens.
|
||
|
|
* @method jibo.loader#addCache
|
||
|
|
* @param {String} cacheId The unique ID for cache.
|
||
|
|
* @return {jibo.loader} The loader namespace for chaining.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set or get the currently active cache.
|
||
|
|
* @name jibo.loader#activeCache
|
||
|
|
* @type {String}
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set or get the default number of max simultaneous loads.
|
||
|
|
* @name jibo.loader#maxDefaultLoads
|
||
|
|
* @type {Number}
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Unloads all assets from the assets cache.
|
||
|
|
* @method jibo.loader#deleteCache
|
||
|
|
* @return {jibo.loader} The loader namespace for chaining.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Gets an asset from the cache by ID
|
||
|
|
* @method jibo.loader#cached
|
||
|
|
* @param {String} id The asset to fetch.
|
||
|
|
* @param {String} cacheId The cache to grab asset from, uses the active cache if empty.
|
||
|
|
* @return {any|null} The cached object or null if empty.
|
||
|
|
*/
|