Packagestarling.assets
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, 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 time frame 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 call the 'onError' callback that you can optional provide to the 'loadQueue' method. Queue processing will continue after an error, so it's always guaranteed that the 'onComplete' callback is executed, too.

Texture Properties

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.textureOptions.format = Context3DTextureFormat.BGRA;
      assets.enqueue(appDir.resolvePath("textures/32bit"));
      
      assets.textureOptions.format = Context3DTextureFormat.BGRA_PACKED;
      assets.enqueue(appDir.resolvePath("textures/16bit"));
      
      assets.loadQueue(...);
Nesting

When you enqueue one or more AssetManagers to another one, the "loadQueue" method will load the assets of the "child" AssetManager, as well. Later, when accessing assets, the "parent" AssetManager will return the "child" assets as well - just like it returns, say, the SubTextures from a contained TextureAtlas.

The main advantage of grouping your assets like this is something else, though: it allows to remove (and dispose) a complete group of assets in one step. The example below loads the assets from two directories. When the contents of one of them are no longer needed, all its assets are removed together.

      var manager:AssetManager = new AssetManager();
      var appDir:File = File.applicationDirectory;
      
      var redAssets:AssetManager = new AssetManager();
      redAssets.enqueueSingle(appDir.resolvePath("textures/red/"));
      
      var greenAssets:AssetManager = new AssetManager();
      greenAssets.enqueueSingle(appDir.resolvePath("textures/green/"));
      
      manager.enqueueSingle(redAssets, "redAssets");
      manager.enqueueSingle(greenAssets, "greenAssets");
      manager.loadQueue(...); // loads both "red" and "green" assets
      
      // ... later, remove all "red" assets together
      manager.removeAssetManager("redAssets");
Customization

You can customize how assets are created by extending the 'AssetFactory' class and registering an instance of your new class at the AssetManager via 'registerFactory'. Factories are probed by priority; any factory with a priority > 0 will be executed before the built-in factories.

An asset type is identified by a unique String. You can add your own asset types by creating a custom 'AssetFactory' and having it add the asset with custom string identifier.

By overriding the methods 'getNameFromUrl', 'getExtensionFromUrl', 'disposeAsset', and 'log', you can customize how assets are named and disposed, and you can forward any logging to an external logger. To customize the way data is loaded from URLs or files, you can assign a custom 'DataLoader' instance to the AssetManager.

See also

starling.assets.AssetFactory
starling.assets.AssetType
starling.assets.DataLoader


Public Properties
 PropertyDefined By
  dataLoader : DataLoader
The DataLoader is used to load any data from files or URLs.
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
  registerBitmapFontsWithFontFace : Boolean
Indicates if bitmap fonts should be registered with their "face" attribute from the font XML file.
AssetManager
  textureOptions : TextureOptions
Textures will be created with the options set up in this object at the time of enqueuing.
AssetManager
  verbose : Boolean
When activated, the class will trace information about added/enqueued assets.
AssetManager
Public Methods
 MethodDefined By
  
AssetManager(scaleFactor:Number = 1)
Create a new instance with the given scale factor.
AssetManager
  
addAsset(name:String, asset:Object, type:String = null):void
Add an asset with a certain name and type.
AssetManager
 Inherited
addEventListener(type:String, listener:Function):void
Registers an event listener at a certain object.
EventDispatcher
  
dequeue(... assetNames):void
Removes the asset(s) with the given name(s) from the queue.
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 assets and purges the queue.
AssetManager
  
enqueue(... assets):void
Enqueues one or more raw assets; they will only be available after successfully executing the "loadQueue" method.
AssetManager
  
