jsdocs update

Author: photonstorm

src/loader/filetypes/AnimationJSONFile.js

@@ -78,9 +78,25 @@ var AnimationJSONFile = new Class({
 /**
  * Adds an Animation JSON Data file, or array of Animation JSON files, to the current load queue.
  *
- * The file is **not** loaded immediately, it is added to a queue ready to be loaded either when the loader starts,
- * or if it's already running, when the next free load slot becomes available. This means you cannot use the file
- * immediately after calling this method, but instead must wait for the file to complete.
+ * You can call this method from within your Scene's `preload`, along with any other files you wish to load:
+ * 
+ * ```javascript
+ * function preload ()
+ * {
+ *     this.load.animation('baddieAnims', 'files/BaddieAnims.json');
+ * }
+ * ```
+ *
+ * The file is **not** loaded right away. It is added to a queue ready to be loaded either when the loader starts,
+ * or if it's already running, when the next free load slot becomes available. This happens automatically if you
+ * are calling this from within the Scene's `preload` method, or a related callback. Because the file is queued
+ * it means you cannot use the file immediately after calling this method, but must wait for the file to complete.
+ * The typical flow for a Phaser Scene is that you load assets in the Scene's `preload` method and then when the
+ * Scene's `create` method is called you are guaranteed that all of those assets are ready for use and have been
+ * loaded.
+ * 
+ * If you call this from outside of `preload` then you are responsible for starting the Loader afterwards and monitoring
+ * its events to know when it's safe to use the asset. Please see the Phaser.Loader.LoaderPlugin class for more details.
  * 
  * The key must be a unique String. It is used to add the file to the global JSON Cache upon a successful load.
  * The key should be unique both in terms of files being loaded and files already present in the JSON Cache.

src/loader/filetypes/AtlasJSONFile.js

@@ -125,7 +125,7 @@ var AtlasJSONFile = new Class({
  * Adds a JSON based Texture Atlas, or array of atlases, to the current load queue.
  *
  * You can call this method from within your Scene's `preload`, along with any other files you wish to load:
-
+ * 
  * ```javascript
  * function preload ()
  * {

src/loader/filetypes/AtlasXMLFile.js

@@ -122,7 +122,7 @@ var AtlasXMLFile = new Class({
  * Adds an XML based Texture Atlas, or array of atlases, to the current load queue.
  *
  * You can call this method from within your Scene's `preload`, along with any other files you wish to load:
-
+ * 
  * ```javascript
  * function preload ()
  * {

src/loader/filetypes/BinaryFile.js

@@ -99,9 +99,22 @@ var BinaryFile = new Class({
 /**
  * Adds a Binary file, or array of Binary files, to the current load queue.
  *
- * The file is **not** loaded immediately, it is added to a queue ready to be loaded either when the loader starts,
- * or if it's already running, when the next free load slot becomes available. This means you cannot use the file
- * immediately after calling this method, but instead must wait for the file to complete.
+ * You can call this method from within your Scene's `preload`, along with any other files you wish to load:
+ * 
+ * ```javascript
+ * function preload ()
+ * {
+ *     this.load.binary('doom', 'files/Doom.wad');
+ * }
+ * ```
+ *
+ * The file is **not** loaded right away. It is added to a queue ready to be loaded either when the loader starts,
+ * or if it's already running, when the next free load slot becomes available. This happens automatically if you
+ * are calling this from within the Scene's `preload` method, or a related callback. Because the file is queued
+ * it means you cannot use the file immediately after calling this method, but must wait for the file to complete.
+ * The typical flow for a Phaser Scene is that you load assets in the Scene's `preload` method and then when the
+ * Scene's `create` method is called you are guaranteed that all of those assets are ready for use and have been
+ * loaded.
  * 
  * The key must be a unique String. It is used to add the file to the global Binary Cache upon a successful load.
  * The key should be unique both in terms of files being loaded and files already present in the Binary Cache.
@@ -113,7 +126,8 @@ var BinaryFile = new Class({
  * ```javascript
  * this.load.binary({
  *     key: 'doom',
- *     url: 'files/Doom.wad'
+ *     url: 'files/Doom.wad',
+ *     dataType: Uint8Array
  * });
  * ```
  *

src/loader/filetypes/BitmapFontFile.js

@@ -13,48 +13,95 @@ var MultiFile = require('../MultiFile.js');
 var ParseXMLBitmapFont = require('../../gameobjects/bitmaptext/ParseXMLBitmapFont.js');
 var XMLFile = require('./XMLFile.js');
 
+/**
+ * @typedef {object} Phaser.Loader.FileTypes.BitmapFontFileConfig
+ *
+ * @property {string} key - The key of the file. Must be unique within both the Loader and the Texture Manager.
+ * @property {string} [textureURL] - The absolute or relative URL to load the texture image file from.
+ * @property {string} [textureExtension='png'] - The default file extension to use for the image texture if no url is provided.
+ * @property {XHRSettingsObject} [textureXhrSettings] - Extra XHR Settings specifically for the texture image file.
+ * @property {string} [normalMap] - The filename of an associated normal map. It uses the same path and url to load as the texture image.
+ * @property {string} [fontDataURL] - The absolute or relative URL to load the font data xml file from.
+ * @property {string} [fontDataExtension='xml'] - The default file extension to use for the font data xml if no url is provided.
+ * @property {XHRSettingsObject} [fontDataXhrSettings] - Extra XHR Settings specifically for the font data xml file.
+ */
+
 /**
  * @classdesc
- * An Bitmap Font File.
+ * A single Bitmap Font based File suitable for loading by the Loader.
+ *
+ * These are created when you use the Phaser.Loader.LoaderPlugin#bitmapFont method and are not typically created directly.
+ * 
+ * For documentation about what all the arguments and configuration options mean please see Phaser.Loader.LoaderPlugin#bitmapFont.
  *
  * @class BitmapFontFile
  * @extends Phaser.Loader.MultiFile
  * @memberOf Phaser.Loader.FileTypes
  * @constructor
  * @since 3.0.0
  *
- * @param {string} key - The key of the file within the loader.
- * @param {string} textureURL - The url to load the texture file from.
- * @param {string} xmlURL - The url to load the atlas file from.
- * @param {string} path - The path of the file.
- * @param {XHRSettingsObject} [textureXhrSettings] - Optional texture file specific XHR settings.
- * @param {XHRSettingsObject} [xmlXhrSettings] - Optional atlas file specific XHR settings.
+ * @param {Phaser.Loader.LoaderPlugin} loader - A reference to the Loader that is responsible for this file.
+ * @param {(string|Phaser.Loader.FileTypes.BitmapFontFileConfig)} key - The key to use for this file, or a file configuration object.
+ * @param {string|string[]} [textureURL] - The absolute or relative URL to load the font image file from. If undefined or `null` it will be set to `<key>.png`, i.e. if `key` was "alien" then the URL will be "alien.png".
+ * @param {string} [fontDataURL] - The absolute or relative URL to load the font xml data file from. If undefined or `null` it will be set to `<key>.xml`, i.e. if `key` was "alien" then the URL will be "alien.xml".
+ * @param {XHRSettingsObject} [textureXhrSettings] - An XHR Settings configuration object for the font image file. Used in replacement of the Loaders default XHR Settings.
+ * @param {XHRSettingsObject} [fontDataXhrSettings] - An XHR Settings configuration object for the font data xml file. Used in replacement of the Loaders default XHR Settings.
  */
 var BitmapFontFile = new Class({
 
     Extends: MultiFile,
 
     initialize:
 
-    function BitmapFontFile (loader, key, textureURL, xmlURL, textureXhrSettings, xmlXhrSettings)
+    function BitmapFontFile (loader, key, textureURL, fontDataURL, textureXhrSettings, fontDataXhrSettings)
     {
+        var image;
+        var data;
+
         if (IsPlainObject(key))
         {
             var config = key;
 
             key = GetFastValue(config, 'key');
-            textureURL = GetFastValue(config, 'textureURL');
-            xmlURL = GetFastValue(config, 'xmlURL');
-            textureXhrSettings = GetFastValue(config, 'textureXhrSettings');
-            xmlXhrSettings = GetFastValue(config, 'xmlXhrSettings');
-        }
 
-        var image = new ImageFile(loader, key, textureURL, textureXhrSettings);
-        var data = new XMLFile(loader, key, xmlURL, xmlXhrSettings);
+            image = new ImageFile(loader, {
+                key: key,
+                url: GetFastValue(config, 'textureURL'),
+                extension: GetFastValue(config, 'textureExtension', 'png'),
+                normalMap: GetFastValue(config, 'normalMap'),
+                xhrSettings: GetFastValue(config, 'textureXhrSettings')
+            });
+
+            data = new XMLFile(loader, {
+                key: key,
+                url: GetFastValue(config, 'fontDataURL'),
+                extension: GetFastValue(config, 'fontDataExtension', 'xml'),
+                xhrSettings: GetFastValue(config, 'fontDataXhrSettings')
+            });
+        }
+        else
+        {
+            image = new ImageFile(loader, key, textureURL, textureXhrSettings);
+            data = new XMLFile(loader, key, fontDataURL, fontDataXhrSettings);
+        }
 
-        MultiFile.call(this, loader, 'bitmapfont', key, [ image, data ]);
+        if (image.linkFile)
+        {
+            //  Image has a normal map
+            MultiFile.call(this, loader, 'bitmapfont', key, [ image, data, image.linkFile ]);
+        }
+        else
+        {
+            MultiFile.call(this, loader, 'bitmapfont', key, [ image, data ]);
+        }
     },
 
+    /**
+     * Adds this file to its target cache upon successful loading and processing.
+     *
+     * @method Phaser.Loader.FileTypes.BitmapFontFile#addToCache
+     * @since 3.7.0
+     */
     addToCache: function ()
     {
         if (this.isReadyToProcess())
@@ -65,7 +112,7 @@ var BitmapFontFile = new Class({
             image.addToCache();
             xml.addToCache();
 
-            this.loader.cacheManager.bitmapFont.add(image.key, {data: ParseXMLBitmapFont(xml.data), texture: image.key, frame: null});
+            this.loader.cacheManager.bitmapFont.add(image.key, { data: ParseXMLBitmapFont(xml.data), texture: image.key, frame: null });
 
             this.complete = true;
         }
@@ -74,25 +121,106 @@ var BitmapFontFile = new Class({
 });
 
 /**
- * Adds a Bitmap Font file to the current load queue.
+ * Adds an XML based Bitmap Font, or array of fonts, to the current load queue.
+ *
+ * You can call this method from within your Scene's `preload`, along with any other files you wish to load:
+
+ * ```javascript
+ * function preload ()
+ * {
+ *     this.load.bitmapFont('goldenFont', 'images/GoldFont.png', 'images/GoldFont.xml');
+ * }
+ * ```
+ *
+ * The file is **not** loaded right away. It is added to a queue ready to be loaded either when the loader starts,
+ * or if it's already running, when the next free load slot becomes available. This happens automatically if you
+ * are calling this from within the Scene's `preload` method, or a related callback. Because the file is queued
+ * it means you cannot use the file immediately after calling this method, but must wait for the file to complete.
+ * The typical flow for a Phaser Scene is that you load assets in the Scene's `preload` method and then when the
+ * Scene's `create` method is called you are guaranteed that all of those assets are ready for use and have been
+ * loaded.
+ * 
+ * If you call this from outside of `preload` then you are responsible for starting the Loader afterwards and monitoring
+ * its events to know when it's safe to use the asset. Please see the Phaser.Loader.LoaderPlugin class for more details.
+ *
+ * Phaser expects the font data to be provided in an XML file format.
+ * These files are created by software such as the [Angelcode Bitmap Font Generator](http://www.angelcode.com/products/bmfont/),
+ * [Littera](http://kvazars.com/littera/) or [Glyph Designer](https://71squared.com/glyphdesigner)
+ * 
+ * Phaser can load all common image types: png, jpg, gif and any other format the browser can natively handle.
+ *
+ * The key must be a unique String. It is used to add the file to the global Texture Manager upon a successful load.
+ * The key should be unique both in terms of files being loaded and files already present in the Texture Manager.
+ * Loading a file using a key that is already taken will result in a warning. If you wish to replace an existing file
+ * then remove it from the Texture Manager first, before loading a new one.
+ *
+ * Instead of passing arguments you can pass a configuration object, such as:
+ * 
+ * ```javascript
+ * this.load.bitmapFont({
+ *     key: 'goldenFont',
+ *     textureURL: 'images/GoldFont.png',
+ *     fontDataURL: 'images/GoldFont.xml'
+ * });
+ * ```
+ *
+ * See the documentation for `Phaser.Loader.FileTypes.BitmapFontFileConfig` for more details.
+ *
+ * Once the atlas has finished loading you can use key of it when creating a Bitmap Text Game Object:
+ * 
+ * ```javascript
+ * this.load.bitmapFont('goldenFont', 'images/GoldFont.png', 'images/GoldFont.xml');
+ * // and later in your game ...
+ * this.add.bitmapText(x, y, 'goldenFont', 'Hello World');
+ * ```
+ *
+ * If you have specified a prefix in the loader, via `Loader.setPrefix` then this value will be prepended to this files
+ * key. For example, if the prefix was `MENU.` and the key was `Background` the final key will be `MENU.Background` and
+ * this is what you would use when creating a Bitmap Text object.
+ *
+ * The URL can be relative or absolute. If the URL is relative the `Loader.baseURL` and `Loader.path` values will be prepended to it.
+ *
+ * If the URL isn't specified the Loader will take the key and create a filename from that. For example if the key is "alien"
+ * and no URL is given then the Loader will set the URL to be "alien.png". It will always add `.png` as the extension, although
+ * this can be overridden if using an object instead of method arguments. If you do not desire this action then provide a URL.
+ *
+ * Phaser also supports the automatic loading of associated normal maps. If you have a normal map to go with this image,
+ * then you can specify it by providing an array as the `url` where the second element is the normal map:
+ * 
+ * ```javascript
+ * this.load.bitmapFont('goldenFont', [ 'images/GoldFont.png', 'images/GoldFont-n.png' ], 'images/GoldFont.xml');
+ * ```
+ *
+ * Or, if you are using a config object use the `normalMap` property:
+ * 
+ * ```javascript
+ * this.load.bitmapFont({
+ *     key: 'goldenFont',
+ *     textureURL: 'images/GoldFont.png',
+ *     normalMap: 'images/GoldFont-n.png',
+ *     fontDataURL: 'images/GoldFont.xml'
+ * });
+ * ```
  *
- * Note: This method will only be available if the Bitmap Font File type has been built into Phaser.
+ * The normal map file is subject to the same conditions as the image file with regard to the path, baseURL, CORs and XHR Settings.
+ * Normal maps are a WebGL only feature.
  *
- * The file is **not** loaded immediately after calling this method.
- * Instead, the file is added to a queue within the Loader, which is processed automatically when the Loader starts.
+ * Note: The ability to load this type of file will only be available if the Bitmap Font File type has been built into Phaser.
+ * It is available in the default build but can be excluded from custom builds.
  *
  * @method Phaser.Loader.LoaderPlugin#bitmapFont
+ * @fires Phaser.Loader.LoaderPlugin#addFileEvent
  * @since 3.0.0
  *
- * @param {string} key - [description]
- * @param {string} textureURL - [description]
- * @param {string} xmlURL - [description]
- * @param {XHRSettingsObject} [textureXhrSettings] - [description]
- * @param {XHRSettingsObject} [xmlXhrSettings] - [description]
+ * @param {(string|Phaser.Loader.FileTypes.BitmapFontFileConfig|Phaser.Loader.FileTypes.BitmapFontFileConfig[])} key - The key to use for this file, or a file configuration object, or array of them.
+ * @param {string|string[]} [textureURL] - The absolute or relative URL to load the font image file from. If undefined or `null` it will be set to `<key>.png`, i.e. if `key` was "alien" then the URL will be "alien.png".
+ * @param {string} [fontDataURL] - The absolute or relative URL to load the font xml data file from. If undefined or `null` it will be set to `<key>.xml`, i.e. if `key` was "alien" then the URL will be "alien.xml".
+ * @param {XHRSettingsObject} [textureXhrSettings] - An XHR Settings configuration object for the font image file. Used in replacement of the Loaders default XHR Settings.
+ * @param {XHRSettingsObject} [fontDataXhrSettings] - An XHR Settings configuration object for the font data xml file. Used in replacement of the Loaders default XHR Settings.
  *
- * @return {Phaser.Loader.LoaderPlugin} The Loader.
+ * @return {Phaser.Loader.LoaderPlugin} The Loader instance.
  */
-FileTypesManager.register('bitmapFont', function (key, textureURL, xmlURL, textureXhrSettings, xmlXhrSettings)
+FileTypesManager.register('bitmapFont', function (key, textureURL, fontDataURL, textureXhrSettings, fontDataXhrSettings)
 {
     var multifile;
 
@@ -111,7 +239,7 @@ FileTypesManager.register('bitmapFont', function (key, textureURL, xmlURL, textu
     }
     else
     {
-        multifile = new BitmapFontFile(this, key, textureURL, xmlURL, textureXhrSettings, xmlXhrSettings);
+        multifile = new BitmapFontFile(this, key, textureURL, fontDataURL, textureXhrSettings, fontDataXhrSettings);
 
         this.addFile(multifile.files);
     }

src/loader/filetypes/GLSLFile.js

@@ -94,9 +94,22 @@ var GLSLFile = new Class({
  * Adds a GLSL file, or array of GLSL files, to the current load queue.
  * In Phaser 3 GLSL files are just plain Text files at the current moment in time.
  *
- * The file is **not** loaded immediately, it is added to a queue ready to be loaded either when the loader starts,
- * or if it's already running, when the next free load slot becomes available. This means you cannot use the file
- * immediately after calling this method, but instead must wait for the file to complete.
+ * You can call this method from within your Scene's `preload`, along with any other files you wish to load:
+ * 
+ * ```javascript
+ * function preload ()
+ * {
+ *     this.load.glsl('plasma', 'shaders/Plasma.glsl');
+ * }
+ * ```
+ *
+ * The file is **not** loaded right away. It is added to a queue ready to be loaded either when the loader starts,
+ * or if it's already running, when the next free load slot becomes available. This happens automatically if you
+ * are calling this from within the Scene's `preload` method, or a related callback. Because the file is queued
+ * it means you cannot use the file immediately after calling this method, but must wait for the file to complete.
+ * The typical flow for a Phaser Scene is that you load assets in the Scene's `preload` method and then when the
+ * Scene's `create` method is called you are guaranteed that all of those assets are ready for use and have been
+ * loaded.
  * 
  * The key must be a unique String. It is used to add the file to the global Shader Cache upon a successful load.
  * The key should be unique both in terms of files being loaded and files already present in the Shader Cache.