GODPAPER | All Packages | All Classes | Index | Frames No Frames |
AssetManager

Package | starling.utils
Class | public class AssetManager
Inheritance | AssetManager EventDispatcher 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:

- Textures, either from Bitmaps or ATF data
- Texture atlases
- Bitmap Fonts
- Sounds
- XML data
- JSON data
- ByteArrays

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.

Public Properties

| Property | Defined 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
|  | scaleFactor : Number Textures that are created from Bitmaps or ATF files will have the scale factor assigned here. | 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

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined 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
|  | 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
|  | 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 contained textures. | 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):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, result: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, result: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, result: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
|  | getTextureNames(prefix:String, result:Vector.<String> = null):Vector.<String> Returns all texture names that start with a certain string, sorted alphabetically. | AssetManager
|  | getTextures(prefix:String, result: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, result:Vector.<String> = null):Vector.<String> Returns all XML names that start with a certain string, sorted alphabetically. | AssetManager
|  | hasEventListener(type:String):Boolean Returns if there are listeners registered for a certain 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, 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
|  | 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

Protected Methods

| Method | Defined By
--- | --- | ---
|  | 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
|  | log(message:String):void This method is called during loading of assets when 'verbose' is activated. | AssetManager

Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | texturesRestored | Dispatched when all textures have been restored after a context loss. | AssetManager

Property Detail

checkPolicyFile | property

`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.

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

scaleFactor | property |

`scaleFactor:Number`

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

Implementation
`public function get scaleFactor():Number`
`public function set scaleFactor(value:Number):void`

useMipMaps | property |

`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.

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

verbose | property |

`verbose:Boolean`

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

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.

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.

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.

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.

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.

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.

Parameters

| `name:String`
| `xml:XML`

dispose | () | method |

`public function dispose():void`

Disposes all contained textures.

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:

- Strings containing an URL to a local or remote resource. Supported types: `png, jpg, gif, atf, mp3, xml, fnt, pex, json`.
- Instances of the File class (AIR only) pointing to a directory or a file. Directories will be scanned recursively for all supported types.
- Classes that contain `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 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):String`

Enqueues a single asset with a custom name that can be used to access it later. If you don't pass a name, it's attempted to generate it automatically.

Parameters

| `asset:Object`
| `name:String` (default = `null`)``

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, result:Vector.<String> = null):Vector.<String>`

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

Parameters

| `prefix:String`
| `result:Vector.<String>` (default = `null`)``

Returns

| `Vector.<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. Typically, 'rawAsset' is either a String or a FileReference. Note that this method won't be called for embedded assets.

Parameters

| `rawAsset:Object`

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, result:Vector.<String> = null):Vector.<String>`

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

Parameters

| `prefix:String`
| `result: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, result:Vector.<String> = null):Vector.<String>`

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

Parameters

| `prefix:String`
| `result: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`

getTextureNames | () | method |

`public function getTextureNames(prefix:String, result:Vector.<String> = null):Vector.<String>`

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

Parameters

| `prefix:String`
| `result:Vector.<String>` (default = `null`)``

Returns

| `Vector.<String>`

getTextures | () | method |

`public function getTextures(prefix:String, result:Vector.<Texture> = null):Vector.<Texture>`

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

Parameters

| `prefix:String`
| `result: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, result:Vector.<String> = null):Vector.<String>`

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

Parameters

| `prefix:String`
| `result: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.

Parameters

| `onProgress:Function` — `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, 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`)``

Event Detail

texturesRestored | Event

Event Object Type: `starling.events.Event`

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

Thu Jan 16 2014, 01:11 PM +08:00