Packagestarling.utils
Classpublic class AssetManager
InheritanceAssetManager Inheritance EventDispatcher Inheritance Object

The AssetManager handles loading and accessing a variety of asset types. You can add assets directly (via the 'add...' methods) or asynchronously via a queue. This allows you to deal with assets in a unified way, no matter if they are loaded from a file, directory, URL, or from an embedded object.

The class can deal with the following media types:

For more information on how to add assets from different sources, read the documentation of the "enqueue()" method.

Context Loss

When the stage3D context is lost (and you have enabled 'Starling.handleLostContext'), the AssetManager will automatically restore all loaded textures. To save memory, it will get them from their original sources. Since this is done asynchronously, your images might not reappear all at once, but during a timeframe of several seconds. If you want, you can pause your game during that time; the AssetManager dispatches an "Event.TEXTURES_RESTORED" event when all textures have been restored.

Error handling

Loading of some assets may fail while the queue is being processed. In that case, the AssetManager will dispatch events of type "IO_ERROR", "SECURITY_ERROR" or "PARSE_ERROR". You can listen to those events and handle the errors manually (e.g., you could enqueue them once again and retry, or provide placeholder textures). Queue processing will continue even when those events are dispatched.

Using variable texture formats

When you enqueue a texture, its properties for "format", "scale", "mipMapping", and "repeat" will reflect the settings of the AssetManager at the time they were enqueued. This means that you can enqueue a bunch of textures, then change the settings and enqueue some more. Like this:

      var appDir:File = File.applicationDirectory;
      var assets:AssetManager = new AssetManager();
      
      assets.textureFormat = Context3DTextureFormat.BGRA;
      assets.enqueue(appDir.resolvePath("textures/32bit"));
      
      assets.textureFormat = Context3DTextureFormat.BGRA_PACKED;
      assets.enqueue(appDir.resolvePath("textures/16bit"));
      
      assets.loadQueue(...);


Public Properties
 PropertyDefined By
  checkPolicyFile : Boolean
Specifies whether a check should be made for the existence of a URL policy file before loading an object from a remote server.
AssetManager
  forcePotTextures : Boolean
Indicates if the underlying Stage3D textures should be created as the power-of-two based Texture class instead of the more memory efficient RectangleTexture.
AssetManager
  isLoading : Boolean
[read-only] Indicates if a queue is currently being loaded.
AssetManager
  keepAtlasXmls : Boolean
Indicates if atlas XML data should be stored for access via the 'getXml' method.
AssetManager
  keepFontXmls : Boolean
Indicates if bitmap font XML data should be stored for access via the 'getXml' method.
AssetManager
  numConnections : int
The maximum number of parallel connections that are spawned when loading the queue.
AssetManager
  numQueuedAssets : int
[read-only] Returns the number of raw assets that have been enqueued, but not yet loaded.
AssetManager
  scaleFactor : Number
Textures that are created from Bitmaps or ATF files will have the scale factor assigned here.
AssetManager
  textureFormat : String
Textures that are created from Bitmaps will be uploaded to the GPU with the Context3DTextureFormat assigned to this property.
AssetManager
  useMipMaps : Boolean
For bitmap textures, this flag indicates if mip maps should be generated when they are loaded; for ATF textures, it indicates if mip maps are valid and should be used.
AssetManager
  verbose : Boolean
When activated, the class will trace information about added/enqueued assets.
AssetManager
Protected Properties
 PropertyDefined By
  queue : Array
[read-only] The queue contains one 'Object' for each enqueued asset.
AssetManager
Public Methods
 MethodDefined By
  
AssetManager(scaleFactor:Number = 1, useMipmaps:Boolean = false)
Create a new AssetManager.
AssetManager
  
addByteArray(name:String, byteArray:ByteArray):void
Register a byte array under a certain name.
AssetManager
 Inherited
addEventListener(type:String, listener:Function):void
Registers an event listener at a certain object.
EventDispatcher
  
addObject(name:String, object:Object):void
Register an arbitrary object under a certain name.
AssetManager
  
addSound(name:String, sound:Sound):void
Register a sound under a certain name.
AssetManager
  
