登录内测(欢迎小伙伴们通过右侧登录按钮进行注册和登录)
如果你的英语过了四级,请看: 英文原版

Phaser.Loader

new Loader(game)

加载器加载所有外部内容,如图像、声音、纹理地图集和数据文件。

加载器可以从标签(如图像元素img)和XHR中加载资源,并且提供加载进度和加载完成事件的回调接口。

支持和默认启用并行加载,并行加载前的一些行为可以通过withSyncPoint来控制。

Atlas的素材集可以通过Texture Packer或者Shoebox来制作。

参数:

参数名参数类型描述
gamePhaser.Game当前游戏的引用。

源码 - loader/Loader.js, line 22

成员

<static, constant>PHYSICS_LIME_CORONA_JSON : number

源码 - loader/Loader.js, line 299

<static, constant>PHYSICS_PHASER_JSON : number

源码 - loader/Loader.js, line 305

<static, constant>TEXTURE_ATLAS_JSON_ARRAY : number

源码 - loader/Loader.js, line 281

<static, constant>TEXTURE_ATLAS_JSON_HASH : number

源码 - loader/Loader.js, line 287

<static, constant>TEXTURE_ATLAS_JSON_PYXEL : number

源码 - loader/Loader.js, line 311

<static, constant>TEXTURE_ATLAS_XML_STARLING : number

源码 - loader/Loader.js, line 293

_withSyncPointDepth : integer

一个计数器,如果大于0,文件将自动添加为同步点。

源码 - loader/Loader.js, line 204

baseURL : string

如果你想在所有资源前面添加一个URL,可以设置此参数。这个参数必须以/结尾

源码 - loader/Loader.js, line 83

crossOrigin : boolean|string

跨域设置,此值经常被设置为'anonymous'

源码 - loader/Loader.js, line 74

enableParallel : integer

并行加载,默认开启。如果要关闭,要在加载资源前,设置此值为false。

源码 - loader/Loader.js, line 188

hasLoaded : boolean

如果所有资源都加载完成,此值为true。

源码 - loader/Loader.js, line 57

isLoading : boolean

如果正在加载资源,此值为true。

源码 - loader/Loader.js, line 50

onFileComplete : Phaser.Signal

当一个资源文件(file)加载成功或者加载失败时,触发此信号。它的回调函数将接受以下参数:进度、文件的key、是否成功、总共加载了多少文件、总共要加载多少文件。其中进度是一个1到100的数,表示百分比。

源码 - loader/Loader.js, line 152

onFileError : Phaser.Signal

当一个资源文件(file)或者资源包(pack)加载失败时,触发此信号。如果是资源文件(file),它会在onFileComplete之前被触发。如果是资源包(pack),它会在onPackComplete之前被触发。

参数:(file key, file)

源码 - loader/Loader.js, line 163

onFileStart : Phaser.Signal

当一个资源文件开始加载的时候,触发此信号。这个信号触发后,资源文件可能加载成功,也可能加载失败。

参数:(progress, file key, file url)

源码 - loader/Loader.js, line 139

onLoadComplete : Phaser.Signal

最后一个资源加载完成或加载失败时,触发此信号。

源码 - loader/Loader.js, line 118

onLoadStart : Phaser.Signal

加载进度开始计算时,触发此信号。发生于第一个资源文件被请求前,但是在包(pack)描述文件被加载后

源码 - loader/Loader.js, line 111

onPackComplete : Phaser.Signal

当一个资源包加载完成或者加载失败时,触发此信号。当一个资源包的清单(manifest)文件加载成功,并且把内容加入加载队列(loader queue)的时候触发此信号。

参数:(pack key, success?, total packs loaded, total packs)

源码 - loader/Loader.js, line 129

path : string

如果设置此值,将在所有相对路径前加上它。比如:

load.path = "images/sprites/";

load.image("ball", "ball.png");

load.image("tree", "level1/oaktree.png");

load.image("boom", "http://server.com/explode.png");

