@vpmedia/phaser 1.15.0 → 1.17.0

package/src/phaser/core/loader.js

@@ -1,15 +1,15 @@
-/**
- * @copyright    Copyright (c) 2018-present Richard Davey, Photon Storm Ltd., Andras Csizmadia <andras@vpmedia.hu> (www.vpmedia.hu)
- * @author       Andras Csizmadia <andras@vpmedia.hu>
- * @author       Richard Davey <rich@photonstorm.com>
- */
-import { Signal } from  './signal';
-import { Rectangle } from  '../geom/rectangle';
+import { Signal } from './signal';
+import { Rectangle } from '../geom/rectangle';
 import { canPlayAudio } from './device_util';
+import { Game } from './game';
 
 const TEXTURE_ATLAS_JSON_HASH = 1;
 
 export class Loader {
+  /**
+   * TBD.
+   * @param {Game} game - TBD.
+   */
   constructor(game) {
     this.game = game;
     this.cache = game.cache;
@@ -45,6 +45,11 @@ export class Loader {
     this._loadedFileCount = 0;
   }
 
+  /**
+   * TBD.
+   * @param sprite - TBD.
+   * @param direction - TBD.
+   */
   setPreloadSprite(sprite, direction = 0) {
     this.preloadSprite = {
       sprite,
@@ -64,16 +69,31 @@ export class Loader {
     sprite.visible = true;
   }
 
+  /**
+   * TBD.
+   */
   resize() {
     if (this.preloadSprite && this.preloadSprite.height !== this.preloadSprite.sprite.height) {
       this.preloadSprite.rect.height = this.preloadSprite.sprite.height;
     }
   }
 
+  /**
+   * TBD.
+   * @param type - TBD.
+   * @param {string} key - TBD.
+   * @returns {boolean} TBD.
+   */
   checkKeyExists(type, key) {
     return this.getAssetIndex(type, key) > -1;
   }
 
+  /**
+   * TBD.
+   * @param type - TBD.
+   * @param {string} key - TBD.
+   * @returns {number} TBD.
+   */
   getAssetIndex(type, key) {
     let bestFound = -1;
     for (let i = 0; i < this._fileList.length; i += 1) {
@@ -90,6 +110,12 @@ export class Loader {
     return bestFound;
   }
 
+  /**
+   * TBD.
+   * @param type - TBD.
+   * @param {string} key - TBD.
+   * @returns {object} TBD.
+   */
   getAsset(type, key) {
     const fileIndex = this.getAssetIndex(type, key);
     if (fileIndex > -1) {
@@ -98,6 +124,11 @@ export class Loader {
     return null;
   }
 
+  /**
+   * TBD.
+   * @param hard
+   * @param clearEvents
+   */
   reset(hard, clearEvents = false) {
     if (hard) {
       this.preloadSprite = null;
@@ -121,14 +152,17 @@ export class Loader {
     }
   }
 
-  addToFileList(
-    type,
-    key = '',
-    url = null,
-    properties = null,
-    overwrite = false,
-    extension = null
-  ) {
+  /**
+   * TBD.
+   * @param type - TBD.
+   * @param {string} key - TBD.
+   * @param {string} url - TBD.
+   * @param properties - TBD.
+   * @param overwrite - TBD.
+   * @param extension - TBD.
+   * @returns {Loader} TBD.
+   */
+  addToFileList(type, key = '', url = null, properties = null, overwrite = false, extension = null) {
     if (key === undefined || key === '') {
       console.warn('Loader: Invalid or no key given of type ' + type);
       return this;
@@ -175,10 +209,26 @@ export class Loader {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param type - TBD.
+   * @param {string} key - TBD.
+   * @param {string} url - TBD.
+   * @param properties - TBD.
+   * @returns {Loader} TBD.
+   */
   replaceInFileList(type, key, url, properties) {
     return this.addToFileList(type, key, url, properties, true);
   }
 
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param {string} url - TBD.
+   * @param data - TBD.
+   * @param {object} callbackContext - TBD.
+   * @returns {Loader} TBD.
+   */
   pack(key, url, data, callbackContext) {
     const pack = {
       type: 'packfile',
@@ -210,10 +260,23 @@ export class Loader {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param {string} url - TBD.
+   * @param overwrite - TBD.
+   * @returns {Loader} TBD.
+   */
   image(key, url, overwrite) {
     return this.addToFileList('image', key, url, undefined, overwrite, '.png');
   }
 
+  /**
+   * TBD.
+   * @param keys - TBD.
+   * @param urls - TBD.
+   * @returns {Loader} TBD.
+   */
   images(keys, urls) {
     if (Array.isArray(urls)) {
       for (let i = 0; i < keys.length; i += 1) {
@@ -227,18 +290,50 @@ export class Loader {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param {string} url - TBD.
+   * @param overwrite - TBD.
+   * @returns {Loader} TBD.
+   */
   text(key, url, overwrite) {
     return this.addToFileList('text', key, url, undefined, overwrite, '.txt');
   }
 
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param {string} url - TBD.
+   * @param overwrite - TBD.
+   * @returns {Loader} TBD.
+   */
   json(key, url, overwrite) {
     return this.addToFileList('json', key, url, undefined, overwrite, '.json');
   }
 
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param {string} url - TBD.
+   * @param overwrite - TBD.
+   * @returns {Loader} TBD.
+   */
   xml(key, url, overwrite) {
     return this.addToFileList('xml', key, url, undefined, overwrite, '.xml');
   }
 
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param {string} url - TBD.
+   * @param frameWidth - TBD.
+   * @param frameHeight - TBD.
+   * @param frameMax - TBD.
+   * @param margin - TBD.
+   * @param spacing - TBD.
+   * @returns {Loader} TBD.
+   */
   spritesheet(key, url, frameWidth, frameHeight, frameMax = -1, margin = 0, spacing = 0) {
     return this.addToFileList(
       'spritesheet',
@@ -250,6 +345,13 @@ export class Loader {
     );
   }
 
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param urls
+   * @param autoDecode
+   * @returns {Loader} TBD.
+   */
   audio(key, urls, autoDecode = true) {
     if (this.game.sound.noAudio) {
       return this;
@@ -260,6 +362,15 @@ export class Loader {
     return this.addToFileList('audio', key, urls, { buffer: null, autoDecode });
   }
 
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param urls - TBD.
+   * @param jsonURL - TBD.
+   * @param jsonData - TBD.
+   * @param autoDecode - TBD.
+   * @returns {Loader} TBD.
+   */
   audioSprite(key, urls, jsonURL, jsonData, autoDecode = true) {
     if (this.game.sound.noAudio) {
       return this;
@@ -276,14 +387,18 @@ export class Loader {
     return this;
   }
 
-  bitmapFont(
-    key,
-    textureURL = null,
-    atlasURL = null,
-    atlasData = null,
-    xSpacing = 0,
-    ySpacing = 0
-  ) {
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param textureURL - TBD.
+   * @param atlasURL - TBD.
+   * @param atlasData - TBD.
+   * @param xSpacing - TBD.
+   * @param ySpacing - TBD.
+   * @returns {Loader} TBD.
+   * @throws Error.
+   */
+  bitmapFont(key, textureURL = null, atlasURL = null, atlasData = null, xSpacing = 0, ySpacing = 0) {
     if (textureURL === undefined || textureURL === null) {
       textureURL = key + '.png';
     }
@@ -316,6 +431,15 @@ export class Loader {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param {string} key - TBD.
+   * @param textureURL - TBD.
+   * @param atlasURL - TBD.
+   * @param atlasData - TBD.
+   * @param format - TBD.
+   * @returns {Loader} TBD.
+   */
   atlas(key, textureURL, atlasURL = null, atlasData = null, format = TEXTURE_ATLAS_JSON_HASH) {
     if (textureURL === undefined || textureURL === null) {
       textureURL = key + '.png';
@@ -332,6 +456,12 @@ export class Loader {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param {Function} callback - TBD.
+   * @param {object} callbackContext - TBD.
+   * @returns {Loader} TBD.
+   */
   withSyncPoint(callback, callbackContext) {
     this._withSyncPointDepth += 1;
     try {
@@ -342,6 +472,12 @@ export class Loader {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param type - TBD.
+   * @param {string} key - TBD.
+   * @returns {Loader} TBD.
+   */
   addSyncPoint(type, key) {
     const asset = this.getAsset(type, key);
     if (asset) {
@@ -350,6 +486,11 @@ export class Loader {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param type - TBD.
+   * @param {string} key - TBD.
+   */
   removeFile(type, key) {
     const asset = this.getAsset(type, key);
     if (asset) {
@@ -359,11 +500,17 @@ export class Loader {
     }
   }
 
+  /**
+   * TBD.
+   */
   removeAll() {
     this._fileList.length = 0;
     this._flightQueue.length = 0;
   }
 
+  /**
+   * TBD.
+   */
   start() {
     if (this.isLoading) {
       return;
@@ -374,6 +521,9 @@ export class Loader {
     this.processLoadQueue();
   }
 
+  /**
+   * TBD.
+   */
   processLoadQueue() {
     if (!this.isLoading) {
       console.warn('Loader - active loading canceled / reset');
@@ -404,12 +554,7 @@ export class Loader {
         } else if (file.type === 'packfile' && file.error) {
           // Non-error pack files are handled when processing the file queue
           this._loadedPackCount += 1;
-          this.onPackComplete.dispatch(
-            file.key,
-            !file.error,
-            this._loadedPackCount,
-            this._totalPackCount
-          );
+          this.onPackComplete.dispatch(file.key, !file.error, this._loadedPackCount, this._totalPackCount);
         }
       }
     }
@@ -423,12 +568,7 @@ export class Loader {
         // Processing the pack / adds more files
         this.processPack(file);
         this._loadedPackCount += 1;
-        this.onPackComplete.dispatch(
-          file.key,
-          !file.error,
-          this._loadedPackCount,
-          this._totalPackCount
-        );
+        this.onPackComplete.dispatch(file.key, !file.error, this._loadedPackCount, this._totalPackCount);
       }
       if (file.loaded || file.error) {
         // Item at the start of file list finished, can skip it in future
@@ -459,10 +599,7 @@ export class Loader {
       }
       // Stop looking if queue full - or if syncblocked and there are no more packs.
       // (As only packs can be loaded around a syncblock)
-      if (
-        this._flightQueue.length >= inflightLimit ||
-        (syncblock && this._loadedPackCount === this._totalPackCount)
-      ) {
+      if (this._flightQueue.length >= inflightLimit || (syncblock && this._loadedPackCount === this._totalPackCount)) {
         break;
       }
     }
@@ -482,6 +619,10 @@ export class Loader {
     }
   }
 
+  /**
+   * TBD.
+   * @param abnormal - TBD.
+   */
   finishedLoading(abnormal) {
     if (this.hasLoaded) {
       return;
@@ -501,6 +642,11 @@ export class Loader {
     // this.reset();
   }
 
+  /**
+   * TBD.
+   * @param file - TBD.
+   * @param errorMessage - TBD.
+   */
   asyncComplete(file, errorMessage = '') {
     file.loaded = true;
     file.error = !!errorMessage;
@@ -512,6 +658,10 @@ export class Loader {
     this.processLoadQueue();
   }
 
+  /**
+   * TBD.
+   * @param pack - TBD.
+   */
   processPack(pack) {
     const packData = pack.data[pack.key];
     if (!packData) {
@@ -565,18 +715,18 @@ export class Loader {
           );
           break;
         case 'atlas':
-          this.atlas(
-            file.key,
-            file.textureURL,
-            file.atlasURL,
-            file.atlasData,
-            TEXTURE_ATLAS_JSON_HASH
-          );
+          this.atlas(file.key, file.textureURL, file.atlasURL, file.atlasData, TEXTURE_ATLAS_JSON_HASH);
           break;
       }
     }
   }
 
+  /**
+   * TBD.
+   * @param {string} url - TBD.
+   * @param file - TBD.
+   * @returns {string} TBD.
+   */
   transformUrl(url, file) {
     if (!url) {
       return false;
@@ -587,6 +737,10 @@ export class Loader {
     return this.baseURL + file.path + url;
   }
 
+  /**
+   * TBD.
+   * @param file - TBD.
+   */
   loadFile(file) {
     switch (file.type) {
       case 'packfile':
@@ -603,11 +757,7 @@ export class Loader {
         if (file.url) {
           this.xhrLoad(file, this.transformUrl(file.url, file), 'arraybuffer', this.fileComplete);
         } else {
-          this.fileError(
-            file,
-            null,
-            'No supported audio URL specified or device does not have audio playback support'
-          );
+          this.fileError(file, null, 'No supported audio URL specified or device does not have audio playback support');
         }
         break;
       case 'json':
@@ -625,6 +775,10 @@ export class Loader {
     }
   }
 
+  /**
+   * TBD.
+   * @param file - TBD.
+   */
   loadImageTag(file) {
     this.log('loadImageTag', file);
     const scope = this;
@@ -653,6 +807,14 @@ export class Loader {
     file.data.src = this.transformUrl(file.url, file);
   }
 
+  /**
+   * TBD.
+   * @param file - TBD.
+   * @param {string} url - TBD.
+   * @param type - TBD.
+   * @param onload - TBD.
+   * @param onerror - TBD.
+   */
   xhrLoad(file, url, type, onload, onerror) {
     this.log('xhrLoad', file);
     const scope = this;
@@ -712,11 +874,19 @@ export class Loader {
     xhr.send();
   }
 
+  /**
+   * TBD.
+   */
   xhrLoadWithXDR() {
     // TODO
     console.warn('loader.xhrLoadWithXDR() is not implemented');
   }
 
+  /**
+   * TBD.
+   * @param urls - TBD.
+   * @returns {string} TBD.
+   */
   getAudioURL(urls) {
     if (this.game.sound.noAudio) {
       return null;
@@ -750,6 +920,12 @@ export class Loader {
     return null;
   }
 
+  /**
+   * TBD.
+   * @param file - TBD.
+   * @param xhr - TBD.
+   * @param reason - TBD.
+   */
   fileError(file, xhr, reason) {
     // const url = file.requestUrl || this.transformUrl(file.url, file);
     let message = 'Error loading asset';
@@ -762,6 +938,12 @@ export class Loader {
     this.asyncComplete(file, message);
   }
 
+  /**
+   * TBD.
+   * @param file - TBD.
+   * @param xhr - TBD.
+   * @throws Error.
+   */
   fileComplete(file, xhr) {
     let loadNext = true;
     switch (file.type) {
@@ -790,12 +972,7 @@ export class Loader {
         } else {
           loadNext = false;
           if (file.format === TEXTURE_ATLAS_JSON_HASH) {
-            this.xhrLoad(
-              file,
-              this.transformUrl(file.atlasURL, file),
-              'text',
-              this.jsonLoadComplete
-            );
+            this.xhrLoad(file, this.transformUrl(file.atlasURL, file), 'text', this.jsonLoadComplete);
           } else {
             throw new Error('Invalid Texture Atlas format: ' + file.format);
           }
@@ -815,27 +992,22 @@ export class Loader {
         } else {
           //  Load the XML before carrying on with the next file
           loadNext = false;
-          this.xhrLoad(
-            file,
-            this.transformUrl(file.atlasURL, file),
-            'text',
-            (bitmapFontFile, bitmapFontXhr) => {
-              let json;
-              try {
-                // Try to parse as JSON, if it fails, then it's hopefully XML
-                json = JSON.parse(bitmapFontXhr.responseText);
-              } catch (e) {
-                // pass
-              }
-              if (json) {
-                bitmapFontFile.atlasType = 'json';
-                this.jsonLoadComplete(bitmapFontFile, bitmapFontXhr);
-              } else {
-                bitmapFontFile.atlasType = 'xml';
-                this.xmlLoadComplete(bitmapFontFile, bitmapFontXhr);
-              }
+          this.xhrLoad(file, this.transformUrl(file.atlasURL, file), 'text', (bitmapFontFile, bitmapFontXhr) => {
+            let json;
+            try {
+              // Try to parse as JSON, if it fails, then it's hopefully XML
+              json = JSON.parse(bitmapFontXhr.responseText);
+            } catch (e) {
+              // pass
             }
-          );
+            if (json) {
+              bitmapFontFile.atlasType = 'json';
+              this.jsonLoadComplete(bitmapFontFile, bitmapFontXhr);
+            } else {
+              bitmapFontFile.atlasType = 'xml';
+              this.xmlLoadComplete(bitmapFontFile, bitmapFontXhr);
+            }
+          });
         }
         break;
       case 'audio':
@@ -858,18 +1030,15 @@ export class Loader {
     }
   }
 
+  /**
+   * TBD.
+   * @param file - TBD.
+   * @param xhr - TBD.
+   */
   jsonLoadComplete(file, xhr) {
     const data = JSON.parse(xhr.responseText);
     if (file.type === 'bitmapfont') {
-      this.cache.addBitmapFont(
-        file.key,
-        file.url,
-        file.data,
-        data,
-        file.atlasType,
-        file.xSpacing,
-        file.ySpacing
-      );
+      this.cache.addBitmapFont(file.key, file.url, file.data, data, file.atlasType, file.xSpacing, file.ySpacing);
     } else if (file.type === 'json') {
       this.cache.addJSON(file.key, file.url, data);
     } else {
@@ -878,11 +1047,19 @@ export class Loader {
     this.asyncComplete(file);
   }
 
+  /**
+   * TBD.
+   */
   csvLoadComplete() {
     // TODO
     console.warn('loader.csvLoadComplete() is not implemented');
   }
 
+  /**
+   * TBD.
+   * @param file - TBD.
+   * @param xhr - TBD.
+   */
   xmlLoadComplete(file, xhr) {
     // Always try parsing the content as XML, regardless of actually response type
     const data = xhr.responseText;
@@ -894,15 +1071,7 @@ export class Loader {
       return;
     }
     if (file.type === 'bitmapfont') {
-      this.cache.addBitmapFont(
-        file.key,
-        file.url,
-        file.data,
-        xml,
-        file.atlasType,
-        file.xSpacing,
-        file.ySpacing
-      );
+      this.cache.addBitmapFont(file.key, file.url, file.data, xml, file.atlasType, file.xSpacing, file.ySpacing);
     } else if (file.type === 'textureatlas') {
       this.cache.addTextureAtlas(file.key, file.url, file.data, xml, file.format);
     } else if (file.type === 'xml') {
@@ -911,6 +1080,11 @@ export class Loader {
     this.asyncComplete(file);
   }
 
+  /**
+   * TBD.
+   * @param data - TBD.
+   * @returns {Document} TBD.
+   */
   parseXml(data) {
     let xml = null;
     try {
@@ -932,16 +1106,15 @@ export class Loader {
     return xml;
   }
 
+  /**
+   * TBD.
+   */
   updateProgress() {
     if (this.preloadSprite) {
       if (this.preloadSprite.direction === 0) {
-        this.preloadSprite.rect.width = Math.floor(
-          (this.preloadSprite.width / 100) * this.progress
-        );
+        this.preloadSprite.rect.width = Math.floor((this.preloadSprite.width / 100) * this.progress);
       } else {
-        this.preloadSprite.rect.height = Math.floor(
-          (this.preloadSprite.height / 100) * this.progress
-        );
+        this.preloadSprite.rect.height = Math.floor((this.preloadSprite.height / 100) * this.progress);
       }
       if (this.preloadSprite.sprite) {
         this.preloadSprite.sprite.updateCrop();
@@ -952,6 +1125,11 @@ export class Loader {
     }
   }
 
+  /**
+   * TBD.
+   * @param message - TBD.
+   * @param data - TBD.
+   */
   log(message, data = '') {
     if (!this.isUseLog) {
       return;
@@ -959,27 +1137,51 @@ export class Loader {
     console.log(`[Loader] ${message}`, data);
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   totalLoadedFiles() {
     return this._loadedFileCount;
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   totalQueuedFiles() {
     return this._totalFileCount - this._loadedFileCount;
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   totalLoadedPacks() {
     return this._totalPackCount;
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   totalQueuedPacks() {
     return this._totalPackCount - this._loadedPackCount;
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get progressFloat() {
     const progress = (this._loadedFileCount / this._totalFileCount) * 100;
     return Math.max(0, Math.min(100, progress || 0));
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get progress() {
     return Math.round(this.progressFloat);
   }