addTexture(name:String, texture:Texture):void
Register a texture under a certain name.
AssetManager
  
addTextureAtlas(name:String, atlas:TextureAtlas):void
Register a texture atlas under a certain name.
AssetManager
  
addXml(name:String, xml:XML):void
Register an XML object under a certain name.
AssetManager
 Inherited
dispatchEvent(event:Event):void
Dispatches an event to all objects that have registered listeners for its type.
EventDispatcher
 Inherited
dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void
Dispatches an event with the given parameters to all objects that have registered listeners for the given type.
EventDispatcher
  
dispose():void
Disposes all contained textures, XMLs and ByteArrays.
AssetManager
  
enqueue(... rawAssets):void
Enqueues one or more raw assets; they will only be available after successfully executing the "loadQueue" method.
AssetManager
  
enqueueWithName(asset:Object, name:String = null, options:TextureOptions = null):String
Enqueues a single asset with a custom name that can be used to access it later.
AssetManager
  
getByteArray(name:String):ByteArray
Returns a byte array with a certain name, or null if it's not found.
AssetManager
  
getByteArrayNames(prefix:String, out:Vector.<String> = null):Vector.<String>
Returns all byte array names that start with a certain string, sorted alphabetically.
AssetManager
  
getObject(name:String):Object
Returns an object with a certain name, or null if it's not found.
AssetManager
  
getObjectNames(prefix:String, out:Vector.<String> = null):Vector.<String>
Returns all object names that start with a certain string, sorted alphabetically.
AssetManager
  
getSound(name:String):Sound
Returns a sound with a certain name, or null if it's not found.
AssetManager
  
getSoundNames(prefix:String, out:Vector.<String> = null):Vector.<String>
Returns all sound names that start with a certain string, sorted alphabetically.
AssetManager
  
getTexture(name:String):Texture
Returns a texture with a certain name.
AssetManager
  
getTextureAtlas(name:String):TextureAtlas
Returns a texture atlas with a certain name, or null if it's not found.
AssetManager
  
getTextureAtlasNames(prefix:String, out:Vector.<String> = null):Vector.<String>
Returns all texture atlas names that start with a certain string, sorted alphabetically.
AssetManager
  
getTextureNames(prefix:String, out:Vector.<String> = null):Vector.<String>
Returns all texture names that start with a certain string, sorted alphabetically.
AssetManager
  
getTextures(prefix:String, out:Vector.<Texture> = null):Vector.<Texture>
Returns all textures that start with a certain string, sorted alphabetically (especially useful for "MovieClip").
AssetManager
  
getXml(name:String):XML
Returns an XML with a certain name, or null if it's not found.
AssetManager
  
getXmlNames(prefix:String, out:Vector.<String> = null):Vector.<String>
Returns all XML names that start with a certain string, sorted alphabetically.
AssetManager
 Inherited
hasEventListener(type:String, listener:Function = null):Boolean
If called with one argument, figures out if there are any listeners registered for the given event type.
EventDispatcher
  
loadQueue(onProgress:Function):void
Loads all enqueued assets asynchronously.
AssetManager
  
playSound(name:String, startTime:Number = 0, loops:int = 0, transform:SoundTransform = null):SoundChannel
Generates a new SoundChannel object to play back the sound.
AssetManager
  
purge():void
Removes assets of all types (disposing them along the way), empties the queue and aborts any pending load operations.
AssetManager
  
purgeQueue():void
Empties the queue and aborts any pending load operations.
AssetManager
  
removeByteArray(name:String, dispose:Boolean = true):void
Removes a certain byte array, optionally disposing its memory right away.
AssetManager
 Inherited
removeEventListener(type:String, listener:Function):void
Removes an event listener from the object.
EventDispatcher
 Inherited
removeEventListeners(type:String = null):void
Removes all event listeners with a certain type, or all of them if type is null.
EventDispatcher
  
removeObject(name:String):void
Removes a certain object.
AssetManager
  
removeSound(name:String):void
Removes a certain sound.
AssetManager
  
removeTexture(name:String, dispose:Boolean = true):void
Removes a certain texture, optionally disposing it.
AssetManager
  