会从images/sprites/ball.png去加载ball,从images/sprites/level1/oaktree.png去加载tree,但是从http://server.com/explode.png去加载boom

path会被加在文件名前,但是在baseURL之后,要以'/'结尾

源码 - loader/Loader.js, line 103

progress : integer

取整后的进度(0-100)

源码 - loader/Loader.js, line 2987

progressFloat : number

进度(0.0-100.0)。在很多文件动态加载的情况下,进度可能会反而变小。

源码 - loader/Loader.js, line 2969

resetLocked : boolean

如果此值为true,则Loader.reset不起作用。如果你要在进入加载场景前创建一个加载队列,可以用这个。

源码 - loader/Loader.js, line 43

方法

addSyncPoint(type, key) : → {Phaser.Loader}

在加载队列中给指定文件添加一个同步点。对于已经加载过的文件无效。

参数:

参数名参数类型描述
typestring资源类型(image, audio, xml 等)。
keystring资源索引(key)。

返回:Phaser.Loader,加载器引用。

源码 - loader/Loader.js, line 1631

atlas(key, textureURL, atlasURL, atlasData, format) : → {Phaser.Loader}

在加载队列中添加一个atlas资源文件。Atlas的素材集可以通过Texture Packer或者Shoebox来制作。如果用Texture Packer,建议勾选Trim sprite names。生成资源的时候不要选择“旋转”。

你可以通过URL来提供一个json文件,也可以通过参数atlasData,传递一个json对象或者一个string。如果你传入string,会被直接JSON.parse,然后被加入到Phaser.Cache。

如果提供的是URL,文件不会马上被加载,而是被放入加载队列。参数key要是唯一的,它会是Phaser.Cache中的键。

可以通过Cache.getImage(key)来获取文件。JSON文件会被自动加载解析。如果你希望控制JSON文件的解析,那就用Loader.text

URL可以是相对路径,也可以是绝对路径。如果是相对路径,Loader.baseURLLoader.path会加在它前面。

如果没有传textureURL参数,Loader会自动创建一个文件名。比如key是player,textureURL没传,Loader会将URL设置为player.png。对于atlasURL来说是一样的,比如key是player,atlasURL会变成player.json。如果你不希望这样,就传参数或者传json对象。

参数:

参数名参数类型是否可选描述
keystring资源索引(key)。
textureURLstring可选texture图像URL。如果是null,会被设置为<key>.png,例如key是alien,URL会被设置为alien.png
atlasURLstring可选atlas数据文件URL。如果是null,会被设置为<key>.json,例如key是alien,URL会被设置为alien.json
atlasDataobject可选JSON或者XML对象,如果指定了URL,就不需要此参数。
formatnumber可选数据格式。可以是 Phaser.Loader.TEXTURE_ATLAS_JSON_ARRAY(默认), Phaser.Loader.TEXTURE_ATLAS_JSON_HASH 或者 Phaser.Loader.TEXTURE_ATLAS_XML_STARLING

返回:Phaser.Loader,加载器引用。

源码 - loader/Loader.js, line 1500

atlasJSONArray(key, textureURL, atlasURL, atlasData) : → {Phaser.Loader}

在加载队列中添加一个atlas资源文件。希望数据是JSON数组。Atlas的素材集可以通过Texture Packer或者Shoebox来制作。如果用Texture Packer,建议勾选Trim sprite names。生成资源的时候不要选择“旋转”。

你可以通过URL来提供一个json文件,也可以通过参数atlasData,传递一个json对象或者一个string。如果你传入string,会被直接JSON.parse,然后被加入到Phaser.Cache。

如果提供的是URL,文件不会马上被加载,而是被放入加载队列。参数key要是唯一的,它会是Phaser.Cache中的键。

可以通过Cache.getImage(key)来获取文件。JSON文件会被自动加载解析。如果你希望控制JSON文件的解析,那就用Loader.text