enqueueSingle(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
  
getAsset(type:String, name:String, recursive:Boolean = true):Object
Retrieves an asset of the given type, with the given name.
AssetManager
  
Returns an asset manager with a certain name, or null if it's not found.
AssetManager
  
getAssetManagerNames(prefix:String, out:Vector.<String> = null):Vector.<String>
Returns all asset manager names that start with a certain string, sorted alphabetically.
AssetManager
  
getAssetNames(assetType:String, prefix:String, recursive:Boolean = true, out:Vector.<String> = null):Vector.<String>
Retrieves an alphabetically sorted list of all assets that have the given type and start with the given prefix.
AssetManager
  
Returns a bitmap font with a certain name, or null if it's not found.
AssetManager
  
getBitmapFontNames(prefix:String, out:Vector.<String> = null):Vector.<String>
Returns all bitmap font names that start with a certain string, sorted alphabetically.
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
  
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(onComplete:Function, onError:Function = null, onProgress:Function = null):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
  
registerFactory(factory:AssetFactory, priority:int = 0):void
Registers a custom AssetFactory.
AssetManager
  
removeAsset(assetType:String, name:String, dispose:Boolean = true):void
Removes the asset with the given name and type, and will optionally dispose it.
AssetManager
  
removeAssetManager(name:String, dispose:Boolean = true):void
Removes a certain asset manager and optionally disposes it right away.
AssetManager
  
removeBitmapFont(name:String, dispose:Boolean = true):void
Removes a certain bitmap font, optionally disposing it.
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
  
Unregisters the specified AssetFactory.
AssetManager
Protected Methods
 MethodDefined By
  
disposeAsset(asset:Object):void
Disposes the given asset.
AssetManager
  
getExtensionFromUrl(url:String):String
This method is called internally to determine the extension that's passed to the 'AssetFactory' (via the 'AssetReference').
AssetManager
  
getNameFromUrl(url:String):String
This method is called internally to determine the name under which an asset will be accessible; override it if you need a custom naming scheme.
AssetManager
  
log(message:String):void
This method is called during loading of assets when 'verbose' is activated.
AssetManager
Events
 Event Summary Defined By
  Dispatched when all textures have been restored after a context loss.AssetManager
Property Detail
dataLoaderproperty
dataLoader:DataLoader

The DataLoader is used to load any data from files or URLs. If you need to customize its behavior (e.g. to add a caching mechanism), assign your custom instance here.


Implementation
    public function get dataLoader():DataLoader
    public function set dataLoader(value:DataLoader):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
registerBitmapFontsWithFontFaceproperty 
registerBitmapFontsWithFontFace:Boolean

Indicates if bitmap fonts should be registered with their "face" attribute from the font XML file. Per default, they are registered with the name of the texture file.

The default value is false.


Implementation
    public function get registerBitmapFontsWithFontFace():Boolean
    public function set registerBitmapFontsWithFontFace(value:Boolean):void
textureOptionsproperty 
textureOptions:TextureOptions

Textures will be created with the options set up in this object at the time of enqueuing.


Implementation
    public function get textureOptions():TextureOptions
    public function set textureOptions(value:TextureOptions):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)

Create a new instance with the given scale factor.

Parameters
scaleFactor:Number (default = 1)
Method Detail
addAsset()method
public function addAsset(name:String, asset:Object, type:String = null):void

Add an asset with a certain name and type.

Beware: if the slot (name + type) was already taken, the existing object will be disposed and replaced by the new one.

Parameters

name:String — The name with which the asset can be retrieved later. Must be unique within this asset type.
 
asset:Object — The actual asset to add (e.g. a texture, a sound, etc).
 
type:String (default = null) — The type of the asset. If omitted, the type will be determined automatically (which works for all standard types defined within the 'AssetType' class).

dequeue()method 
public function dequeue(... assetNames):void

Removes the asset(s) with the given name(s) from the queue. Note that this won't work after loading has started, even if these specific assets have not yet been processed.

Parameters

... assetNames

dispose()method 
public function dispose():void

Disposes all assets and purges the queue.

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.

disposeAsset()method 
protected function disposeAsset(asset:Object):void