removeTextureAtlas(name:String, dispose:Boolean = true):void
Removes a certain texture atlas, optionally disposing it.
AssetManager
  
removeXml(name:String, dispose:Boolean = true):void
Removes a certain Xml object, optionally disposing it.
AssetManager
Protected Methods
 MethodDefined By
  
getBasenameFromUrl(url:String):String
Extracts the base name of a file path or URL, i.e.
AssetManager
  
getExtensionFromUrl(url:String):String
Extracts the file extension from an URL.
AssetManager
  
getName(rawAsset:Object):String
This method is called by 'enqueue' to determine the name under which an asset will be accessible; override it if you need a custom naming scheme.
AssetManager
  
loadRawAsset(rawAsset:Object, onProgress:Function, onComplete:Function):void
This method is called internally for each element of the queue when it is loaded.
AssetManager
  
log(message:String):void
This method is called during loading of assets when 'verbose' is activated.
AssetManager
  
transformData(data:ByteArray, url:String):ByteArray
This method is called when raw byte data has been loaded from an URL or a file.
AssetManager
Events
 Event Summary Defined By
  
ioError
Dispatched when an URLLoader fails with an IO_ERROR while processing the queue.AssetManager
  
parseError
Dispatched when an XML or JSON file couldn't be parsed.AssetManager
  
securityError
Dispatched when an URLLoader fails with a SECURITY_ERROR while processing the queue.AssetManager
  
texturesRestored
Dispatched when all textures have been restored after a context loss.AssetManager
Property Detail
checkPolicyFileproperty
checkPolicyFile:Boolean

Specifies whether a check should be made for the existence of a URL policy file before loading an object from a remote server. More information about this topic can be found in the 'flash.system.LoaderContext' documentation.

The default value is false.


Implementation
    public function get checkPolicyFile():Boolean
    public function set checkPolicyFile(value:Boolean):void
forcePotTexturesproperty 
forcePotTextures:Boolean

Indicates if the underlying Stage3D textures should be created as the power-of-two based Texture class instead of the more memory efficient RectangleTexture.

The default value is false.


Implementation
    public function get forcePotTextures():Boolean
    public function set forcePotTextures(value:Boolean):void
isLoadingproperty 
isLoading:Boolean  [read-only]

Indicates if a queue is currently being loaded.


Implementation
    public function get isLoading():Boolean
keepAtlasXmlsproperty 
keepAtlasXmls:Boolean

Indicates if atlas XML data should be stored for access via the 'getXml' method. If true, you can access an XML under the same name as the atlas. If false, XMLs will be disposed when the atlas was created.

The default value is false..


Implementation
    public function get keepAtlasXmls():Boolean
    public function set keepAtlasXmls(value:Boolean):void
keepFontXmlsproperty 
keepFontXmls:Boolean

Indicates if bitmap font XML data should be stored for access via the 'getXml' method. If true, you can access an XML under the same name as the bitmap font. If false, XMLs will be disposed when the font was created.

The default value is false..


Implementation
    public function get keepFontXmls():Boolean
    public function set keepFontXmls(value:Boolean):void
numConnectionsproperty 
numConnections:int

The maximum number of parallel connections that are spawned when loading the queue. More connections can reduce loading times, but require more memory.

The default value is 3..


Implementation
    public function get numConnections():int
    public function set numConnections(value:int):void
numQueuedAssetsproperty 
numQueuedAssets:int  [read-only]

Returns the number of raw assets that have been enqueued, but not yet loaded.


Implementation
    public function get numQueuedAssets():int
queueproperty 
queue:Array  [read-only]

The queue contains one 'Object' for each enqueued asset. Each object has 'asset' and 'name' properties, pointing to the raw asset and its name, respectively.


Implementation
    protected function get queue():Array
scaleFactorproperty 
scaleFactor:Number

Textures that are created from Bitmaps or ATF files will have the scale factor assigned here.

The default value is 1.


Implementation
    public function get scaleFactor():Number
    public function set scaleFactor(value:Number):void
textureFormatproperty 
textureFormat:String

Textures that are created from Bitmaps will be uploaded to the GPU with the Context3DTextureFormat assigned to this property.

