From d7dfc1137d9627033790e325b5e58e5da30a6295 Mon Sep 17 00:00:00 2001 From: Richard Davey Date: Tue, 8 May 2018 13:16:53 +0100 Subject: [PATCH] Added jsdocs --- src/loader/filetypes/TextFile.js | 2 +- src/loader/filetypes/TilemapCSVFile.js | 105 +++++++++++++++++++--- src/loader/filetypes/TilemapImpactFile.js | 103 +++++++++++++++++---- src/loader/filetypes/TilemapJSONFile.js | 97 +++++++++++++++++--- 4 files changed, 263 insertions(+), 44 deletions(-) diff --git a/src/loader/filetypes/TextFile.js b/src/loader/filetypes/TextFile.js index 2f0f32688..214a37410 100644 --- a/src/loader/filetypes/TextFile.js +++ b/src/loader/filetypes/TextFile.js @@ -91,7 +91,7 @@ var TextFile = new Class({ }); /** - * Adds an Text file, or array of Text files, to the current load queue. + * Adds a Text file, or array of Text files, 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: * diff --git a/src/loader/filetypes/TilemapCSVFile.js b/src/loader/filetypes/TilemapCSVFile.js index fd8ee4381..da8979ffe 100644 --- a/src/loader/filetypes/TilemapCSVFile.js +++ b/src/loader/filetypes/TilemapCSVFile.js @@ -12,9 +12,22 @@ var GetFastValue = require('../../utils/object/GetFastValue'); var IsPlainObject = require('../../utils/object/IsPlainObject'); var TILEMAP_FORMATS = require('../../tilemaps/Formats'); +/** + * @typedef {object} Phaser.Loader.FileTypes.TilemapCSVFileConfig + * + * @property {string} key - The key of the file. Must be unique within both the Loader and the Tilemap Cache. + * @property {string} [url] - The absolute or relative URL to load the file from. + * @property {string} [extension='csv'] - The default file extension to use if no url is provided. + * @property {XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for this file. + */ + /** * @classdesc - * [description] + * A single Tilemap CSV File suitable for loading by the Loader. + * + * These are created when you use the Phaser.Loader.LoaderPlugin#tilemapCSV method and are not typically created directly. + * + * For documentation about what all the arguments and configuration options mean please see Phaser.Loader.LoaderPlugin#tilemapCSV. * * @class TilemapCSVFile * @extends Phaser.Loader.File @@ -22,11 +35,10 @@ var TILEMAP_FORMATS = require('../../tilemaps/Formats'); * @constructor * @since 3.0.0 * - * @param {string} key - [description] - * @param {string} url - [description] - * @param {string} path - [description] - * @param {string} format - [description] - * @param {XHRSettingsObject} [xhrSettings] - [description] + * @param {Phaser.Loader.LoaderPlugin} loader - A reference to the Loader that is responsible for this file. + * @param {(string|Phaser.Loader.FileTypes.TilemapCSVFileConfig)} key - The key to use for this file, or a file configuration object. + * @param {string} [url] - The absolute or relative URL to load this file from. If undefined or `null` it will be set to `.csv`, i.e. if `key` was "alien" then the URL will be "alien.csv". + * @param {XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for this file. */ var TilemapCSVFile = new Class({ @@ -63,6 +75,13 @@ var TilemapCSVFile = new Class({ this.tilemapFormat = TILEMAP_FORMATS.CSV; }, + /** + * Called automatically by Loader.nextFile. + * This method controls what extra work this File does with its loaded data. + * + * @method Phaser.Loader.FileTypes.TilemapCSVFile#onProcess + * @since 3.7.0 + */ onProcess: function () { this.state = CONST.FILE_PROCESSING; @@ -72,6 +91,12 @@ var TilemapCSVFile = new Class({ this.onProcessComplete(); }, + /** + * Adds this file to its target cache upon successful loading and processing. + * + * @method Phaser.Loader.FileTypes.TilemapCSVFile#addToCache + * @since 3.7.0 + */ addToCache: function () { var tiledata = { format: this.tilemapFormat, data: this.data }; @@ -84,21 +109,73 @@ var TilemapCSVFile = new Class({ }); /** - * Adds a Tilemap CSV file to the current load queue. + * Adds a CSV Tilemap file, or array of CSV files, to the current load queue. * - * Note: This method will only be available if the Tilemap CSV File type has been built into Phaser. + * 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.tilemapCSV('level1', maps/Level1.csv'); + * } + * ``` * - * 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. + * Tilemap CSV data can be created in a text editor, or a 3rd party app that exports as CSV. + * + * 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 Tilemap Cache upon a successful load. + * The key should be unique both in terms of files being loaded and files already present in the Tilemap Cache. + * 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 Text Cache first, before loading a new one. + * + * Instead of passing arguments you can pass a configuration object, such as: + * + * ```javascript + * this.load.tilemapCSV({ + * key: 'level1', + * url: 'maps/Level1.csv' + * }); + * ``` + * + * See the documentation for `Phaser.Loader.FileTypes.TilemapCSVFileConfig` for more details. + * + * Once the file has finished loading you can access it from its Cache using its key: + * + * ```javascript + * this.load.tilemapCSV('level1', 'maps/Level1.csv'); + * // and later in your game ... + * var map = this.make.tilemap({ key: 'level1' }); + * ``` + * + * 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 `LEVEL1.` and the key was `Story` the final key will be `LEVEL1.Story` and + * this is what you would use to retrieve the text from the Tilemap Cache. + * + * 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 "level" + * and no URL is given then the Loader will set the URL to be "level.csv". It will always add `.csv` 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. + * + * Note: The ability to load this type of file will only be available if the Tilemap CSV 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#tilemapCSV + * @fires Phaser.Loader.LoaderPlugin#addFileEvent * @since 3.0.0 * - * @param {string} key - [description] - * @param {string} url - [description] - * @param {XHRSettingsObject} [xhrSettings] - [description] + * @param {(string|Phaser.Loader.FileTypes.TilemapCSVFileConfig|Phaser.Loader.FileTypes.TilemapCSVFileConfig[])} key - The key to use for this file, or a file configuration object, or array of them. + * @param {string} [url] - The absolute or relative URL to load this file from. If undefined or `null` it will be set to `.csv`, i.e. if `key` was "alien" then the URL will be "alien.csv". + * @param {XHRSettingsObject} [xhrSettings] - An XHR Settings configuration object. Used in replacement of the Loaders default XHR Settings. * - * @return {Phaser.Loader.LoaderPlugin} The Loader. + * @return {Phaser.Loader.LoaderPlugin} The Loader instance. */ FileTypesManager.register('tilemapCSV', function (key, url, xhrSettings) { diff --git a/src/loader/filetypes/TilemapImpactFile.js b/src/loader/filetypes/TilemapImpactFile.js index a722afc73..4ba60f90b 100644 --- a/src/loader/filetypes/TilemapImpactFile.js +++ b/src/loader/filetypes/TilemapImpactFile.js @@ -9,9 +9,22 @@ var FileTypesManager = require('../FileTypesManager'); var JSONFile = require('./JSONFile.js'); var TILEMAP_FORMATS = require('../../tilemaps/Formats'); +/** + * @typedef {object} Phaser.Loader.FileTypes.TilemapImpactFileConfig + * + * @property {string} key - The key of the file. Must be unique within both the Loader and the Tilemap Cache. + * @property {string} [url] - The absolute or relative URL to load the file from. + * @property {string} [extension='json'] - The default file extension to use if no url is provided. + * @property {XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for this file. + */ + /** * @classdesc - * [description] + * A single Impact.js Tilemap JSON File suitable for loading by the Loader. + * + * These are created when you use the Phaser.Loader.LoaderPlugin#tilemapImpact method and are not typically created directly. + * + * For documentation about what all the arguments and configuration options mean please see Phaser.Loader.LoaderPlugin#tilemapImpact. * * @class TilemapImpactFile * @extends Phaser.Loader.File @@ -19,10 +32,10 @@ var TILEMAP_FORMATS = require('../../tilemaps/Formats'); * @constructor * @since 3.7.0 * - * @param {string} key - [description] - * @param {string} url - [description] - * @param {string} path - [description] - * @param {XHRSettingsObject} [xhrSettings] - [description] + * @param {Phaser.Loader.LoaderPlugin} loader - A reference to the Loader that is responsible for this file. + * @param {(string|Phaser.Loader.FileTypes.TilemapImpactFileConfig)} key - The key to use for this file, or a file configuration object. + * @param {string} [url] - The absolute or relative URL to load this file from. If undefined or `null` it will be set to `.json`, i.e. if `key` was "alien" then the URL will be "alien.json". + * @param {XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for this file. */ var TilemapImpactFile = new Class({ @@ -39,6 +52,12 @@ var TilemapImpactFile = new Class({ this.cache = loader.cacheManager.tilemap; }, + /** + * Adds this file to its target cache upon successful loading and processing. + * + * @method Phaser.Loader.FileTypes.TilemapImpactFile#addToCache + * @since 3.7.0 + */ addToCache: function () { var tiledata = { format: TILEMAP_FORMATS.WELTMEISTER, data: this.data }; @@ -51,23 +70,75 @@ var TilemapImpactFile = new Class({ }); /** - * Adds a Tilemap (Weltmeister Format) file to the current load queue. + * Adds an Impact.js Tilemap file, or array of map files, to the current load queue. * - * Note: This method will only be available if the Tilemap File type has been built into Phaser. + * 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.tilemapImpact('level1', maps/Level1.json'); + * } + * ``` * - * 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. + * Impact Tilemap data is created the Impact.js Map Editor called Weltmeister. * - * @method Phaser.Loader.LoaderPlugin#tilemapWeltmeister - * @since 3.0.0 + * 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 Tilemap Cache upon a successful load. + * The key should be unique both in terms of files being loaded and files already present in the Tilemap Cache. + * 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 Text Cache first, before loading a new one. * - * @param {string} key - [description] - * @param {string} url - [description] - * @param {XHRSettingsObject} [xhrSettings] - [description] + * Instead of passing arguments you can pass a configuration object, such as: + * + * ```javascript + * this.load.tilemapImpact({ + * key: 'level1', + * url: 'maps/Level1.json' + * }); + * ``` * - * @return {Phaser.Loader.LoaderPlugin} The Loader. + * See the documentation for `Phaser.Loader.FileTypes.TilemapImpactFileConfig` for more details. + * + * Once the file has finished loading you can access it from its Cache using its key: + * + * ```javascript + * this.load.tilemapImpact('level1', 'maps/Level1.json'); + * // and later in your game ... + * var map = this.make.tilemap({ key: 'level1' }); + * ``` + * + * 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 `LEVEL1.` and the key was `Story` the final key will be `LEVEL1.Story` and + * this is what you would use to retrieve the text from the Tilemap Cache. + * + * 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 "level" + * and no URL is given then the Loader will set the URL to be "level.json". It will always add `.json` 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. + * + * Note: The ability to load this type of file will only be available if the Tilemap Impact 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#tilemapImpact + * @fires Phaser.Loader.LoaderPlugin#addFileEvent + * @since 3.7.0 + * + * @param {(string|Phaser.Loader.FileTypes.TilemapImpactFileConfig|Phaser.Loader.FileTypes.TilemapImpactFileConfig[])} key - The key to use for this file, or a file configuration object, or array of them. + * @param {string} [url] - The absolute or relative URL to load this file from. If undefined or `null` it will be set to `.json`, i.e. if `key` was "alien" then the URL will be "alien.json". + * @param {XHRSettingsObject} [xhrSettings] - An XHR Settings configuration object. Used in replacement of the Loaders default XHR Settings. + * + * @return {Phaser.Loader.LoaderPlugin} The Loader instance. */ -FileTypesManager.register('tilemapWeltmeister', function (key, url, xhrSettings) +FileTypesManager.register('tilemapImpact', function (key, url, xhrSettings) { if (Array.isArray(key)) { diff --git a/src/loader/filetypes/TilemapJSONFile.js b/src/loader/filetypes/TilemapJSONFile.js index 7c96736c5..e25a61884 100644 --- a/src/loader/filetypes/TilemapJSONFile.js +++ b/src/loader/filetypes/TilemapJSONFile.js @@ -9,9 +9,22 @@ var FileTypesManager = require('../FileTypesManager'); var JSONFile = require('./JSONFile.js'); var TILEMAP_FORMATS = require('../../tilemaps/Formats'); +/** + * @typedef {object} Phaser.Loader.FileTypes.TilemapJSONFileConfig + * + * @property {string} key - The key of the file. Must be unique within both the Loader and the Tilemap Cache. + * @property {string} [url] - The absolute or relative URL to load the file from. + * @property {string} [extension='json'] - The default file extension to use if no url is provided. + * @property {XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for this file. + */ + /** * @classdesc - * [description] + * A single Tiled Tilemap JSON File suitable for loading by the Loader. + * + * These are created when you use the Phaser.Loader.LoaderPlugin#tilemapTiledJSON method and are not typically created directly. + * + * For documentation about what all the arguments and configuration options mean please see Phaser.Loader.LoaderPlugin#tilemapTiledJSON. * * @class TilemapJSONFile * @extends Phaser.Loader.File @@ -19,10 +32,10 @@ var TILEMAP_FORMATS = require('../../tilemaps/Formats'); * @constructor * @since 3.0.0 * - * @param {string} key - [description] - * @param {string} url - [description] - * @param {string} path - [description] - * @param {XHRSettingsObject} [xhrSettings] - [description] + * @param {Phaser.Loader.LoaderPlugin} loader - A reference to the Loader that is responsible for this file. + * @param {(string|Phaser.Loader.FileTypes.TilemapJSONFileConfig)} key - The key to use for this file, or a file configuration object. + * @param {string} [url] - The absolute or relative URL to load this file from. If undefined or `null` it will be set to `.json`, i.e. if `key` was "alien" then the URL will be "alien.json". + * @param {XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for this file. */ var TilemapJSONFile = new Class({ @@ -39,6 +52,12 @@ var TilemapJSONFile = new Class({ this.cache = loader.cacheManager.tilemap; }, + /** + * Adds this file to its target cache upon successful loading and processing. + * + * @method Phaser.Loader.FileTypes.TilemapJSONFile#addToCache + * @since 3.7.0 + */ addToCache: function () { var tiledata = { format: TILEMAP_FORMATS.TILED_JSON, data: this.data }; @@ -51,21 +70,73 @@ var TilemapJSONFile = new Class({ }); /** - * Adds a Tilemap (Tiled JSON Format) file to the current load queue. + * Adds a Tiled JSON Tilemap file, or array of map files, to the current load queue. * - * Note: This method will only be available if the Tilemap File type has been built into Phaser. + * 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.tilemapTiledJSON('level1', maps/Level1.json'); + * } + * ``` * - * 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. + * The Tilemap data is created using the Tiled Map Editor and selecting JSON as the export format. + * + * 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 Tilemap Cache upon a successful load. + * The key should be unique both in terms of files being loaded and files already present in the Tilemap Cache. + * 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 Text Cache first, before loading a new one. + * + * Instead of passing arguments you can pass a configuration object, such as: + * + * ```javascript + * this.load.tilemapTiledJSON({ + * key: 'level1', + * url: 'maps/Level1.json' + * }); + * ``` + * + * See the documentation for `Phaser.Loader.FileTypes.TilemapJSONFileConfig` for more details. + * + * Once the file has finished loading you can access it from its Cache using its key: + * + * ```javascript + * this.load.tilemapTiledJSON('level1', 'maps/Level1.json'); + * // and later in your game ... + * var map = this.make.tilemap({ key: 'level1' }); + * ``` + * + * 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 `LEVEL1.` and the key was `Story` the final key will be `LEVEL1.Story` and + * this is what you would use to retrieve the text from the Tilemap Cache. + * + * 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 "level" + * and no URL is given then the Loader will set the URL to be "level.json". It will always add `.json` 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. + * + * Note: The ability to load this type of file will only be available if the Tilemap JSON 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#tilemapTiledJSON + * @fires Phaser.Loader.LoaderPlugin#addFileEvent * @since 3.0.0 * - * @param {string} key - [description] - * @param {string} url - [description] - * @param {XHRSettingsObject} [xhrSettings] - [description] + * @param {(string|Phaser.Loader.FileTypes.TilemapJSONFileConfig|Phaser.Loader.FileTypes.TilemapJSONFileConfig[])} key - The key to use for this file, or a file configuration object, or array of them. + * @param {string} [url] - The absolute or relative URL to load this file from. If undefined or `null` it will be set to `.json`, i.e. if `key` was "alien" then the URL will be "alien.json". + * @param {XHRSettingsObject} [xhrSettings] - An XHR Settings configuration object. Used in replacement of the Loaders default XHR Settings. * - * @return {Phaser.Loader.LoaderPlugin} The Loader. + * @return {Phaser.Loader.LoaderPlugin} The Loader instance. */ FileTypesManager.register('tilemapTiledJSON', function (key, url, xhrSettings) {