URL可以是相对路径,也可以是绝对路径。如果是相对路径,Loader.baseURLLoader.path会加在它前面。

如果没有传textureURL参数,Loader会自动创建一个文件名。比如key是player,textureURL没传,Loader会将URL设置为player.png。对于atlasURL来说是一样的,比如key是player,atlasURL会变成player.json。如果你不希望这样,就传参数或者传json对象。

参数:

参数名参数类型是否可选描述
keystring资源索引(key)。
textureURLstring可选texture图像URL。如果是null,会被设置为<key>.png,例如key是alien,URL会被设置为alien.png
atlasURLstring可选atlas数据文件URL。如果是null,会被设置为<key>.json,例如key是alien,URL会被设置为alien.json
atlasDataobject可选JSON或者XML对象,如果指定了URL,就不需要此参数。

返回:Phaser.Loader,加载器引用。

源码 - loader/Loader.js, line 1354

atlasJSONHash(key, textureURL, atlasURL, atlasData) : → {Phaser.Loader}

在加载队列中添加一个atlas资源文件。希望数据是JSON对象。Atlas的素材集可以通过Texture Packer或者Shoebox来制作。如果用Texture Packer,建议勾选Trim sprite names。生成资源的时候不要选择“旋转”。

你可以通过URL来提供一个json文件,也可以通过参数atlasData,传递一个json对象或者一个string。如果你传入string,会被直接JSON.parse,然后被加入到Phaser.Cache。

如果提供的是URL,文件不会马上被加载,而是被放入加载队列。参数key要是唯一的,它会是Phaser.Cache中的键。

可以通过Cache.getImage(key)来获取文件。JSON文件会被自动加载解析。如果你希望控制JSON文件的解析,那就用Loader.text

URL可以是相对路径,也可以是绝对路径。如果是相对路径,Loader.baseURLLoader.path会加在它前面。

如果没有传textureURL参数,Loader会自动创建一个文件名。比如key是player,textureURL没传,Loader会将URL设置为player.png。对于atlasURL来说是一样的,比如key是player,atlasURL会变成player.json。如果你不希望这样,就传参数或者传json对象。

参数:

参数名参数类型是否可选描述
keystring资源索引(key)。
textureURLstring可选texture图像URL。如果是null,会被设置为<key>.png,例如key是alien,URL会被设置为alien.png
atlasURLstring可选atlas数据文件URL。如果是null,会被设置为<key>.json,例如key是alien,URL会被设置为alien.json
atlasDataobject可选JSON或者XML对象,如果指定了URL,就不需要此参数。

返回:Phaser.Loader,加载器引用。

源码 - loader/Loader.js, line 1400

atlasXML(key, textureURL, atlasURL, atlasData) : → {Phaser.Loader}

在加载队列中添加一个atlas资源文件。希望数据是XML格式。Atlas的素材集可以通过Texture Packer或者Shoebox来制作。如果用Texture Packer,建议勾选Trim sprite names。生成资源的时候不要选择“旋转”。

你可以通过URL来提供一个json文件,也可以通过参数atlasData,传递一个json对象或者一个string。如果你传入string,会被直接JSON.parse,然后被加入到Phaser.Cache。

如果提供的是URL,文件不会马上被加载,而是被放入加载队列。参数key要是唯一的,它会是Phaser.Cache中的键。

可以通过Cache.getImage(key)来获取文件。JSON文件会被自动加载解析。如果你希望控制JSON文件的解析,那就用Loader.text

URL可以是相对路径,也可以是绝对路径。如果是相对路径,Loader.baseURLLoader.path会加在它前面。

如果没有传textureURL参数,Loader会自动创建一个文件名。比如key是player,textureURL没传,Loader会将URL设置为player.png。对于atlasURL来说是一样的,比如key是player,atlasURL会变成player.json。如果你不希望这样,就传参数或者传json对象。

参数:

参数名参数类型是否可选描述
keystring资源索引(key)。
textureURLstring可选texture图像URL。如果是null,会被设置为<key>.png,例如key是alien,URL会被设置为alien.png
atlasURLstring可选atlas数据文件URL。如果是null,会被设置为<key>.json,例如key是alien,URL会被设置为alien.json
atlasDataobject可选JSON或者XML对象,如果指定了URL,就不需要此参数。

返回:Phaser.Loader,加载器引用。

源码 - loader/Loader.js, line 1446

audio(key, urls, autoDecode) : → {Phaser.Loader}

在加载队列中添加一个音频文件。调用这个方法之后,文件不会马上加载,只是放到了加载队列。key必须唯一。

可以通过Cache.getSound(key)来获取文件。

URL可以是相对路径,也可以是绝对路径。如果是相对路径,Loader.baseURLLoader.path会加在它前面。

移动端请注意:有一些设备(如ipad2,ipad mini)不能播放48000Hz的音频,会导致音频播放系统奔溃,解决方案是使用低频的音频,比如44100Hz。

参数:

参数名参数类型是否可选默认值描述
keystring音频文件的键值。
urlsstring|Array.<string>|Array.<object>字符串,字符串数组,或者是一个对象数组,数组中的元素都是{uri: .., type: ..}。如果是一个数组,那么第一个设备兼容的URI会被选择。比如:"jump.mp3"['jump.mp3', 'jump.ogg', 'jump.m4a']或者[{uri: "data:<opus_resource>", type: 'opus'}, 'fallback.mp3']。BLOB和DATA URIs只能用对象数组方式加载。
autoDecodeboolean可选true使用Web Audio时,音频资源可以在加载时解码,也可以在运行时解码。因为音频文件在使用前必须先解码,如果此值为true,那么音频被加载后就会马上解码。音频解码是异步的,但是会严重耗费CPU,尤其是在移动端。

返回:Phaser.Loader,加载器引用。

源码 - loader/Loader.js, line 968

audiosprite(key, urls, jsonURL, jsonData, autoDecode) : → {Phaser.Loader}

在加载队列中添加一个音频精灵。调用这个方法之后,文件不会马上加载,只是放到了加载队列。key必须唯一。

音频精灵是音频文件和JSON配置的组合。JSON格式可以参考https://github.com/tonistiigi/audiosprite

可以通过Cache.getSoundData(key)来获取文件。

URL可以是相对路径,也可以是绝对路径。如果是相对路径,Loader.baseURLLoader.path会加在它前面。

参数:

参数名参数类型是否可选默认值描述
keystring音频精灵的键值。
urlsArray|string可以是一个包含音频文件URL的数组,例如:['audiosprite.mp3', 'audiosprite.ogg', 'audiosprite.m4a'],也可以是一个字符串,只表示一个音频文件的URL。
jsonURLstring可选null音频精灵的JSON配置文件的URL。如果你想直接传JSON数据,把这个值设为null。
jsonDatastring|object可选null音频精灵的JSON配置对象。如果jsonURL不是null,那么此值会被忽略。
autoDecodeboolean可选true使用Web Audio时,音频资源可以在加载时解码,也可以在运行时解码。因为音频文件在使用前必须先解码,如果此值为true,那么音频被加载后就会马上解码。音频解码是异步的,但是会严重耗费CPU,尤其是在移动端。

返回:Phaser.Loader,加载器引用。

源码 - loader/Loader.js, line 1011

binary(key, url, callback, callbackContext) : → {Phaser.Loader}

在加载队列中添加一个二进制文件。调用这个方法之后,文件不会马上加载,只是放到了加载队列。key必须唯一。

可以通过Cache.getBinary(key)来获取文件。

URL可以是相对路径,也可以是绝对路径。如果是相对路径,Loader.baseURLLoader.path会加在它前面。

如果没有指定URL,加载器会根据key生成一个文件名。例如key是alien,没指定URL,加载器会把URL设置为alien.bin。

