MuskOx

MuskOx is an easy to use, event-driven, and efficient asset preloader for the browser.

Installation

MuskOx is shipped as an ES6 module.

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

$ npm install musk-ox

Usage

To use MuskOx, simply import the module:

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

Initialization

After importing MuskOx, a new instance can be initialized like so:

const ox = new MuskOx();

There is also currently one initialization parameter that allows you to specify a global cross origin policy for loading images from an external source. This is useful if you have a lot of assets coming from a single external source. If no value is specified, then it is left null and not used.

Usage

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

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']);

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');

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:

ox.on('load-complete', () => {

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

	document.body.appendChild(star);

});

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');

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');

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