Options
All
  • Public
  • Public/Protected
  • All
Menu

Class AssetManager

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:

  • Texture, either from Bitmaps or ATF data
  • Texture atlases
  • Bitmap Fonts
  • Sounds
  • XML data
  • JSON data
  • ByteArrays
  • other AssetManagers

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:

appDir:File = File.applicationDirectory; 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 oad 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.

manager:AssetManager = new AssetManager(); appDir:File = File.applicationDirectory; redAssets:AssetManager = new AssetManager(); manager.enqueueSingle(appDir.resolvePath("textures/red/", "redAssets"); greenAssets:AssetManager = new AssetManager(); manager.enqueueSingle(appDir.resolvePath("textures/green/", "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 starling.assets.AssetFactory @see starling.assets.AssetType @see starling.assets.DataLoader

Hierarchy

Index

Constructors

constructor

Properties

dataLoader

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.

numConnections

numConnections: number

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

numQueuedAssets

numQueuedAssets: number

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

registerBitmapFontsWithFontFace

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. @default false

textureOptions

textureOptions: TextureOptions

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

verbose

verbose: boolean

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

Methods

addAsset

  • addAsset(name: string, asset: any, type?: string): 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.

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

    Parameters

    • name: string
    • asset: any
    • Optional type: string

    Returns void

addEventListener

  • addEventListener(type: string, listener: Function): void

dispatchEvent

  • dispatchEvent(event: Event): void
  • Dispatches an event to all objects that have registered listeners for its type. If an event with enabled 'bubble' property is dispatched to a display object, it will travel up along the line of parents, until it either hits the root object or someone stops its propagation manually.

    Parameters

    Returns void

dispatchEventWith

  • dispatchEventWith(type: string, bubbles?: boolean, data?: any): void

dispose

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

    Returns void

enqueue

  • enqueue(assets: Array<any>): 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 or URLRequests containing an URL to a local or remote resource. Supported types: png, jpg, gif, atf, mp3, xml, fnt, json, binary.
    • 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.
    • If the file extension is not recognized, the data is analyzed to see if contains XML or JSON data. If it's neither, it is stored as ByteArray.

    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: Array<any>

    Returns void

enqueueSingle

  • enqueueSingle(asset: any, name?: string, options?: TextureOptions): 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.

    @param asset The asset that will be enqueued; accepts the same objects as the 'enqueue' method. @param name 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. @param options Custom options that will be used if 'asset' points to texture data. @return the name with which the asset was registered.

    Parameters

    Returns string

getAsset

  • getAsset(type: string, name: string, recursive?: boolean): any
  • 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
    • Optional recursive: boolean

    Returns any

getAssetManager

getAssetManagerNames

  • getAssetManagerNames(prefix?: string, out?: Vector<string>): 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

    • Optional prefix: string
    • Optional out: Vector<string>

    Returns Vector<string>

getAssetNames

  • getAssetNames(assetType: string, prefix?: string, recursive?: boolean, out?: Vector<string>): 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
    • Optional prefix: string
    • Optional recursive: boolean
    • Optional out: Vector<string>

    Returns Vector<string>

getBitmapFont

getBitmapFontNames

  • getBitmapFontNames(prefix?: string, out?: Vector<string>): 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

    • Optional prefix: string
    • Optional out: Vector<string>

    Returns Vector<string>

getByteArray

  • getByteArray(name: string): ByteArray

getByteArrayNames

  • getByteArrayNames(prefix?: string, out?: Vector<string>): 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

    • Optional prefix: string
    • Optional out: Vector<string>

    Returns Vector<string>

getObject

  • getObject(name: string): any
  • 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 any

getObjectNames

  • getObjectNames(prefix?: string, out?: Vector<string>): 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

    • Optional prefix: string
    • Optional out: Vector<string>

    Returns Vector<string>

getSound

  • getSound(name: string): Sound

getSoundNames

  • getSoundNames(prefix?: string, out?: Vector<string>): 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

    • Optional prefix: string
    • Optional out: Vector<string>

    Returns Vector<string>

getTexture

  • getTexture(name: string): Texture

getTextureAtlas

getTextureAtlasNames

  • getTextureAtlasNames(prefix?: string, out?: Vector<string>): 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

    • Optional prefix: string
    • Optional out: Vector<string>

    Returns Vector<string>

getTextureNames

  • getTextureNames(prefix?: string, out?: Vector<string>): Vector<string>
  • Returns all texture names that start with a certain string, sorted alphabetically. Includes textures stored inside atlases.

    Parameters

    • Optional prefix: string
    • Optional out: Vector<string>

    Returns Vector<string>

getTextures

  • getTextures(prefix?: string, out?: Vector<Texture>): Vector<Texture>
  • Returns all textures that start with a certain string, sorted alphabetically (especially useful for "MovieClip"). Includes textures stored inside atlases.

    Parameters

    • Optional prefix: string
    • Optional out: Vector<Texture>

    Returns Vector<Texture>

getXml

  • getXml(name: string): any

getXmlNames

  • getXmlNames(prefix?: string, out?: Vector<string>): 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

    • Optional prefix: string
    • Optional out: Vector<string>

    Returns Vector<string>

Protected get_dataLoader

Protected get_numConnections

  • get_numConnections(): number

Protected get_numQueuedAssets

  • get_numQueuedAssets(): number

Protected get_registerBitmapFontsWithFontFace

  • get_registerBitmapFontsWithFontFace(): boolean

Protected get_textureOptions

Protected get_verbose

  • get_verbose(): boolean

hasEventListener

  • hasEventListener(type: string, listener?: any): boolean

loadQueue

  • loadQueue(onComplete: function, onError?: function, onProgress?: function): 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' will be called with a 'ratio' between '0.0' and '1.0' and is also 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.

    @param onComplete function(manager:AssetManager):void; - parameter is optional! @param onError function(error:string):void; @param onProgress function(ratio:Number):void;

    Parameters

    • onComplete: function
        • (): void
        • Returns void

    • Optional onError: function
        • (string: any): void
        • Parameters

          • string: any

          Returns void

    • Optional onProgress: function
        • (number: any): void
        • Parameters

          • number: any

          Returns void

    Returns void

playSound

  • playSound(name: string, startTime?: number, loops?: number, transform?: SoundTransform): 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
    • Optional startTime: number
    • Optional loops: number
    • Optional transform: SoundTransform

    Returns SoundChannel

purge

  • purge(): void

purgeQueue

  • purgeQueue(): void

registerFactory

  • registerFactory(factory: AssetFactory, priority?: number): 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

    Returns void

removeAsset

  • removeAsset(assetType: string, name: string, dispose?: boolean): void
  • Removes the asset with the given name and type, and will optionally dispose it.

    Parameters

    • assetType: string
    • name: string
    • Optional dispose: boolean

    Returns void

removeAssetManager

  • removeAssetManager(name: string, dispose?: boolean): void

removeBitmapFont

  • removeBitmapFont(name: string, dispose?: boolean): void

removeByteArray

  • removeByteArray(name: string, dispose?: boolean): void

removeEventListener

  • removeEventListener(type: string, listener: Function): void

removeEventListeners

  • removeEventListeners(type?: string): void

removeObject

  • removeObject(name: string): void

removeSound

  • removeSound(name: string): void

removeTexture

  • removeTexture(name: string, dispose?: boolean): void

removeTextureAtlas

  • removeTextureAtlas(name: string, dispose?: boolean): void

removeXml

  • removeXml(name: string, dispose?: boolean): void

Protected set_dataLoader

Protected set_numConnections

  • set_numConnections(value: number): number

Protected set_registerBitmapFontsWithFontFace

  • set_registerBitmapFontsWithFontFace(value: boolean): boolean

Protected set_textureOptions

Protected set_verbose

  • set_verbose(value: boolean): boolean

Generated using TypeDoc