new Loader(game)
The Loader handles loading all external content such as Images, Sounds, Texture Atlases and data files. It uses a combination of Image() loading and xhr and provides progress and completion callbacks.
Parameters
Name | Type | Description |
---|---|---|
game |
Phaser.Game | A reference to the currently running game. |
- Source code: loader/Loader.js, line 16
Public Properties
-
[static] PHYSICS_LIME_CORONA_JSON : number
-
- Source code: loader/Loader.js, line 173
-
[static] PHYSICS_PHASER_JSON : number
-
- Source code: loader/Loader.js, line 179
-
[static] TEXTURE_ATLAS_JSON_ARRAY : number
-
- Source code: loader/Loader.js, line 155
-
[static] TEXTURE_ATLAS_JSON_HASH : number
-
- Source code: loader/Loader.js, line 161
-
[static] TEXTURE_ATLAS_XML_STARLING : number
-
- Source code: loader/Loader.js, line 167
-
baseURL : string
-
If you want to append a URL before the path of any asset you can set this here. Useful if you need to allow an asset url to be configured outside of the game code. MUST have / on the end of it!
- Source code: loader/Loader.js, line 69
-
crossOrigin : boolean | string
-
The crossOrigin value applied to loaded images. Very often this needs to be set to 'anonymous'.
Type
- boolean | string
- Default Value
- false
- Source code: loader/Loader.js, line 60
-
game : Phaser.Game
-
Local reference to game.
- Source code: loader/Loader.js, line 21
-
hasLoaded : boolean
-
True if all assets in the queue have finished loading.
- Default Value
- false
- Source code: loader/Loader.js, line 33
-
isLoading : boolean
-
True if the Loader is in the process of loading the queue.
- Default Value
- false
- Source code: loader/Loader.js, line 27
-
onFileComplete : Phaser.Signal
-
This event is dispatched when a file completes loading successfully.
- Source code: loader/Loader.js, line 84
-
onFileError : Phaser.Signal
-
This event is dispatched when a file errors as a result of the load request.
- Source code: loader/Loader.js, line 89
-
onFileStart : Phaser.Signal
-
This event is dispatched immediately before a file starts loading. It's possible the file may still error (404, etc) after this event is sent.
- Source code: loader/Loader.js, line 79
-
onLoadComplete : Phaser.Signal
-
This event is dispatched when the final file in the load queue has either loaded or failed.
- Source code: loader/Loader.js, line 94
-
onLoadStart : Phaser.Signal
-
This event is dispatched when the loading process starts, before the first file has been requested.
- Source code: loader/Loader.js, line 74
-
onPackComplete : Phaser.Signal
-
This event is dispatched when an asset pack has either loaded or failed.
- Source code: loader/Loader.js, line 99
-
preloadSprite : Object
-
You can optionally link a sprite to the preloader. If you do so the Sprites width or height will be cropped based on the percentage loaded. This property is an object containing: sprite, rect, direction, width and height
- Source code: loader/Loader.js, line 54
-
progress : number
-
The rounded load progress percentage value (from 0 to 100)
- Default Value
- 0
- Source code: loader/Loader.js, line 39
-
progressFloat : number
-
The non-rounded load progress value (from 0.0 to 100.0)
- Default Value
- 0
- Source code: loader/Loader.js, line 45
-
useXDomainRequest : boolean
-
If true and if the browser supports XDomainRequest, it will be used in preference for xhr when loading json files. This is only relevant for IE9 when you know your server/CDN requires it.
- Source code: loader/Loader.js, line 104
Public Methods
-
<internal> addToFileList(type, key, url, properties)
-
Internal function that adds a new entry to the file list. Do not call directly.
Parameters
Name Type Description type
string The type of resource to add to the list (image, audio, xml, etc).
key
string The unique Cache ID key of this resource.
url
string The URL the asset will be loaded from.
properties
object Any additional properties needed to load the file.
- Internal:
- This member is internal (protected) and may be modified or removed in the future.
- Source code: loader/Loader.js, line 326
-
atlas(key, textureURL, atlasURL, atlasData, format) → {Phaser.Loader}
-
Add a new texture atlas to the loader.
Parameters
Name Type Argument Description key
string Unique asset key of the texture atlas file.
textureURL
string The url of the texture atlas image file.
atlasURL
string <optional>
The url of the texture atlas data file (json/xml). You don't need this if you are passing an atlasData object instead.
atlasData
object <optional>
A JSON or XML data object. You don't need this if the data is being loaded from a URL.
format
number <optional>
A value describing the format of the data, the default is Phaser.Loader.TEXTURE_ATLAS_JSON_ARRAY.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 862
-
atlasJSONArray(key, textureURL, atlasURL, atlasData) → {Phaser.Loader}
-
Add a new texture atlas to the loader. This atlas uses the JSON Array data format.
Parameters
Name Type Argument Description key
string Unique asset key of the texture atlas file.
textureURL
string The url of the texture atlas image file.
atlasURL
string <optional>
The url of the texture atlas data file (json/xml). You don't need this if you are passing an atlasData object instead.
atlasData
object <optional>
A JSON or XML data object. You don't need this if the data is being loaded from a URL.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 814
-
atlasJSONHash(key, textureURL, atlasURL, atlasData) → {Phaser.Loader}
-
Add a new texture atlas to the loader. This atlas uses the JSON Hash data format.
Parameters
Name Type Argument Description key
string Unique asset key of the texture atlas file.
textureURL
string The url of the texture atlas image file.
atlasURL
string <optional>
The url of the texture atlas data file (json/xml). You don't need this if you are passing an atlasData object instead.
atlasData
object <optional>
A JSON or XML data object. You don't need this if the data is being loaded from a URL.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 830
-
atlasXML(key, textureURL, atlasURL, atlasData) → {Phaser.Loader}
-
Add a new texture atlas to the loader. This atlas uses the Starling XML data format.
Parameters
Name Type Argument Description key
string Unique asset key of the texture atlas file.
textureURL
string The url of the texture atlas image file.
atlasURL
string <optional>
The url of the texture atlas data file (json/xml). You don't need this if you are passing an atlasData object instead.
atlasData
object <optional>
A JSON or XML data object. You don't need this if the data is being loaded from a URL.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 846
-
audio(key, urls, autoDecode) → {Phaser.Loader}
-
Add a new audio file to the loader.
Parameters
Name Type Description key
string Unique asset key of the audio file.
urls
Array | string An array containing the URLs of the audio files, i.e.: [ 'jump.mp3', 'jump.ogg', 'jump.m4a' ] or a single string containing just one URL. BLOB urls are supported, but note that Phaser will not validate the audio file's type if a BLOB is provided; the user should ensure that a BLOB url is playable.
autoDecode
boolean When using Web Audio the audio files can either be decoded at load time or run-time. They can't be played until they are decoded, but this let's you control when that happens. Decoding is a non-blocking async process.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 615
-
audiosprite(key, urls, atlasURL) → {Phaser.Loader}
-
Add a new audiosprite file to the loader. Audio Sprites are a combination of audio files and a JSON configuration. The JSON follows the format of that created by https://github.com/tonistiigi/audiosprite
Parameters
Name Type Description key
string Unique asset key of the audio file.
urls
Array | string An array containing the URLs of the audio files, i.e.: [ 'audiosprite.mp3', 'audiosprite.ogg', 'audiosprite.m4a' ] or a single string containing just one URL.
atlasURL
string The URL of the audiosprite configuration json.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 634
-
binary(key, url, callback, callbackContext) → {Phaser.Loader}
-
Add a binary file to the Loader. It will be loaded via xhr with a responseType of "arraybuffer". You can specify an optional callback to process the file after load. When the callback is called it will be passed 2 parameters: the key of the file and the file data. WARNING: If you specify a callback, the file data will be set to whatever your callback returns. So always return the data object, even if you didn't modify it.
Parameters
Name Type Argument Description key
string Unique asset key of the binary file.
url
string URL of the binary file.
callback
function <optional>
Optional callback that will be passed the file after loading, so you can perform additional processing on it.
callbackContext
function <optional>
The context under which the callback will be applied. If not specified it will use the callback itself as the context.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 567
-
bitmapFont(key, textureURL, xmlURL, xmlData, xSpacing, ySpacing) → {Phaser.Loader}
-
Add a new bitmap font loading request.
Parameters
Name Type Argument Default Description key
string Unique asset key of the bitmap font.
textureURL
string The url of the font image file.
xmlURL
string <optional>
The url of the font data file (xml/fnt)
xmlData
object <optional>
An optional XML data object.
xSpacing
number <optional>
0 If you'd like to add additional horizontal spacing between the characters then set the pixel value here.
ySpacing
number <optional>
0 If you'd like to add additional vertical spacing between the lines then set the pixel value here.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 750
-
checkKeyExists(type, key) → {boolean}
-
Check whether asset exists with a specific key. Use Phaser.Cache to access loaded assets, e.g. Phaser.Cache#checkImageKey
Parameters
Name Type Description type
string The type asset you want to check.
key
string Key of the asset you want to check.
Returns
boolean -Return true if exists, otherwise return false.
- Source code: loader/Loader.js, line 232
-
csvLoadComplete(index)
-
Successfully loaded a CSV file.
Parameters
Name Type Description index
number The index of the file in the file queue that loaded.
- Source code: loader/Loader.js, line 1642
-
dataLoadError(index)
-
Error occured when load a JSON.
Parameters
Name Type Description index
number The index of the file in the file queue that errored.
- Source code: loader/Loader.js, line 1667
-
fileComplete(index)
-
Called when a file is successfully loaded.
Parameters
Name Type Description index
number The index of the file in the file queue that loaded.
- Source code: loader/Loader.js, line 1451
-
fileError(index)
-
Error occured when loading a file.
Parameters
Name Type Description index
number The index of the file in the file queue that errored.
- Source code: loader/Loader.js, line 1432
-
getAsset(type, key) → {any}
-
Gets the asset that is queued for load.
Parameters
Name Type Description type
string The type asset you want to check.
key
string Key of the asset you want to check.
Returns
any -Returns an object if found that has 2 properties: index and file. Otherwise false.
- Source code: loader/Loader.js, line 283
-
getAssetIndex(type, key) → {number}
-
Gets the fileList index for the given key.
Parameters
Name Type Description type
string The type asset you want to check.
key
string Key of the asset you want to check.
Returns
number -The index of this key in the filelist, or -1 if not found.
- Source code: loader/Loader.js, line 258
-
image(key, url, overwrite) → {Phaser.Loader}
-
Add an image to the Loader.
Parameters
Name Type Argument Default Description key
string Unique asset key of this image file.
url
string URL of image file.
overwrite
boolean <optional>
false If an unloaded file with a matching key already exists in the queue, this entry will overwrite it.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 441
-
json(key, url, overwrite) → {Phaser.Loader}
-
Add a json file to the Loader.
Parameters
Name Type Argument Default Description key
string Unique asset key of the json file.
url
string URL of the json file.
overwrite
boolean <optional>
false If an unloaded file with a matching key already exists in the queue, this entry will overwrite it.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 493
-
jsonLoadComplete(index)
-
Successfully loaded a JSON file.
Parameters
Name Type Description index
number The index of the file in the file queue that loaded.
- Source code: loader/Loader.js, line 1598
-
pack(key, url, data, callbackContext) → {Phaser.Loader}
-
Add an image to the Loader.
Parameters
Name Type Argument Description key
string Unique asset key of this image file.
url
string <optional>
URL of the Asset Pack JSON file. If you wish to pass a json object instead set this to null and pass the object as the data parameter.
data
object <optional>
The Asset Pack JSON data. Use this to pass in a json data object rather than loading it from a URL. TODO
callbackContext
object <optional>
Some Loader operations, like Binary and Script require a context for their callbacks. Pass the context here.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 404
-
physics(key, url, data, format) → {Phaser.Loader}
-
Add a new physics data object loading request. The data must be in Lime + Corona JSON format. Physics Editor by code'n'web exports in this format natively.
Parameters
Name Type Argument Default Description key
string Unique asset key of the physics json data.
url
string <optional>
The url of the map data file (csv/json)
data
object <optional>
An optional JSON data object. If given then the url is ignored and this JSON object is used for physics data instead.
format
string <optional>
Phaser.Physics.LIME_CORONA_JSON The format of the physics data.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 707
-
removeAll()
-
Remove all file loading requests.
- Source code: loader/Loader.js, line 960
-
removeFile(type, key)
-
Remove loading request of a file.
Parameters
Name Type Description type
string The type of resource to add to the list (image, audio, xml, etc).
key
string Key of the file you want to remove.
- Source code: loader/Loader.js, line 942
-
<internal> replaceInFileList(type, key, url, properties)
-
Internal function that replaces an existing entry in the file list with a new one. Do not call directly.
Parameters
Name Type Description type
string The type of resource to add to the list (image, audio, xml, etc).
key
string The unique Cache ID key of this resource.
url
string The URL the asset will be loaded from.
properties
object Any additional properties needed to load the file.
- Internal:
- This member is internal (protected) and may be modified or removed in the future.
- Source code: loader/Loader.js, line 362
-
reset()
-
Reset loader, this will remove the load queue.
- Source code: loader/Loader.js, line 308
-
resize(width, height)
-
Called automatically by ScaleManager when the game resizes in RESIZE scalemode. We use this to adjust the height of the preloading sprite, if set.
Parameters
Name Type Description width
number The new width of the game in pixels.
height
number The new height of the game in pixels.
- Source code: loader/Loader.js, line 215
-
script(key, url, callback, callbackContext) → {Phaser.Loader}
-
Add a JavaScript file to the Loader. Once loaded the JavaScript file will be automatically turned into a script tag (and executed), so be careful what you load! You can also specify a callback. This will be executed as soon as the script tag has been created.
Parameters
Name Type Argument Description key
string Unique asset key of the script file.
url
string URL of the JavaScript file.
callback
function <optional>
Optional callback that will be called after the script tag has loaded, so you can perform additional processing.
callbackContext
function <optional>
The context under which the callback will be applied. If not specified it will use the callback itself as the context.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 545
-
setPreloadSprite(sprite, direction)
-
You can set a Sprite to be a "preload" sprite by passing it to this method. A "preload" sprite will have its width or height crop adjusted based on the percentage of the loader in real-time. This allows you to easily make loading bars for games. Note that Sprite.visible = true will be set when calling this.
Parameters
Name Type Argument Default Description sprite
Phaser.Sprite | Phaser.Image The sprite or image that will be cropped during the load.
direction
number <optional>
0 A value of zero means the sprite will be cropped horizontally, a value of 1 means its will be cropped vertically.
- Source code: loader/Loader.js, line 183
-
spritesheet(key, url, frameWidth, frameHeight, frameMax, margin, spacing) → {Phaser.Loader}
-
Add a new sprite sheet to the loader.
Parameters
Name Type Argument Default Description key
string Unique asset key of the sheet file.
url
string URL of the sheet file.
frameWidth
number Width of each single frame.
frameHeight
number Height of each single frame.
frameMax
number <optional>
-1 How many frames in this sprite sheet. If not specified it will divide the whole image into frames.
margin
number <optional>
0 If the frames have been drawn with a margin, specify the amount here.
spacing
number <optional>
0 If the frames have been drawn with spacing between them, specify the amount here.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 590
-
start()
-
Start loading the assets. Normally you don't need to call this yourself as the StateManager will do so.
- Source code: loader/Loader.js, line 971
-
text(key, url, overwrite) → {Phaser.Loader}
-
Add a text file to the Loader.
Parameters
Name Type Argument Default Description key
string Unique asset key of the text file.
url
string URL of the text file.
overwrite
boolean <optional>
false If an unloaded file with a matching key already exists in the queue, this entry will overwrite it.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 467
-
tilemap(key, url, data, format) → {Phaser.Loader}
-
Add a new tilemap loading request.
Parameters
Name Type Argument Default Description key
string Unique asset key of the tilemap data.
url
string <optional>
The url of the map data file (csv/json)
data
object <optional>
An optional JSON data object. If given then the url is ignored and this JSON object is used for map data instead.
format
number <optional>
Phaser.Tilemap.CSV The format of the map data. Either Phaser.Tilemap.CSV or Phaser.Tilemap.TILED_JSON.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 654
-
totalLoadedFiles() → {number}
-
Returns the number of files that have already been loaded, even if they errored.
Returns
number -The number of files that have already been loaded (even if they errored)
- Source code: loader/Loader.js, line 1798
-
totalLoadedPacks() → {number}
-
Returns the number of asset packs that have already been loaded, even if they errored.
Returns
number -The number of asset packs that have already been loaded (even if they errored)
- Source code: loader/Loader.js, line 1842
-
totalQueuedFiles() → {number}
-
Returns the number of files still waiting to be processed in the load queue. This value decreases as each file in the queue is loaded.
Returns
number -The number of files that still remain in the load queue.
- Source code: loader/Loader.js, line 1820
-
totalQueuedPacks() → {number}
-
Returns the number of asset packs still waiting to be processed in the load queue. This value decreases as each pack in the queue is loaded.
Returns
number -The number of asset packs that still remain in the load queue.
- Source code: loader/Loader.js, line 1864
-
xml(key, url, overwrite) → {Phaser.Loader}
-
Add an XML file to the Loader.
Parameters
Name Type Argument Default Description key
string Unique asset key of the xml file.
url
string URL of the xml file.
overwrite
boolean <optional>
false If an unloaded file with a matching key already exists in the queue, this entry will overwrite it.
Returns
This Loader instance.
- Source code: loader/Loader.js, line 519
-
xmlLoadComplete(index)
-
Successfully loaded an XML file.
Parameters
Name Type Description index
number The index of the file in the file queue that loaded.
- Source code: loader/Loader.js, line 1686