The default value is "bgra".


Implementation
    public function get textureFormat():String
    public function set textureFormat(value:String):void
useMipMapsproperty 
useMipMaps:Boolean

For bitmap textures, this flag indicates if mip maps should be generated when they are loaded; for ATF textures, it indicates if mip maps are valid and should be used.

The default value is false.


Implementation
    public function get useMipMaps():Boolean
    public function set useMipMaps(value:Boolean):void
verboseproperty 
verbose:Boolean

When activated, the class will trace information about added/enqueued assets.

The default value is true.


Implementation
    public function get verbose():Boolean
    public function set verbose(value:Boolean):void
Constructor Detail
AssetManager()Constructor
public function AssetManager(scaleFactor:Number = 1, useMipmaps:Boolean = false)

Create a new AssetManager. The 'scaleFactor' and 'useMipmaps' parameters define how enqueued bitmaps will be converted to textures.

Parameters
scaleFactor:Number (default = 1)
 
useMipmaps:Boolean (default = false)
Method Detail
addByteArray()method
public function addByteArray(name:String, byteArray:ByteArray):void

Register a byte array under a certain name. It will be available right away. If the name was already taken, the existing byte array will be cleared and replaced by the new one.

Parameters

name:String
 
byteArray:ByteArray

addObject()method 
public function addObject(name:String, object:Object):void

Register an arbitrary object under a certain name. It will be available right away. If the name was already taken, the existing object will be replaced by the new one.

Parameters

name:String
 
object:Object

addSound()method 
public function addSound(name:String, sound:Sound):void

Register a sound under a certain name. It will be available right away. If the name was already taken, the existing sound will be replaced by the new one.

Parameters

name:String
 
sound:Sound

addTexture()method 
public function addTexture(name:String, texture:Texture):void

Register a texture under a certain name. It will be available right away. If the name was already taken, the existing texture will be disposed and replaced by the new one.

Parameters

name:String
 
texture:Texture

addTextureAtlas()method 
public function addTextureAtlas(name:String, atlas:TextureAtlas):void

Register a texture atlas under a certain name. It will be available right away. If the name was already taken, the existing atlas will be disposed and replaced by the new one.

Parameters

name:String
 
atlas:TextureAtlas

addXml()method 
public function addXml(name:String, xml:XML):void

Register an XML object under a certain name. It will be available right away. If the name was already taken, the existing XML will be disposed and replaced by the new one.

Parameters

name:String
 
xml:XML

dispose()method 
public function dispose():void

Disposes all contained textures, XMLs and ByteArrays.

Beware that all references to the assets will remain intact, even though the assets are no longer valid. Call 'purge' if you want to remove all resources and reuse the AssetManager later.

enqueue()method 
public function enqueue(... rawAssets):void

Enqueues one or more raw assets; they will only be available after successfully executing the "loadQueue" method. This method accepts a variety of different objects:

Suitable object names are extracted automatically: A file named "image.png" will be accessible under the name "image". When enqueuing embedded assets via a class, the variable name of the embedded object will be used as its name. An exception are texture atlases: they will have the same name as the actual texture they are referencing.

XMLs that contain texture atlases or bitmap fonts are processed directly: fonts are registered at the TextField class, atlas textures can be acquired with the "getTexture()" method. All other XMLs are available via "getXml()".

If you pass in JSON data, it will be parsed into an object and will be available via "getObject()".

Parameters

... rawAssets

enqueueWithName()method 
public function enqueueWithName(asset:Object, name:String = null, options:TextureOptions = null):String

Enqueues a single asset with a custom name that can be used to access it later. If the asset is a texture, you can also add custom texture options.

Parameters

asset:Object — The asset that will be enqueued; accepts the same objects as the 'enqueue' method.
 
name:String (default = null) — The name under which the asset will be found later. If you pass null or omit the parameter, it's attempted to generate a name automatically.
 
options:TextureOptions (default = null) — Custom options that will be used if 'asset' points to texture data.

Returns
String — the name with which the asset was registered.
getBasenameFromUrl()method 
protected function getBasenameFromUrl(url:String):String

