Merge d500c9e into 0d312bd

src/assets.js

@@ -1,8 +1,18 @@
+import { emit } from './events.js'
+
 /**
- * A promise based asset loader for loading images, audio, and data files.
+ * A promise based asset loader for loading images, audio, and data files. An `assetLoaded` event is emitted after each asset is fully loaded. The callback for the event is passed the asset and the url to the asset as parameters.
  *
  * ```js
- * import { load } from 'kontra';
+ * import { load, on } from 'kontra';
+ *
+ * let numAssets = 3;
+ * let assetsLoaded = 0;
+ * on('assetLoaded', (asset, url) => {
+ *   assetsLoaded++;
+ *
+ *   // inform user or update progress bar
+ * });
  *
  * load(
  *   'assets/imgs/character.png',
@@ -264,6 +274,7 @@ export function loadImage(url) {
     image.onload = function loadImageOnLoad() {
       fullUrl = getUrl(resolvedUrl, window.location.href);
       imageAssets[ getName(url) ] = imageAssets[resolvedUrl] = imageAssets[fullUrl] = this;
+      emit('assetLoaded', this, url);
       resolve(this);
     };
 
@@ -324,6 +335,7 @@ export function loadAudio(url) {
     audioEl.addEventListener('canplay', function loadAudioOnLoad() {
       fullUrl = getUrl(resolvedUrl, window.location.href);
       audioAssets[ getName(url) ] = audioAssets[resolvedUrl] = audioAssets[fullUrl] = this;
+      emit('assetLoaded', this, url);
       resolve(this);
     });
 
@@ -371,6 +383,7 @@ export function loadData(url) {
     }
 
     dataAssets[ getName(url) ] = dataAssets[resolvedUrl] = dataAssets[fullUrl] = response;
+    emit('assetLoaded', response, url);
     return response;
   });
 }

src/events.js

@@ -1,5 +1,5 @@
 /**
- * A simple event system, mostly created to support [Plugins](api/plugin). Allows you to hook into Kontra lifecycle events or create your own.
+ * A simple event system. Allows you to hook into Kontra lifecycle events or create your own, such as for [Plugins](api/plugin).
  *
  * ```js
  * import { on, off, emit } from 'kontra';
@@ -19,9 +19,10 @@
 export let callbacks = {};
 
 /**
- * There are currently only two lifecycle events:
- * - `init` - Emitted after `init()` is called.
+ * There are currently only three lifecycle events:
+ * - `init` - Emitted after `konta.init()` is called.
  * - `tick` - Emitted every frame of kontra.GameLoop before the loops `update()` and `render()` functions are called.
+ * - `assetLoaded` - Emitted after an asset has fully loaded using the asset loader. The callback function is passed the asset and the url of the asset as parameters.
  * @sectionName Lifecycle Events
  */
 

test/unit/assets.spec.js

@@ -1,4 +1,5 @@
 import * as assets from '../../src/assets.js'
+import { on, off } from '../../src/events.js'
 
 // --------------------------------------------------
 // assets
@@ -101,6 +102,25 @@ describe('assets', () => {
       });
     });
 
+    it('should emit the assetLoaded event', done => {
+      function loaded(asset, url) {
+        // this needs to be called first otherwise every load event will call this
+        // emitted function
+        off('assetLoaded', loaded);
+
+        try {
+          expect(assets.imageAssets['/imgs/bullet.png']).to.equal(asset);
+          expect(url).to.equal('/imgs/bullet.png');
+        } catch(e) {
+          done(e);
+        }
+
+        done();
+      }
+      on('assetLoaded', loaded);
+      assets.loadImage('/imgs/bullet.png').catch(done);
+    });
+
   });
 
 
@@ -186,6 +206,25 @@ describe('assets', () => {
       });
     });
 
+    it('should emit the assetLoaded event', done => {
+      function loaded(asset, url) {
+        // this needs to be called first otherwise every load event will call this
+        // emitted function
+        off('assetLoaded', loaded);
+
+        try {
+          expect(assets.dataAssets['/data/test.txt']).to.equal(asset);
+          expect(url).to.equal('/data/test.txt');
+        } catch(e) {
+          return done(e);
+        }
+
+        done();
+      }
+      on('assetLoaded', loaded);
+      assets.loadData('/data/test.txt').catch(done);
+    });
+
   });
 
 
@@ -317,6 +356,25 @@ describe('assets', () => {
       });
     });
 
+    it('should emit the assetLoaded event', done => {
+      function loaded(asset, url) {
+        // this needs to be called first otherwise every load event will call this
+        // emitted function
+        off('assetLoaded', loaded);
+
+        try {
+          expect(assets.audioAssets['/audio/shoot.mp3']).to.equal(asset);
+          expect(url).to.equal('/audio/shoot.mp3');
+        } catch(e) {
+          done(e);
+        }
+
+        done();
+      }
+      on('assetLoaded', loaded);
+      assets.loadAudio('/audio/shoot.mp3').catch(done);
+    });
+
   });