Disposes the given asset. ByteArrays are cleared, XMLs are disposed using 'System.disposeXML'. If the object contains a 'dispose' method, it will be called. Override if you need to add custom cleanup code for a certain asset.

Parameters

asset:Object

enqueue()method 
public function enqueue(... assets):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 are made available via "getXml()"; this includes XMLs containing texture atlases or bitmap fonts, which are processed along the way. Bitmap fonts are also registered at the TextField class.

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

Parameters

... assets

enqueueSingle()method 
public function enqueueSingle(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.
getAsset()method 
public function getAsset(type:String, name:String, recursive:Boolean = true):Object

Retrieves an asset of the given type, with the given name. If 'recursive' is true, the method will traverse included texture atlases and asset managers.

Typically, you will use one of the type-safe convenience methods instead, like 'getTexture', 'getSound', etc.

Parameters

type:String
 
name:String
 
recursive:Boolean (default = true)

Returns
Object
getAssetManager()method 
public function getAssetManager(name:String):AssetManager

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

Parameters

name:String

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

Returns all asset manager 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>
getAssetNames()method 
public function getAssetNames(assetType:String, prefix:String, recursive:Boolean = true, out:Vector.<String> = null):Vector.<String>

Retrieves an alphabetically sorted list of all assets that have the given type and start with the given prefix. If 'recursive' is true, the method will traverse included texture atlases and asset managers.

Parameters

assetType:String
 
prefix:String
 
recursive:Boolean (default = true)
 
out:Vector.<String> (default = null)

Returns
Vector.<String>
getBitmapFont()method 
public function getBitmapFont(name:String):BitmapFont

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

Parameters

name:String

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

Returns all bitmap font 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>
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

This method is called internally to determine the extension that's passed to the 'AssetFactory' (via the 'AssetReference'). Override it if you need to customize e.g. the extension of a server URL.

Parameters

url:String

Returns
String — the extension to be used for the asset, or an empty string if it can't be determined.
getNameFromUrl()method 
protected function getNameFromUrl(url:String):String

This method is called internally to determine the name under which an asset will be accessible; override it if you need a custom naming scheme.

Parameters

url:String

Returns
String — the name to be used for the asset, or 'null' if it can't be determined.
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. Includes textures stored inside 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. Includes textures stored inside atlases.

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"). Includes textures stored inside atlases.

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(onComplete:Function, onError:Function = null, onProgress:Function = null):void

Loads all enqueued assets asynchronously. The 'onComplete' callback will be executed once all assets have been loaded - even when there have been errors, which are forwarded to the optional 'onError' callback. The 'onProgress' function will be called with a 'ratio' between '0.0' and '1.0' and is also optional. Furthermore, all parameters of all the callbacks are optional.

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

onComplete:Functionfunction(manager:AssetManager):void;
 
onError:Function (default = null)function(error:String, asset:AssetReference):void;
 
onProgress:Function (default = null)function(ratio:Number):void;

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.

registerFactory()method 
public function registerFactory(factory:AssetFactory, priority:int = 0):void

Registers a custom AssetFactory. If you use any priority > 0, the factory will be called before the default factories. The final factory to be invoked is the 'ByteArrayFactory', which is using a priority of '-100'.

Parameters

factory:AssetFactory
 
priority:int (default = 0)

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

Removes the asset with the given name and type, and will optionally dispose it.

Parameters

assetType:String
 
name:String
 
dispose:Boolean (default = true)

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

Removes a certain asset manager and optionally disposes it right away.

Parameters

name:String
 
dispose:Boolean (default = true)

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

Removes a certain bitmap font, optionally disposing it.

Parameters

name:String
 
dispose:Boolean (default = true)

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)

unregisterFactory()method 
public function unregisterFactory(factory:AssetFactory):void

Unregisters the specified AssetFactory.

Parameters

factory:AssetFactory

Event Detail
texturesRestored Event
Event Object Type: starling.events.Event

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