# 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:
    - loader/Loader.js, line 18

### Members

#### <static, constant> PHYSICS_LIME_CORONA_JSON :number

  ##### Type:

  - number
  Source:
    - loader/Loader.js, line 152

#### <static, constant> PHYSICS_PHASER_JSON :number

  ##### Type:

  - number
  Source:
    - loader/Loader.js, line 158

#### <static, constant> TEXTURE_ATLAS_JSON_ARRAY :number

  ##### Type:

  - number
  Source:
    - loader/Loader.js, line 134

#### <static, constant> TEXTURE_ATLAS_JSON_HASH :number

  ##### Type:

  - number
  Source:
    - loader/Loader.js, line 140

#### <static, constant> TEXTURE_ATLAS_XML_STARLING :number

  ##### Type:

  - number
  Source:
    - loader/Loader.js, line 146

#### 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:
    - loader/Loader.js, line 101

#### 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:
    - loader/Loader.js, line 92

#### game

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `game` | Phaser.Game | Local reference to game.

  Source:
    - loader/Loader.js, line 23

#### hasLoaded

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `hasLoaded` | boolean | True if all assets in the queue have finished loading.

  Default Value:
    - false
  Source:
    - loader/Loader.js, line 66

#### isLoading

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `isLoading` | boolean | True if the Loader is in the process of loading the queue.

  Default Value:
    - false
  Source:
    - loader/Loader.js, line 60

#### onFileComplete

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `onFileComplete` | Phaser.Signal | This event is dispatched when a file completes loading successfully.

  Source:
    - loader/Loader.js, line 116

#### onFileError

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `onFileError` | Phaser.Signal | This event is dispatched when a file errors as a result of the load request.

  Source:
    - loader/Loader.js, line 121

#### 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:
    - loader/Loader.js, line 111

#### 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:
    - loader/Loader.js, line 126

#### 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:
    - loader/Loader.js, line 106

#### 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:
    - loader/Loader.js, line 86

#### progress

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `progress` | number | The rounded load progress percentage value (from 0 to 100)

  Default Value:
    - 0
  Source:
    - loader/Loader.js, line 72

#### progressFloat

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `progressFloat` | number | The non-rounded load progress value (from 0.0 to 100.0)

  Default Value:
    - 0
  Source:
    - loader/Loader.js, line 78

### 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:
    - loader/Loader.js, line 285

#### 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:
    - loader/Loader.js, line 738

  ##### 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:
    - loader/Loader.js, line 690

  ##### 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:
    - loader/Loader.js, line 706

  ##### 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:
    - loader/Loader.js, line 722

  ##### 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:
    - loader/Loader.js, line 511

  ##### 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:
    - loader/Loader.js, line 463

  ##### 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:
    - loader/Loader.js, line 626

  ##### 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:
    - loader/Loader.js, line 195

  ##### 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:
    - loader/Loader.js, line 1328

#### 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:
    - loader/Loader.js, line 1353

#### 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:
    - loader/Loader.js, line 1123

#### 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:
    - loader/Loader.js, line 1104

#### 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:
    - loader/Loader.js, line 246

  ##### 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:
    - loader/Loader.js, line 221

  ##### 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:
    - loader/Loader.js, line 363

  ##### 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:
    - loader/Loader.js, line 415

  ##### 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:
    - loader/Loader.js, line 1292

#### physics(key, dataURL, jsonData, 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.
  `dataURL` | string | <optional> |  | The url of the map data file (csv/json)
  `jsonData` | object | <optional> |  | An optional JSON data object. If given then the dataURL 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:
    - loader/Loader.js, line 583

  ##### Returns:

  This Loader instance.

  Type
    Phaser.Loader

#### removeAll()

  Remove all file loading requests.

  Source:
    - loader/Loader.js, line 836

#### 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:
    - loader/Loader.js, line 818

#### <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:
    - loader/Loader.js, line 321

#### reset()

  Reset loader, this will remove the load queue.

  Source:
    - loader/Loader.js, line 271

#### 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:
    - loader/Loader.js, line 441

  ##### 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:
    - loader/Loader.js, line 162

#### 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:
    - loader/Loader.js, line 486

  ##### 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:
    - loader/Loader.js, line 847

#### 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:
    - loader/Loader.js, line 389

  ##### Returns:

  This Loader instance.

  Type
    Phaser.Loader

#### tilemap(key, mapDataURL, mapData, format) → {Phaser.Loader}

  Add a new tilemap loading request.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `key` | string |  |  | Unique asset key of the tilemap data.
  `mapDataURL` | string | <optional> |  | The url of the map data file (csv/json)
  `mapData` | object | <optional> |  | An optional JSON data object. If given then the mapDataURL 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:
    - loader/Loader.js, line 530

  ##### Returns:

  This Loader instance.

  Type
    Phaser.Loader

#### totalLoadedFiles() → {number}

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

  Source:
    - loader/Loader.js, line 1478

  ##### Returns:

  The number of files 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 is in the queue is loaded.

  Source:
    - loader/Loader.js, line 1499

  ##### Returns:

  The number of files 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:
    - loader/Loader.js, line 1372