| Package | starling.assets |
| Class | public class AssetManager |
| Inheritance | AssetManager  EventDispatcher 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 LossWhen 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 HandlingLoading 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 PropertiesWhen 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(...);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");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
| Property | Defined 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 | ||
| Method | Defined 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 | ||
 | 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 | ||
| dispatchEvent(event:Event):void Dispatches an event to all objects that have registered listeners for its type. | EventDispatcher | |
| 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 | ||
getAssetManager(name:String):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 | ||
getBitmapFont(name:String):BitmapFont 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 | ||
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 | ||
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 | ||
| 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 | ||
| removeEventListener(type:String, listener:Function):void Removes an event listener from the object. | EventDispatcher | |
| 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 | ||
unregisterFactory(factory:AssetFactory):void Unregisters the specified AssetFactory. | AssetManager | ||
| Method | Defined 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 | ||
| Event | Summary | Defined By | ||
|---|---|---|---|---|
| Dispatched when all textures have been restored after a context loss. | AssetManager | |||
| dataLoader | property |
Hide Inherited Public Methods
Show Inherited Public MethodsdataLoader:DataLoaderThe 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.
public function get dataLoader():DataLoader public function set dataLoader(value:DataLoader):void| numConnections | property |
numConnections:intThe 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..
public function get numConnections():int public function set numConnections(value:int):void| numQueuedAssets | property |
numQueuedAssets:int [read-only] Returns the number of raw assets that have been enqueued, but not yet loaded.
public function get numQueuedAssets():int| registerBitmapFontsWithFontFace | property |
registerBitmapFontsWithFontFace:BooleanIndicates 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.
public function get registerBitmapFontsWithFontFace():Boolean public function set registerBitmapFontsWithFontFace(value:Boolean):void| textureOptions | property |
textureOptions:TextureOptionsTextures will be created with the options set up in this object at the time of enqueuing.
public function get textureOptions():TextureOptions public function set textureOptions(value:TextureOptions):void| verbose | property |
verbose:BooleanWhen activated, the class will trace information about added/enqueued assets.
The default value is true.
public function get verbose():Boolean public function set verbose(value:Boolean):void| AssetManager | () | Constructor |
public function AssetManager(scaleFactor:Number = 1)Create a new instance with the given scale factor.
ParametersscaleFactor:Number (default = 1) |
| addAsset | () | method |
public function addAsset(name:String, asset:Object, type:String = null):voidAdd 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) |
| dequeue | () | method |
public function dequeue(... assetNames):voidRemoves 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():voidDisposes 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):voidDisposes 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):voidEnqueues one or more raw assets; they will only be available after successfully executing the "loadQueue" method. This method accepts a variety of different objects:
png, jpg, gif, atf, mp3, xml, fnt, json, binary.static embedded assets.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):StringEnqueues 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) | |
options:TextureOptions (default = null) |
String — the name with which the asset was registered.
|
| getAsset | () | method |
public function getAsset(type:String, name:String, recursive:Boolean = true):ObjectRetrieves 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) |
Object |
| getAssetManager | () | method |
public function getAssetManager(name:String):AssetManagerReturns an asset manager with a certain name, or null if it's not found.
Parameters
name:String |
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) |
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) |
Vector.<String> |
| getBitmapFont | () | method |
public function getBitmapFont(name:String):BitmapFontReturns a bitmap font with a certain name, or null if it's not found.
Parameters
name:String |
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) |
Vector.<String> |
| getByteArray | () | method |
public function getByteArray(name:String):ByteArrayReturns a byte array with a certain name, or null if it's not found.
Parameters
name:String |
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) |
Vector.<String> |
| getExtensionFromUrl | () | method |
protected function getExtensionFromUrl(url:String):StringThis 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 |
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):StringThis 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 |
String — the name to be used for the asset, or 'null' if it can't be determined. |
| getObject | () | method |
public function getObject(name:String):ObjectReturns 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 |
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) |
Vector.<String> |
| getSound | () | method |
public function getSound(name:String):SoundReturns a sound with a certain name, or null if it's not found.
Parameters
name:String |
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) |
Vector.<String> |
| getTexture | () | method |
public function getTexture(name:String):TextureReturns a texture with a certain name. Includes textures stored inside atlases.
Parameters
name:String |
Texture |
| getTextureAtlas | () | method |
public function getTextureAtlas(name:String):TextureAtlasReturns a texture atlas with a certain name, or null if it's not found.
Parameters
name:String |
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) |
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) |
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) |
Vector.<Texture> |
| getXml | () | method |
public function getXml(name:String):XMLReturns an XML with a certain name, or null if it's not found.
Parameters
name:String |
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) |
Vector.<String> |
| loadQueue | () | method |
public function loadQueue(onComplete:Function, onError:Function = null, onProgress:Function = null):voidLoads 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:Function — function(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):voidThis 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):SoundChannelGenerates 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) |
SoundChannel |
| purge | () | method |
public function purge():voidRemoves assets of all types (disposing them along the way), empties the queue and aborts any pending load operations.
| purgeQueue | () | method |
public function purgeQueue():voidEmpties the queue and aborts any pending load operations.
| registerFactory | () | method |
public function registerFactory(factory:AssetFactory, priority:int = 0):voidRegisters 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):voidRemoves 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):voidRemoves 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):voidRemoves a certain bitmap font, optionally disposing it.
Parameters
name:String | |
dispose:Boolean (default = true) |
| removeByteArray | () | method |
public function removeByteArray(name:String, dispose:Boolean = true):voidRemoves a certain byte array, optionally disposing its memory right away.
Parameters
name:String | |
dispose:Boolean (default = true) |
| removeObject | () | method |
public function removeObject(name:String):voidRemoves a certain object.
Parameters
name:String |
| removeSound | () | method |
public function removeSound(name:String):voidRemoves a certain sound.
Parameters
name:String |
| removeTexture | () | method |
public function removeTexture(name:String, dispose:Boolean = true):voidRemoves a certain texture, optionally disposing it.
Parameters
name:String | |
dispose:Boolean (default = true) |
| removeTextureAtlas | () | method |
public function removeTextureAtlas(name:String, dispose:Boolean = true):voidRemoves a certain texture atlas, optionally disposing it.
Parameters
name:String | |
dispose:Boolean (default = true) |
| removeXml | () | method |
public function removeXml(name:String, dispose:Boolean = true):voidRemoves a certain Xml object, optionally disposing it.
Parameters
name:String | |
dispose:Boolean (default = true) |
| unregisterFactory | () | method |
public function unregisterFactory(factory:AssetFactory):voidUnregisters the specified AssetFactory.
Parameters
factory:AssetFactory |
| texturesRestored | Event |
starling.events.EventDispatched when all textures have been restored after a context loss.