Extracts the base name of a file path or URL, i.e. the file name without extension.

Parameters

url:String

Returns
String
getByteArray()method 
public function getByteArray(name:String):ByteArray

Returns a byte array with a certain name, or null if it's not found.

Parameters

name:String

Returns
ByteArray
getByteArrayNames()method 
public function getByteArrayNames(prefix:String, out:Vector.<String> = null):Vector.<String>

Returns all byte array names that start with a certain string, sorted alphabetically. If you pass an out-vector, the names will be added to that vector.

Parameters

prefix:String
 
out:Vector.<String> (default = null)

Returns
Vector.<String>
getExtensionFromUrl()method 
protected function getExtensionFromUrl(url:String):String

Extracts the file extension from an URL.

Parameters

url:String

Returns
String
getName()method 
protected function getName(rawAsset:Object):String

This method is called by 'enqueue' to determine the name under which an asset will be accessible; override it if you need a custom naming scheme. Note that this method won't be called for embedded assets.

Parameters

rawAsset:Object — either a String, an URLRequest or a FileReference.

Returns
String
getObject()method 
public function getObject(name:String):Object

Returns an object with a certain name, or null if it's not found. Enqueued JSON data is parsed and can be accessed with this method.

Parameters

name:String

Returns
Object
getObjectNames()method 
public function getObjectNames(prefix:String, out:Vector.<String> = null):Vector.<String>

Returns all object names that start with a certain string, sorted alphabetically. If you pass an out-vector, the names will be added to that vector.

Parameters

prefix:String
 
out:Vector.<String> (default = null)

Returns
Vector.<String>
getSound()method 
public function getSound(name:String):Sound

Returns a sound with a certain name, or null if it's not found.

Parameters

name:String

Returns
Sound
getSoundNames()method 
public function getSoundNames(prefix:String, out:Vector.<String> = null):Vector.<String>

Returns all sound names that start with a certain string, sorted alphabetically. If you pass an out-vector, the names will be added to that vector.

Parameters

prefix:String
 
out:Vector.<String> (default = null)

Returns
Vector.<String>
getTexture()method 
public function getTexture(name:String):Texture

Returns a texture with a certain name. The method first looks through the directly added textures; if no texture with that name is found, it scans through all texture atlases.

Parameters

name:String

Returns
Texture
getTextureAtlas()method 
public function getTextureAtlas(name:String):TextureAtlas

Returns a texture atlas with a certain name, or null if it's not found.

Parameters

name:String

Returns
TextureAtlas
getTextureAtlasNames()method 
public function getTextureAtlasNames(prefix:String, out:Vector.<String> = null):Vector.<String>

Returns all texture atlas names that start with a certain string, sorted alphabetically. If you pass an out-vector, the names will be added to that vector.

Parameters

prefix:String
 
out:Vector.<String> (default = null)

Returns
Vector.<String>
getTextureNames()method 
public function getTextureNames(prefix:String, out:Vector.<String> = null):Vector.<String>

Returns all texture names that start with a certain string, sorted alphabetically.

Parameters

prefix:String
 
out:Vector.<String> (default = null)

Returns
Vector.<String>
getTextures()method 
public function getTextures(prefix:String, out:Vector.<Texture> = null):Vector.<Texture>

Returns all textures that start with a certain string, sorted alphabetically (especially useful for "MovieClip").

Parameters

prefix:String
 
out:Vector.<Texture> (default = null)

Returns
Vector.<Texture>
getXml()method 
public function getXml(name:String):XML

Returns an XML with a certain name, or null if it's not found.

Parameters

name:String

Returns
XML
getXmlNames()method 
public function getXmlNames(prefix:String, out:Vector.<String> = null):Vector.<String>

Returns all XML names that start with a certain string, sorted alphabetically. If you pass an out-vector, the names will be added to that vector.

Parameters

prefix:String
 
out:Vector.<String> (default = null)

Returns
Vector.<String>
loadQueue()method 
public function loadQueue(onProgress:Function):void

Loads all enqueued assets asynchronously. The 'onProgress' function will be called with a 'ratio' between '0.0' and '1.0', with '1.0' meaning that it's complete.

