Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Loader . File

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Loader . File

The base File class used by all File Types that the Loader can support. You shouldn't create an instance of a File directly, but should extend it with your own class, setting a custom type and processing methods.

Constructor:

new File(loader, fileConfig)

Parameters:

name type description
loader Phaser.Loader.LoaderPlugin

The Loader that is going to load this File.

fileConfig Phaser.Types.Loader.FileConfig

The file configuration object, as created by the file type.

Since: 3.0.0
Source: src/loader/File.js (Line 16)

Members

bytesLoaded: number
Focus
Focus

Description:

Updated as the file loads. Only set if loading via XHR.

Type:
number
Default: -1
Since: 3.0.0
Source: src/loader/File.js (Line 160)
Focus
Focus
bytesTotal: number
Focus
Focus

Description:

The total size of this file. Set by onProgress and only if loading via XHR.

Type:
number
Default: 0
Since: 3.0.0
Source: src/loader/File.js (Line 149)
Focus
Focus

Description:

A reference to the Cache, or Texture Manager, that is going to store this file if it loads.

Type:
Since: 3.7.0
Source: src/loader/File.js (Line 44)
Focus
Focus
config: *
Focus
Focus

Description:

A config object that can be used by file types to store transitional data.

Type:
*
Since: 3.0.0
Source: src/loader/File.js (Line 201)
Focus
Focus
crossOrigin: string | undefined
Focus
Focus

Description:

For CORs based loading. If this is undefined then the File will check BaseLoader.crossOrigin and use that (if set)

Type:
string | undefined
Since: 3.0.0
Source: src/loader/File.js (Line 182)
Focus
Focus
data: *
Focus
Focus

Description:

The processed file data, stored here after the file has loaded.

Type:
*
Since: 3.0.0
Source: src/loader/File.js (Line 192)
Focus
Focus
key: string
Focus
Focus

Description:

Unique cache key (unique within its file type)

Type:
string
Since: 3.0.0
Source: src/loader/File.js (Line 62)
Focus
Focus
<nullable> linkFile: Phaser.Loader.File
Focus
Focus

Description:

Does this file have an associated linked file? Such as an image and a normal map. Atlases and Bitmap Fonts use the multiFile, because those files need loading together but aren't actually bound by data, where-as a linkFile is.

Type:
Since: 3.7.0
Source: src/loader/File.js (Line 220)
Focus
Focus

Description:

A reference to the Loader that is going to load this file.

Type:
Since: 3.0.0
Source: src/loader/File.js (Line 35)
Focus
Focus
<nullable> multiFile: Phaser.Loader.MultiFile
Focus
Focus

Description:

If this is a multipart file, i.e. an atlas and its json together, then this is a reference to the parent MultiFile. Set and used internally by the Loader or specific file types.

Type:
Since: 3.7.0
Source: src/loader/File.js (Line 210)
Focus
Focus
percentComplete: number
Focus
Focus

Description:

A percentage value between 0 and 1 indicating how much of this file has loaded. Only set if loading via XHR.

Type:
number
Default: -1
Since: 3.0.0
Source: src/loader/File.js (Line 171)
Focus
Focus
src: string
Focus
Focus

Description:

The final URL this file will load from, including baseURL and path. Set automatically when the Loader calls 'load' on this file.

Type:
string
Since: 3.0.0
Source: src/loader/File.js (Line 107)
Focus
Focus
state: number
Focus
Focus

Description:

The current state of the file. One of the FILE_CONST values.

Type:
number
Since: 3.0.0
Source: src/loader/File.js (Line 140)
Focus
Focus
type: string
Focus
Focus

Description:

The file type string (image, json, etc) for sorting within the Loader.

Type:
string
Since: 3.0.0
Source: src/loader/File.js (Line 53)
Focus
Focus
url: object | string
Focus
Focus

Description:

The URL of the file, not including baseURL.

Automatically has Loader.path prepended to it if a string.

Can also be a JavaScript Object, such as the results of parsing JSON data.

Type:
object | string
Since: 3.0.0
Source: src/loader/File.js (Line 94)
Focus
Focus
<nullable> xhrLoader: XMLHttpRequest
Focus
Focus

Description:

The XMLHttpRequest instance (as created by XHR Loader) that is loading this File.

Type:
XMLHttpRequest
Since: 3.0.0
Source: src/loader/File.js (Line 131)
Focus
Focus

Description:

