Mirrors/phaser
2
0
Fork 0
mirror of https://github.com/photonstorm/phaser synced 2024-11-22 12:43:26 +00:00
Code Issues Projects Releases Packages Wiki Activity

Added jsdocs and moved FileTypes to their own namespace

Browse source
This commit is contained in:
Richard Davey 2018-02-08 17:00:14 +00:00
parent 93a2c3734b
commit e5f32ef546
10 changed files with 356 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

124
src/loader/File.js
View file

@ -24,9 +24,10 @@ var File = new Class({
function File (fileConfig)
{
/**
* The file type (image, json, etc) for sorting within the Loader.
*
* @property {string} type
* The file type string (image, json, etc) for sorting within the Loader.
*
* @name Phaser.Loader.File#type
* @type {string}
* @since 3.0.0
*/
this.type = GetFastValue(fileConfig, 'type', false);
@ -34,7 +35,8 @@ var File = new Class({
/**
* Unique cache key (unique within its file type)
*
* @property {string} key
* @name Phaser.Loader.File#key
* @type {string}
* @since 3.0.0
*/
this.key = GetFastValue(fileConfig, 'key', false);
@ -47,7 +49,8 @@ var File = new Class({
/**
* The URL of the file, not including baseURL.
*
* @property {string} url
* @name Phaser.Loader.File#url
* @type {string}
* @since 3.0.0
*/
this.url = GetFastValue(fileConfig, 'url');
@ -64,16 +67,17 @@ var File = new Class({
/**
* Set when the Loader calls 'load' on this file.
*
* @property {string} src
* @default ''
* @name Phaser.Loader.File#src
* @type {string}
* @since 3.0.0
*/
this.src = '';
/**
* [description]
* The merged XHRSettings for this file.
*
* @property {object} xhrSettings
* @name Phaser.Loader.File#xhrSettings
* @type {Phaser.Loader.XHRSettings}
* @since 3.0.0
*/
this.xhrSettings = XHRSettings(GetFastValue(fileConfig, 'responseType', undefined));
@ -86,51 +90,58 @@ var File = new Class({
/**
* The LoaderPlugin instance that is loading this file.
*
* @property {Phaser.Loader.LoaderPlugin} loader
* @default null
* @name Phaser.Loader.File#loader
* @type {?Phaser.Loader.LoaderPlugin}
* @since 3.0.0
*/
this.loader = null;
/**
* [description]
* The XHR Loader instance that is loading this File.
*
* @property {Phaser.Loader.XHRLoader} xhrLoader
* @default null
* @name Phaser.Loader.File#xhrLoader
* @type {?Phaser.Loader.XHRLoader}
* @since 3.0.0
*/
this.xhrLoader = null;
/**
* [description]
* The current state of the file. One of the FILE_CONST values.
*
* @property {integer} state
* @name Phaser.Loader.File#state
* @type {integer}
* @since 3.0.0
*/
this.state = CONST.FILE_PENDING;
/**
* Set by onProgress (only if loading via XHR)
* The total size of this file.
* Set by onProgress and only if loading via XHR.
*
* @property {number} bytesTotal
* @name Phaser.Loader.File#bytesTotal
* @type {number}
* @default 0
* @since 3.0.0
*/
this.bytesTotal = 0;
/**
* [description]
* Updated as the file loads.
* Only set if loading via XHR.
*
* @property {number} bytesLoaded
* @name Phaser.Loader.File#bytesLoaded
* @type {number}
* @default -1
* @since 3.0.0
*/
this.bytesLoaded = -1;
/**
* [description]
* A percentage value between 0 and 1 indicating how much of this file has loaded.
* Only set if loading via XHR.
*
* @property {float} percentComplete
* @name Phaser.Loader.File#percentComplete
* @type {float}
* @default -1
* @since 3.0.0
*/
@ -140,7 +151,8 @@ var File = new Class({
* For CORs based loading.
* If this is undefined then the File will check BaseLoader.crossOrigin and use that (if set)
*
* @property {string|undefined} crossOrigin
* @name Phaser.Loader.File#crossOrigin
* @type {string|undefined}
* @since 3.0.0
*/
this.crossOrigin = undefined;
@ -148,7 +160,8 @@ var File = new Class({
/**
* The processed file data, stored in here after the file has loaded.
*
* @property {any} data
* @name Phaser.Loader.File#data
* @type {any}
* @since 3.0.0
*/
this.data = undefined;
@ -156,32 +169,38 @@ var File = new Class({
/**
* A config object that can be used by file types to store transitional data.
*
* @property {[type]} config
* @name Phaser.Loader.File#config
* @type {object}
* @since 3.0.0
*/
this.config = GetFastValue(fileConfig, 'config', {});
/**
* Multipart file? i.e. an atlas and its json together.
* If this is a multipart file, i.e. an atlas and its json together, then this is a reference
* to the linked file. Set and used internally by the Loader.
*
* @property {?Phaser.Loader.File} linkFile
* @name Phaser.Loader.File#linkFile
* @type {?Phaser.Loader.File}
* @since 3.0.0
*/
this.linkFile = undefined;
/**
* [description]
* If this is a multipart file, i.e. an atlas and its json together, then this is a reference
* to the type of linked association. Set and used internally by the Loader.
*
* @property {string} linkType
* @name Phaser.Loader.File#linkType
* @type {string}
* @default ''
* @since 3.0.0
*/
this.linkType = '';
/**
* [description]
* If this is a link file, is this the parent or the sibbling?
*
* @property {boolean} linkParent
* @name Phaser.Loader.File#linkParent
* @type {boolean}
* @default false
* @since 3.0.0
*/
@ -189,13 +208,14 @@ var File = new Class({
},
/**
* [description]
* If this is a multipart file, i.e. an atlas and its json together, then this is a reference
* to the linked file. Set and used internally by the Loader.
*
* @method Phaser.Loader.File#setLinkFile
* @since 3.0.0
*
* @param {Phaser.Loader.File} fileB - [description]
* @param {string} linkType - [description]
* @param {Phaser.Loader.File} fileB - The linked file.
* @param {string} linkType - The type of association.
*/
setLinkFile: function (fileB, linkType)
{
@ -209,7 +229,7 @@ var File = new Class({
},
/**
* [description]
* Resets the XHRLoader instance.
*
* @method Phaser.Loader.File#resetXHR
* @since 3.0.0
@ -228,7 +248,7 @@ var File = new Class({
* @method Phaser.Loader.File#load
* @since 3.0.0
*
* @param {Phaser.Loader.LoaderPlugin} loader - [description]
* @param {Phaser.Loader.LoaderPlugin} loader - The Loader that will load this File.
*/
load: function (loader)
{
@ -256,12 +276,12 @@ var File = new Class({
},
/**
* Called when the file finishes loading, is sent a DOM ProgressEvent
* Called when the file finishes loading, is sent a DOM ProgressEvent.
*
* @method Phaser.Loader.File#onLoad
* @since 3.0.0
*
* @param {ProgressEvent} event - [description]
* @param {ProgressEvent} event - The DOM ProgressEvent that resulted from this load.
*/
onLoad: function (event)
{
@ -277,14 +297,13 @@ var File = new Class({
}
},
//
/**
* Called if the file errors while loading, is sent a DOM ProgressEvent
* Called if the file errors while loading, is sent a DOM ProgressEvent.
*
* @method Phaser.Loader.File#onError
* @since 3.0.0
*
* @param {ProgressEvent} event - [description]
* @param {ProgressEvent} event - The DOM ProgressEvent that resulted from this error.
*/
onError: function (event)
{
@ -294,12 +313,12 @@ var File = new Class({
},
/**
* [description]
* Called during the file load progress. Is sent a DOM ProgressEvent.
*
* @method Phaser.Loader.File#onProgress
* @since 3.0.0
*
* @param {[type]} event - [description]
* @param {ProgressEvent} event - The DOM ProgressEvent.
*/
onProgress: function (event)
{
@ -316,13 +335,13 @@ var File = new Class({
},
/**
* Usually overriden by the FileTypes and is called by Loader.finishedLoading.
* Usually overridden by the FileTypes and is called by Loader.finishedLoading.
* The callback is Loader.processUpdate
*
* @method Phaser.Loader.File#onProcess
* @since 3.0.0
*
* @param {[type]} callback - [description]
* @param {function} callback - The callback to invoke to process this File.
*/
onProcess: function (callback)
{
@ -334,7 +353,8 @@ var File = new Class({
},
/**
* [description]
* Called with the File has completed loading.
* Checks on the state of its linkfile, if set.
*
* @method Phaser.Loader.File#onComplete
* @since 3.0.0
@ -367,11 +387,11 @@ var File = new Class({
* Static method for creating object URL using URL API and setting it as image 'src' attribute.
* If URL API is not supported (usually on old browsers) it falls back to creating Base64 encoded url using FileReader.
*
* @method createObjectURL
* @method Phaser.Loader.File.createObjectURL
* @static
* @param image {Image} Image object which 'src' attribute should be set to object URL.
* @param blob {Blob} A Blob object to create an object URL for.
* @param defaultType {string} Default mime type used if blob type is not available.
* @param {Image} image - Image object which 'src' attribute should be set to object URL.
* @param {Blob} blob - A Blob object to create an object URL for.
* @param {string} defaultType - Default mime type used if blob type is not available.
*/
File.createObjectURL = function (image, blob, defaultType)
{
@ -399,9 +419,9 @@ File.createObjectURL = function (image, blob, defaultType)
* Static method for releasing an existing object URL which was previously created
* by calling {@link File#createObjectURL} method.
*
* @method revokeObjectURL
* @method Phaser.Loader.File.revokeObjectURL
* @static
* @param image {Image} Image object which 'src' attribute should be revoked.
* @param {Image} image - Image object which 'src' attribute should be revoked.
*/
File.revokeObjectURL = function (image)
{

11
src/loader/GetURL.js
View file

@ -1,3 +1,14 @@
/**
* Given a File and a baseURL value this returns the URL the File will use to download from.
*
* @function Phaser.Loader.GetURL
* @since 3.0.0
*
* @param {Phaser.Loader.File} file - The File object.
* @param {string} baseURL - A default base URL.
*
* @return {string} The URL the File will use.
*/
var GetURL = function (file, baseURL)
{
if (!file.url)

19
src/loader/MergeXHRSettings.js
View file

@ -1,11 +1,20 @@
var Extend = require('../utils/object/Extend');
var XHRSettings = require('./XHRSettings');
// Takes two XHR Objects and creates a new object
// The new object is based on global initially, but any setting in
// local overrides the global value.
/**
* Takes two XHRSettings Objects and creates a new XHRSettings object from them.
*
* The new object is seeded by the values given in the global settings, but any setting in
* the local object overrides the global ones.
*
* @function Phaser.Loader.MergeXHRSettings
* @since 3.0.0
*
* @param {Phaser.Loader.XHRSettings} global - The global XHRSettings object.
* @param {Phaser.Loader.XHRSettings} local - The local XHRSettings object.
*
* @return {Phaser.Loader.XHRSettings} A newly formed XHRSettings object.
*/
var MergeXHRSettings = function (global, local)
{
var output = (global === undefined) ? XHRSettings() : Extend(global);

13
src/loader/XHRLoader.js
View file

@ -1,5 +1,18 @@
var MergeXHRSettings = require('./MergeXHRSettings');
/**
* Creates a new XMLHttpRequest (xhr) object based on the given File and XHRSettings
* and starts the download of it. It uses the Files own XHRSettings and merges them
* with the global XHRSettings object to set the xhr values before download.
*
* @function Phaser.Loader.XHRLoader
* @since 3.0.0
*
* @param {Phaser.Loader.File} file - The File to download.
* @param {Phaser.Loader.XHRSettings} globalXHRSettings - The global XHRSettings object.
*
* @return {XMLHttpRequest} The XHR object.
*/
var XHRLoader = function (file, globalXHRSettings)
{
var config = MergeXHRSettings(globalXHRSettings, file.xhrSettings);

17
src/loader/XHRSettings.js
View file

@ -1,5 +1,17 @@
// Creates an XHRSettings Object with default values
/**
* Creates an XHRSettings Object with default values.
*
* @function Phaser.Loader.XHRSettings
* @since 3.0.0
*
* @param {string} [responseType] - The responseType, such as 'text'.
* @param {boolean} [async=true] - Should the XHR request use async or not?
* @param {string} [user] - Optional username for the XHR request.
* @param {string} [password] - Optional password for the XHR request.
* @param {integer} [timeout=0] - Optional XHR timeout value.
*
* @return {Phaser.Loader.XHRSettings} The XHRSettings object as used by the Loader.
*/
var XHRSettings = function (responseType, async, user, password, timeout)
{
if (responseType === undefined) { responseType = ''; }
@ -34,7 +46,6 @@ var XHRSettings = function (responseType, async, user, password, timeout)
overrideMimeType: undefined
};
};
module.exports = XHRSettings;

142
src/loader/const.js
View file

@ -1,43 +1,165 @@
var FILE_CONST = {
/**
* The Loader is idle.
*
* @name Phaser.Loader.LOADER_IDLE
* @type {integer}
* @since 3.0.0
*/
LOADER_IDLE: 0,
/**
* The Loader is actively loading.
*
* @name Phaser.Loader.LOADER_LOADING
* @type {integer}
* @since 3.0.0
*/
LOADER_LOADING: 1,
/**
* The Loader is processing files is has loaded.
*
* @name Phaser.Loader.LOADER_PROCESSING
* @type {integer}
* @since 3.0.0
*/
LOADER_PROCESSING: 2,
/**
* The Loader has completed loading and processing.
*
* @name Phaser.Loader.LOADER_COMPLETE
* @type {integer}
* @since 3.0.0
*/
LOADER_COMPLETE: 3,
/**
* The Loader is shutting down.
*
* @name Phaser.Loader.LOADER_SHUTDOWN
* @type {integer}
* @since 3.0.0
*/
LOADER_SHUTDOWN: 4,
/**
* The Loader has been destroyed.
*
* @name Phaser.Loader.LOADER_DESTROYED
* @type {integer}
* @since 3.0.0
*/
LOADER_DESTROYED: 5,
// File is in the load queue but not yet started
/**
* File is in the load queue but not yet started
*
* @name Phaser.Loader.FILE_PENDING
* @type {integer}
* @since 3.0.0
*/
FILE_PENDING: 10,
// File has been started to load by the loader (onLoad called)
/**
* File has been started to load by the loader (onLoad called)
*
* @name Phaser.Loader.FILE_LOADING
* @type {integer}
* @since 3.0.0
*/
FILE_LOADING: 11,
// File has loaded successfully, awaiting processing
/**
* File has loaded successfully, awaiting processing
*
* @name Phaser.Loader.FILE_LOADED
* @type {integer}
* @since 3.0.0
*/
FILE_LOADED: 12,
// File failed to load
/**
* File failed to load
*
* @name Phaser.Loader.FILE_FAILED
* @type {integer}
* @since 3.0.0
*/
FILE_FAILED: 13,
// File is being processed (onProcess callback)
/**
* File is being processed (onProcess callback)
*
* @name Phaser.Loader.FILE_PROCESSING
* @type {integer}
* @since 3.0.0
*/
FILE_PROCESSING: 14,
// File is being processed (onProcess callback)
/**
* File is waiting for its linkfile to load.
*
* @name Phaser.Loader.FILE_WAITING_LINKFILE
* @type {integer}
* @since 3.0.0
*/
FILE_WAITING_LINKFILE: 15,
// File is being processed (onProcess callback)
/**
* The File has errored somehow during processing.
*
* @name Phaser.Loader.FILE_ERRORED
* @type {integer}
* @since 3.0.0
*/
FILE_ERRORED: 16,
// File has finished processing
/**
* File has finished processing.
*
* @name Phaser.Loader.FILE_COMPLETE
* @type {integer}
* @since 3.0.0
*/
FILE_COMPLETE: 17,
// File has been destroyed
/**
* File has been destroyed
*
* @name Phaser.Loader.FILE_DESTROYED
* @type {integer}
* @since 3.0.0
*/
FILE_DESTROYED: 18,
// File was populated from local data and doesn't need an HTTP request
/**
* File was populated from local data and doesn't need an HTTP request
*
* @name Phaser.Loader.FILE_POPULATED
* @type {integer}
* @since 3.0.0
*/
FILE_POPULATED: 19,
/**
* A special Texture Atlas const.
*
* @name Phaser.Loader.TEXTURE_ATLAS_JSON_ARRAY
* @type {integer}
* @since 3.0.0
*/
TEXTURE_ATLAS_JSON_ARRAY: 20,
/**
* A special Texture Atlas const.
*
* @name Phaser.Loader.TEXTURE_ATLAS_JSON_HASH
* @type {integer}
* @since 3.0.0
*/
TEXTURE_ATLAS_JSON_HASH: 21
};

44
src/loader/filetypes/AnimationJSONFile.js
View file

@ -2,17 +2,17 @@ var FileTypesManager = require('../FileTypesManager');
var JSONFile = require('./JSONFile.js');
/**
* [description]
* An Animation JSON File.
*
* @function Phaser.Loader.Filetypes.AnimationJSONFile
* @since 3.0.0
*
* @param {string} key - [description]
* @param {string} url - [description]
* @param {string} path - [description]
* @param {object} xhrSettings - [description]
* @param {string} key - The key of the file within the loader.
* @param {string} url - The url to load the file from.
* @param {string} path - The path of the file.
* @param {object} xhrSettings - Optional file specific XHR settings.
*
* @return {Phaser.Loader.Filetypes.AnimationJSONFile} [description]
* @return {Phaser.Loader.Filetypes.AnimationJSONFile} A File instance to be added to the Loader.
*/
var AnimationJSONFile = function (key, url, path, xhrSettings)
{
@ -24,12 +24,26 @@ var AnimationJSONFile = function (key, url, path, xhrSettings)
return json;
};
// When registering a factory function 'this' refers to the Loader context.
//
// There are several properties available to use:
//
// this.scene - a reference to the Scene that owns the GameObjectFactory
/**
* Adds an Animation JSON file to the current load queue.
*
* Note: This method will only be available if the Animation JSON File type has been built into Phaser.
*
* 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.
*
*
*
* @method Phaser.Loader.LoaderPlugin#animation
* @since 3.0.0
*
* @param {string|array|object} key - A unique string to be used as the key to reference this file from the Cache. Must be unique within this file type.
* @param {string} [url] - URL of the file. If `undefined` or `null` the url will be set to `<key>.json`,
* i.e. if `key` was "alien" then the URL will be "alien.json".
* @param {object} [xhrSettings] - File specific XHR settings to be used during the load. These settings are merged with the global Loader XHR settings.
*
* @return {Phaser.Loader.LoaderPlugin} The Loader.
*/
FileTypesManager.register('animation', function (key, url, xhrSettings)
{
if (Array.isArray(key))
@ -49,4 +63,10 @@ FileTypesManager.register('animation', function (key, url, xhrSettings)
return this;
});
// When registering a factory function 'this' refers to the Loader context.
//
// There are several properties available to use:
//
// this.scene - a reference to the Scene that owns the GameObjectFactory
module.exports = AnimationJSONFile;

16
src/loader/filetypes/AtlasJSONFile.js
View file

@ -3,19 +3,19 @@ var ImageFile = require('./ImageFile.js');
var JSONFile = require('./JSONFile.js');
/**
* [description]
* An Atlas JSON File.
*
* @function Phaser.Loader.Filetypes.AtlasJSONFile
* @since 3.0.0
*
* @param {string} key - [description]
* @param {string} textureURL - [description]
* @param {string} atlasURL - [description]
* @param {string} path - [description]
* @param {object} textureXhrSettings - [description]
* @param {object} atlasXhrSettings - [description]
* @param {string} key - The key of the file within the loader.
* @param {string} textureURL - The url to load the texture file from.
* @param {string} atlasURL - The url to load the atlas file from.
* @param {string} path - The path of the file.
* @param {object} textureXhrSettings - Optional texture file specific XHR settings.
* @param {object} atlasXhrSettings - Optional atlas file specific XHR settings.
*
* @return {object} [description]
* @return {object} An object containing two File objects to be added to the loader.
*/
var AtlasJSONFile = function (key, textureURL, atlasURL, path, textureXhrSettings, atlasXhrSettings)
{

53
src/loader/filetypes/index.js Normal file
View file

@ -0,0 +1,53 @@
/**
* @namespace Phaser.Loader.FileTypes
*/
/**
* @typedef {object} XHRConfig
*
* @property {string} key - [description]
* @property {string} texture - [description]
* @property {string} [data] - [description]
* @property {XHRConfig} [xhr] - [description]
*/
/**
* @typedef {object} FileTypeConfig
*
* @property {string} key - [description]
* @property {string} texture - [description]
* @property {string} [data] - [description]
* @property {string} [url] - [description]
* @property {string} [path] - [description]
* @property {string} [extension] - [description]
* @property {string} [responseType] - [description]
* @property {object} [config] - [description]
* @property {XHRConfig} [xhr] - [description]
*/
module.exports = {
AnimationJSONFile: require('./AnimationJSONFile'),
AtlasJSONFile: require('./AtlasJSONFile'),
AudioFile: require('./AudioFile'),
AudioSprite: require('./AudioSprite'),
BinaryFile: require('./BinaryFile'),
BitmapFontFile: require('./BitmapFontFile'),
GLSLFile: require('./GLSLFile'),
HTMLAudioFile: require('./HTMLAudioFile'),
HTMLFile: require('./HTMLFile'),
ImageFile: require('./ImageFile'),
JSONFile: require('./JSONFile'),
MultiAtlas: require('./MultiAtlas'),
PluginFile: require('./PluginFile'),
ScriptFile: require('./ScriptFile'),
SpriteSheet: require('./SpriteSheet'),
SVGFile: require('./SVGFile'),
TextFile: require('./TextFile'),
TilemapCSVFile: require('./TilemapCSVFile'),
TilemapJSONFile: require('./TilemapJSONFile'),
UnityAtlasFile: require('./UnityAtlasFile'),
WavefrontFile: require('./WavefrontFile'),
XMLFile: require('./XMLFile')
};

36
src/loader/index.js
View file

@ -2,38 +2,16 @@
* @namespace Phaser.Loader
*/
/**
* @namespace Phaser.Loader.FileTypes
*/
module.exports = {
LoaderPlugin: require('./LoaderPlugin'),
FileTypes: require('./filetypes')
File: require('./File'),
FileTypesManager: require('./FileTypesManager'),
FileTypes: {
AnimationJSONFile: require('./filetypes/AnimationJSONFile'),
AtlasJSONFile: require('./filetypes/AtlasJSONFile'),
AudioFile: require('./filetypes/AudioFile'),
AudioSprite: require('./filetypes/AudioSprite'),
BinaryFile: require('./filetypes/BinaryFile'),
BitmapFontFile: require('./filetypes/BitmapFontFile'),
GLSLFile: require('./filetypes/GLSLFile'),
HTMLFile: require('./filetypes/HTMLFile'),
ImageFile: require('./filetypes/ImageFile'),
JSONFile: require('./filetypes/JSONFile'),
MultiAtlas: require('./filetypes/MultiAtlas'),
PluginFile: require('./filetypes/PluginFile'),
ScriptFile: require('./filetypes/ScriptFile'),
SpriteSheet: require('./filetypes/SpriteSheet'),
SVGFile: require('./filetypes/SVGFile'),
TextFile: require('./filetypes/TextFile'),
TilemapCSVFile: require('./filetypes/TilemapCSVFile'),
TilemapJSONFile: require('./filetypes/TilemapJSONFile'),
UnityAtlasFile: require('./filetypes/UnityAtlasFile'),
WavefrontFile: require('./filetypes/WavefrontFile'),
XMLFile: require('./filetypes/XMLFile')
}
GetURL: require('./GetURL'),
LoaderPlugin: require('./LoaderPlugin'),
MergeXHRSettings: require('./MergeXHRSettings'),
XHRLoader: require('./XHRLoader'),
XHRSettings: require('./XHRSettings')
};