When you call this method, the manager will save a reference to "Starling.current"; all textures that are loaded will be accessible only from within this instance. Thus, if you are working with more than one Starling instance, be sure to call "makeCurrent()" on the appropriate instance before processing the queue.

Parameters

onProgress:Function — function(ratio:Number):void;

loadRawAsset()method 
protected function loadRawAsset(rawAsset:Object, onProgress:Function, onComplete:Function):void

This method is called internally for each element of the queue when it is loaded. 'rawAsset' is typically either a class (pointing to an embedded asset) or a string (containing the path to a file). For texture data, it will also be called after a context loss.

The method has to transform this object into one of the types that the AssetManager can work with, e.g. a Bitmap, a Sound, XML data, or a ByteArray. This object needs to be passed to the 'onComplete' callback.

The calling method will then process this data accordingly (e.g. a Bitmap will be transformed into a texture). Unknown types will be available via 'getObject()'.

When overriding this method, you can call 'onProgress' with a number between 0 and 1 to update the total queue loading progress.

Parameters

rawAsset:Object
 
onProgress:Function
 
onComplete:Function

log()method 
protected function log(message:String):void

This method is called during loading of assets when 'verbose' is activated. Per default, it traces 'message' to the console.

Parameters

message:String

playSound()method 
public function playSound(name:String, startTime:Number = 0, loops:int = 0, transform:SoundTransform = null):SoundChannel

Generates a new SoundChannel object to play back the sound. This method returns a SoundChannel object, which you can access to stop the sound and to control volume.

Parameters

name:String
 
startTime:Number (default = 0)
 
loops:int (default = 0)
 
transform:SoundTransform (default = null)

Returns
SoundChannel
purge()method 
public function purge():void

Removes assets of all types (disposing them along the way), empties the queue and aborts any pending load operations.

purgeQueue()method 
public function purgeQueue():void

Empties the queue and aborts any pending load operations.

removeByteArray()method 
public function removeByteArray(name:String, dispose:Boolean = true):void

Removes a certain byte array, optionally disposing its memory right away.

Parameters

name:String
 
dispose:Boolean (default = true)

removeObject()method 
public function removeObject(name:String):void

Removes a certain object.

Parameters

name:String

removeSound()method 
public function removeSound(name:String):void

Removes a certain sound.

Parameters

name:String

removeTexture()method 
public function removeTexture(name:String, dispose:Boolean = true):void

Removes a certain texture, optionally disposing it.

Parameters

name:String
 
dispose:Boolean (default = true)

removeTextureAtlas()method 
public function removeTextureAtlas(name:String, dispose:Boolean = true):void

Removes a certain texture atlas, optionally disposing it.

Parameters

name:String
 
dispose:Boolean (default = true)

removeXml()method 
public function removeXml(name:String, dispose:Boolean = true):void

Removes a certain Xml object, optionally disposing it.

Parameters

name:String
 
dispose:Boolean (default = true)

transformData()method 
protected function transformData(data:ByteArray, url:String):ByteArray

This method is called when raw byte data has been loaded from an URL or a file. Override it to process the downloaded data in some way (e.g. decompression) or to cache it on disk.

It's okay to call one (or more) of the 'add...' methods from here. If the binary data contains multiple objects, this allows you to process all of them at once. Return 'null' to abort processing of the current item.

Parameters

data:ByteArray
 
url:String

Returns
ByteArray
Event Detail
ioError Event
Event Object Type: starling.events.Event

Dispatched when an URLLoader fails with an IO_ERROR while processing the queue. The 'data' property of the Event contains the URL-String that could not be loaded.

parseError Event  
Event Object Type: starling.events.Event

Dispatched when an XML or JSON file couldn't be parsed. The 'data' property of the Event contains the name of the asset that could not be parsed.

securityError Event  
Event Object Type: starling.events.Event

Dispatched when an URLLoader fails with a SECURITY_ERROR while processing the queue. The 'data' property of the Event contains the URL-String that could not be loaded.

texturesRestored Event  
Event Object Type: starling.events.Event

Dispatched when all textures have been restored after a context loss.





Mon Apr 18 2016, 08:17 PM +02:00