musk-ox v5.0.2

Table of Contents

• Installation
• Initialization
• Signals and Events
• Step 1: Defining Assets to Load
• Step 2: Loading Assets
• Step 3: Fetching Assets

Installation

MuskOx is shipped as an ES6 module.

To install MuskOx through npm, simply use the following command:

$ npm install musk-ox

Initialization

To use MuskOx, simply import the module:

import MuskOx from './path/to/muskox.js';

and after that, a new instance can be initialized like so:

const ox = new MuskOx();

As of 5.0.0 the single crossOrigin initialization parameter has been replaced with an options object:

The MuskOx asset loading system is split into three steps: defining assets to load, initiating the load, and retrieving loaded assets.

Signals and Events

Before we get into usage, it helps to know how Musk Ox's event system works. Instead of using traditional events, MuskOx uses signals which don't rely on event names but objects that dispatch the signal with any data needed.

To respond to a signal, you have to use the signal's add method and then declare the function that you want to run when the signal is dispatched.

Currently MuskOx has the following available events:

onLoad

The onLoad signal is dispatched each time an asset is loaded and it contains the data of the asset that was loaded.

const onLoadResponse = (asset) => {
  console.log(asset); // Asset is the asset that was most recently loaded.
};

ox.onLoad.add(onLoadResponse);

onComplete

The onComplete signal is dispatched when all of the assets are loaded.

const onCompleteResponse = () => {
};

ox.onComplete.add(onCompleteResponse);

onError

The onError signal is dispatched if an asset encounters an error while loading and it contains the asset and error that was thrown.

const onErrorResponse = (asset, err) => {
  console.log(asset); // Asset is the asset that had trouble loading.
  console.log(err); // Err is the error that was thrown while loading the asset.
};

ox.onError.add(onErrorResponse);

onProgress

The onProgress signal is dispatched when the loading progress changes and it contains the current load percentage.

const onProgressResponse = (percent) => {
  console.log(percent); // Percent is the current loading percentage.
};

ox.onProgress.add(onProgressResponse);

Step 1: Defining Assets to Load

The first step in using MuskOx involves defining the assets that need to be loaded. As of current, MuskOx supports loading images, audio, video, text, binary, and JSON assets. Assets defined during the loading phase are set to a queue that will process when the start method is called.

image

Adds an image asset to the load queue.

ox.image('star', './images/star.png');

audio

Adds an audio asset to the load queue.

Using a single source:

ox.audio('podcast', './recordings/2019-01-01.m4a');

Using fallback sources:

ox.audio('podcast', ['./recordings/2019-01-01.m4a', './recordings/2019-01-01.wav']);

audioBuffer

Adds an audio asset to the load queue to load as an AudioBuffer.

ox.audioBuffer('podcast', './recordings/2019-01-01.m4a');

video

Adds a video asset to the load queue.

Using a single source:

ox.video('stream', './recordings/stardew-valley-1.m4a');

Using fallback sources:

ox.video('stream', ['./recordings/stardew-valley-1.mp4', './recordings/stardew-valley-1.webm']);

text

Adds a text asset to the load queue.

ox.text('bio', './documents/biography.txt');

binary

Adds a binary asset to the load queue. Any file provided to this will be turned into a binary format.

ox.binary('bio', './documents/biography.txt');

json

Adds a JSON asset to the load queue. The JSON will be stored as a parsed object.

ox.json('movies', './documents/favorite-movies.json');

arrayBuffer

Adds an asset to load as an array buffer.

ox.arrayBuffer('podcast', './podcasts/podcast-new.mp4');

Step 2: Start Loading

After defining all of the assets that need to be loaded, you have to tell MuskOx that you're ready for it to actually load all of the assets by calling the start method.

start

Starts the loading process and emits the load-complete event when finished.

ox.start();

Step 3: Using Loaded Assets

Since loading assets is an asynchronous action, you must wait until the load-complete event is emitted to ensure that all of the assets are loaded and ready to use.

Here is an example of how to listen to the load-complete event:

const complete = () => {

  // You can start using assets here.
  const star = ox.fetch.image('star');

  document.body.appendChild(star);

};

ox.onComplete.add(complete);

Retrieving assets from the cache is made possible through the fetch methods. By using the method that corresponds to the asset type and the asset key, you can easily retrieve any saved asset.

image

Get a saved image asset from the cache.

const star = ox.fetch.image('star');

audio

Get a saved audio asset from the cache.

const podcast = ox.fetch.audio('podcast');

audioBuffer

Get a saved audio buffer from the cache.

const podcast = ox.fetch.audioBuffer('podcast');

video

Get a saved video asset from the cache.

const stream = ox.fetch.video('stream');

text

Get a saved text asset from the cache.

const bio = ox.fetch.text('bio');

binary

Get a saved binary asset from the cache.

const bio = ox.fetch.binary('bio');

json

Get a saved JSON asset from the cache.

const movies = ox.fetch.json('movies');

arrayBuffer

Get a saved arrayBuffer from the cache.

const podcast = ox.fetch.arrayBuffer('podcast');

Properties

There are also a few properties that are available:

assetsLoaded

Gets the number of assets that have been loaded so far.

assetsToLoad

Gets the number of assets that have yet to be loaded.

progress

Gets the current loading progress as a percentage.

License

MIT