它会通过xhr加载,返回类型是arraybuffer。你可以在文件加载完成后设置一个回调来处理数据,回调有两个参数,文件key和文件数据。

参数:

参数名参数类型是否可选默认值描述
keystring二进制文件的键值。
urlstring可选二进制文件的URL。如果是undefined或者null,URL会被设置为<key>.bin,例如:key是alien,URL就是alien.bin
callbackfunction可选(none)文件加载完成后的回调函数,你可以在这里对二进制进行进一步处理。
callbackContextobject可选回调的上下文,如果没有指定,会用callback自己作为上下文。

返回:Phaser.Loader,加载器引用。

源码 - loader/Loader.js, line 888

bitmapFont(key, textureURL, atlasURL, atlasData, xSpacing, ySpacing) : → {Phaser.Loader}

在加载队列中添加一个位图字体文件。

Windows下可以用BMFont(免费),mac下可以用Glyph Designer(商业版收费),或者用web在线的Littera(免费)都可以创建位图字体。

你可以通过提供一个XML文件的URL地址,从网络加载字体。或者给atlasData传一个XML对象或者字符串。如果传字符串,它会被Loader.parseXML直接解析成XML对象放入Phaser.Cache。

调用这个方法之后,文件不会马上加载,只是放到了加载队列。key必须唯一。

可以通过Cache.getBitmapFont(key)来获取文件。XML文件会在加载后自动解析,如果你需要控制XML的解析时间,你可以用Loader.text,然后自己解析XML文件。

URL可以是相对路径,也可以是绝对路径。如果是相对路径,Loader.baseURLLoader.path会加在它前面。

如果没有指定textureURL,加载器会根据key生成一个文件名。例如key是megaFont,没指定URL,加载器会把URL设置为megaFont.png。atlasURL也一样,如果没有指定atlasURL,也没有atlasData,加载器会根据key生成一个atlasURL,例如key是megaFont,则atlasURL是megaFont.xml

如果你不想这样,就提供Url和data。

参数:

参数名参数类型是否可选默认值描述
keystring位图字体文件的键值。
textureURLstring位图字体文件的图片的URL。如果是undefined或者null,URL会被设置为<key>.png,例如:key是megaFont,URL就是megaFont.png
atlasURLstring位图字体文件的描述文件的URL。如果是undefined或者null,而且atlasData也是null,URL会被设置为<key>.xml,例如:key是megaFont,URL就是megaFont.xml
atlasDataobject可选位图字体描述,字符串或者XML对象。
xSpacingnumber可选0字母间的水平间隙。
ySpacingnumber可选0字母间的垂直间隙。

返回:Phaser.Loader,加载器引用。

源码 - loader/Loader.js, line 1263

checkKeyExists(type, key) : → {boolean}

检查一个文件/资源是否在加载队列中。

可以用Phaser.Cache来获取一个已经加载的资源,例如:Phaser.Cache#checkImageKey

参数:

参数名参数类型描述
typestring资源类型(image, audio, xml 等)。
keystring资源索引(key)。

返回:如果存在返回true,否则返回false。

源码 - loader/Loader.js, line 367

getAsset(type, key) : → {any}

获取一个文件/资源。

只有在加载队列中的文件能够被找到。

参数:

参数名参数类型描述
typestring资源类型(image, audio, xml 等)。
keystring资源索引(key)。

返回:如果找到,返回一个有index和file两个属性的对象,否则返回false。index会经常变化,只能在这个函数被调用后马上使用。

源码 - loader/Loader.js, line 418

getAssetIndex(type, key) : → {number}

获取一个文件/资源在加载队列中的索引。

只有在加载队列中的文件能够被找到。

参数:

参数名参数类型描述
typestring资源类型(image, audio, xml 等)。
keystring资源索引(key)。

返回:如果找到,返回文件/资源在加载队列中的索引,否则返回-1。index会经常变化,只能在这个函数被调用后马上使用。

源码 - loader/Loader.js, line 418