Phaser

Class: Loader

Phaser. Loader

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.

new Loader(game)

Phaser loader constructor. 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:

Members

<static, constant> PHYSICS_LIME_CORONA_JSON :number

Type:
  • number
Source:

<static, constant> PHYSICS_PHASER_JSON :number

Type:
  • number
Source:

<static, constant> TEXTURE_ATLAS_JSON_ARRAY :number

Type:
  • number
Source:

<static, constant> TEXTURE_ATLAS_JSON_HASH :number

Type:
  • number
Source:

<static, constant> TEXTURE_ATLAS_XML_STARLING :number

Type:
  • number
Source:

baseURL

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!

Properties:
Name Type Description
baseURL string
Source:

crossOrigin

Properties:
Name Type Description
crossOrigin boolean | string

The crossOrigin value applied to loaded images. Very often this needs to be set to 'anonymous'.
Default Value:
  • false
Source:

game

Properties:
Name Type Description
game Phaser.Game

Local reference to game.
Source:

hasLoaded

Properties:
Name Type Description
hasLoaded boolean

True if all assets in the queue have finished loading.
Default Value:
  • false
Source:

isLoading

Properties:
Name Type Description
isLoading boolean

True if the Loader is in the process of loading the queue.
Default Value:
  • false
Source:

onFileComplete

Properties:
Name Type Description
onFileComplete Phaser.Signal

This event is dispatched when a file completes loading successfully.
Source:

onFileError

Properties:
Name Type Description
onFileError Phaser.Signal

This event is dispatched when a file errors as a result of the load request.
Source:

onFileStart

Properties:
Name Type Description
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:

onLoadComplete

Properties:
Name Type Description
onLoadComplete Phaser.Signal

This event is dispatched when the final file in the load queue has either loaded or failed.
Source:

onLoadStart

Properties:
Name Type Description
onLoadStart Phaser.Signal

This event is dispatched when the loading process starts, before the first file has been requested.
Source:

onPackComplete

Properties:
Name Type Description
onPackComplete Phaser.Signal

This event is dispatched when an asset pack has either loaded or failed.
Source:

preloadSprite

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.

Properties:
Name Type Description
preloadSprite Phaser.Sprite | Phaser.Image
Default Value:
  • null
Source:

progress

Properties:
Name Type Description
progress number

The rounded load progress percentage value (from 0 to 100)
Default Value:
  • 0
Source:

progressFloat

Properties:
Name Type Description
progressFloat number

The non-rounded load progress value (from 0.0 to 100.0)
Default Value:
  • 0
Source:

Methods

<protected> 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.
Source:

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
Source:
Returns:

Return true if exists, otherwise return false.

Type
boolean

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:

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:

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:

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:

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.
Source:
Returns:

Returns an object if found that has 2 properties: index and file. Otherwise false.

Type
any

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.
Source:
Returns:

The index of this key in the filelist, or -1 if not found.

Type
number

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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:

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

removeAll()

Remove all file loading requests.

Source:

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:

<protected> 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.
Source:

reset()

Reset loader, this will remove the load queue.

Source:

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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. Note: The Sprite should use a single image and not use a texture that is part of a Texture Atlas or Sprite Sheet.

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:

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

start()

Start loading the assets. Normally you don't need to call this yourself as the StateManager will do so.

Source:

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

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.
Source:
Returns:

This Loader instance.

Type
Phaser.Loader

totalLoadedFiles() → {number}

Returns the number of files that have already been loaded, even if they errored.

Source:
Returns:

The number of files that have already been loaded (even if they errored)

Type
number

totalLoadedPacks() → {number}

Returns the number of asset packs that have already been loaded, even if they errored.

Source:
Returns:

The number of asset packs that have already been loaded (even if they errored)

Type
number

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.

Source:
Returns:

The number of files that still remain in the load queue.

Type
number

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.

Source:
Returns:

The number of asset packs that still remain in the load queue.

Type
number

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:
Phaser Copyright © 2012-2014 Photon Storm Ltd.
Documentation generated by JSDoc 3.3.0-dev on Fri Jul 18 2014 12:36:46 GMT+0100 (BST) using the DocStrap template.