The merged XHRSettings for this file.

Type:
Since: 3.0.0
Source: src/loader/File.js (Line 117)
Focus
Focus

Methods

addToCache()
Focus
Focus

Description:

Adds this file to its target cache upon successful loading and processing. This method is often overridden by specific file types.

Examples:
Since: 3.7.0
Source: src/loader/File.js (Line 440)
Focus
Focus
destroy()
Focus
Focus

Description:

Destroy this File and any references it holds.

Examples:
Since: 3.7.0
Source: src/loader/File.js (Line 479)
Focus
Focus
hasCacheConflict()
Focus
Focus

Description:

Checks if a key matching the one used by this file exists in the target Cache or not. This is called automatically by the LoaderPlugin to decide if the file can be safely loaded or will conflict.

Returns:
Description:

true if adding this file will cause a conflict, otherwise false.

Type:
  • boolean
Examples:
Since: 3.7.0
Source: src/loader/File.js (Line 425)
Focus
Focus
load()
Focus
Focus

Description:

Called by the Loader, starts the actual file downloading. During the load the methods onLoad, onError and onProgress are called, based on the XHR events. You shouldn't normally call this method directly, it's meant to be invoked by the Loader.

Examples:
Since: 3.0.0
Source: src/loader/File.js (Line 263)
Focus
Focus
onError(xhr, event)
Focus
Focus

Description:

Called if the file errors while loading, is sent a DOM ProgressEvent.

Parameters:

name type description
xhr XMLHttpRequest

The XMLHttpRequest that caused this onload event.

event ProgressEvent

The DOM ProgressEvent that resulted from this error.

Examples:
Since: 3.0.0
Source: src/loader/File.js (Line 335)
Focus
Focus
onLoad(xhr, event)
Focus
Focus

Description:

Called when the file finishes loading, is sent a DOM ProgressEvent.

Parameters:

name type description
xhr XMLHttpRequest

The XMLHttpRequest that caused this onload event.

event ProgressEvent

The DOM ProgressEvent that resulted from this load.

Examples:
Since: 3.0.0
Source: src/loader/File.js (Line 302)
Focus
Focus
onProcess()
Focus
Focus

Description:

Usually overridden by the FileTypes and is called by Loader.nextFile. This method controls what extra work this File does with its loaded data, for example a JSON file will parse itself during this stage.

Examples:
Since: 3.0.0
Source: src/loader/File.js (Line 373)
Focus
Focus
onProcessComplete()
Focus
Focus

Description:

Called when the File has completed processing. Checks on the state of its multifile, if set.

Examples:
Since: 3.7.0
Source: src/loader/File.js (Line 387)
Focus
Focus
onProcessError()
Focus
Focus

Description:

Called when the File has completed processing but it generated an error. Checks on the state of its multifile, if set.

Examples:
Since: 3.7.0
Source: src/loader/File.js (Line 406)
Focus
Focus
onProgress(event)
Focus
Focus

Description:

Called during the file load progress. Is sent a DOM ProgressEvent.

Parameters:

name type description
event ProgressEvent

The DOM ProgressEvent.

Examples:
Since: 3.0.0
Source: src/loader/File.js (Line 351)
Focus
Focus
pendingDestroy()
Focus
Focus

Description:

Called once the file has been added to its cache and is now ready for deletion from the Loader. It will emit a filecomplete event from the LoaderPlugin.

Examples:
Since: 3.7.0
Source: src/loader/File.js (Line 457)
Focus
Focus
resetXHR()
Focus
Focus

Description:

Resets the XHRLoader instance this file is using.

Examples:
Since: 3.0.0
Source: src/loader/File.js (Line 247)
Focus
Focus
<static> createObjectURL(image, blob, defaultType)
Focus
Focus

Description:

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.

Parameters:

name type description
image HTMLImageElement

Image object which 'src' attribute should be set to object URL.

blob Blob

A Blob object to create an object URL for.

defaultType string

Default mime type used if blob type is not available.

Examples:
Since: 3.7.0
Source: src/loader/File.js (Line 497)
Focus
Focus
<static> revokeObjectURL(image)
Focus
Focus

Description:

Static method for releasing an existing object URL which was previously created by calling File#createObjectURL method.

Parameters:

name type description
image HTMLImageElement

Image object which 'src' attribute should be revoked.

Examples:
Since: 3.7.0
Source: src/loader/File.js (Line 531)
Focus
Focus