# 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
});
```