244 lines
6.7 KiB
Markdown
244 lines
6.7 KiB
Markdown
# Overview
|
|
|
|
The purpose of this Loader module is to:
|
|
|
|
* Provide an easy way to asynchronously load multiple asset via a JSON list
|
|
* Use NodeJS's **fs** module for loading assets instead of XMLHttpRequest
|
|
* Remove the dependencies on SpringRoll for loading of assets
|
|
|
|
### Usage
|
|
|
|
#### Loading a Single File
|
|
```js
|
|
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
|
|
});
|
|
```
|
|
|
|
#### Loading Multiple files
|
|
```js
|
|
const jibo = require('jibo');
|
|
const assets = [
|
|
"logo.png",
|
|
"header.jpg"
|
|
];
|
|
jibo.loader.load(assets, function(err, results) {
|
|
// results is an Array of HTMLImageElements
|
|
});
|
|
```
|
|
|
|
```js
|
|
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
|
|
});
|
|
```
|
|
|
|
#### Caching Assets
|
|
|
|
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.
|
|
|
|
```js
|
|
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
|
|
});
|
|
```
|
|
#### Options for Multiple Loading
|
|
|
|
```js
|
|
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
|
|
});
|
|
```
|
|
|
|
|
|
#### Return Types
|
|
|
|
| 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`_ |
|
|
|
|
|
|
#### Assets
|
|
|
|
**General asset**
|
|
|
|
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.
|
|
|
|
```js
|
|
{
|
|
src: "file.txt", // path to file
|
|
cache: false, // save to cache
|
|
id: "file-ref", // cache key
|
|
complete: function(result){}, // returns
|
|
}
|
|
```
|
|
|
|
**Color-Alpha asset**
|
|
|
|
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.
|
|
|
|
```js
|
|
{
|
|
src: "color.jpg", // path to file
|
|
alpha: "color-alpha.png", // alpha
|
|
complete: function(err, img){}, // returns HTMLImageElement
|
|
}
|
|
```
|
|
|
|
**Texture Asset**
|
|
|
|
By default, loading images returns an HTMLImageElement. To return a PIXI.Texture object, you can used the Texture Asset. Noticed the required field `type`.
|
|
|
|
```js
|
|
{
|
|
src: "logo.png",
|
|
type: "texture", // required
|
|
upload: false, // upload to GPU when finished downloading
|
|
complete: function(err, texture){} // returns PIXI.Texture object
|
|
}
|
|
```
|
|
**Keys Asset**
|
|
|
|
Preload a keys file and any assets (sounds or timelines) that it uses.
|
|
|
|
```js
|
|
{
|
|
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
|
|
}
|
|
```
|
|
|
|
**Timeline Asset**
|
|
|
|
Preload a PixiAnimate animation. Will preload any assets used by the timeline (shapes & images).
|
|
|
|
```js
|
|
{
|
|
src: "my-animation.js",
|
|
type: "timeline", // required
|
|
complete: function(err, timeline){} // returns jibo.rendering.animation.Timeline object
|
|
}
|
|
```
|
|
|
|
**Sound Asset**
|
|
|
|
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")`.
|
|
|
|
```js
|
|
{
|
|
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
|
|
}
|
|
```
|
|
|
|
**Function Asset**
|
|
|
|
A function can be used as an asset like any other. This requires `done` to be called. Optionally an result can be passed as the first argument to `done` and this will be used as the cached result.
|
|
|
|
```js
|
|
function(err, done)
|
|
{
|
|
// do some async things here
|
|
done();
|
|
}
|
|
```
|
|
|
|
#### Unloading
|
|
|
|
```js
|
|
const assets = [
|
|
{ id:'logo', src: "logo.png", cache: true },
|
|
{ id: 'header', src: "header.jpg", cache: true }
|
|
];
|
|
jibo.loader.unload(assets);
|
|
jibo.loader.unload('logo', 'header'); // alternatively, remove by IDs
|
|
jibo.loader.unloadAll(); // remove all assets
|
|
```
|
|
|
|
#### Custom Task
|
|
|
|
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:
|
|
|
|
```js
|
|
// 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
|
|
```
|
|
|
|
**Usage**
|
|
|
|
```js
|
|
const asset = {
|
|
image: "spritesheet.png",
|
|
data: "spritesheet_atlas.json"
|
|
};
|
|
jibo.loader.load(asset, function(err, spritesheet) {
|
|
// spritesheet should be a Spritesheet object
|
|
});
|
|
```
|