cc.plugin.loader.Loader

cc.plugin.loader.Loader

The loader object is an asynchronous resource loader utility. Unlike in V3, the developer can build as much loader objects as needed. The Loader works based on resource file extension. Based on the file extension, a ResourceLoader suitable to understand what the file is, is created and delegated the responsibility of loading and interpreting resources. When the resource is loaded, of fails at loading, notifies the Loader object accordingly.

The following extensions are recognized out-of-the-box:

• ResourceLoaderAudioBuffer: mp3, ogg, wav
• ResourceLoaderImage: jpg, jpeg, png
• ResourceLoaderJSON: txt, json, fnt
• ResourceLoaderXML: xml, plist

New extension for new ResourceLoader types can be registered.

Registering new extensions for a ResourceLoader:

It is straightforward to associate an extension file with a ResourceLoader object type:

// register a ResourceLoaderXML for files with extension plist.
cc.plugin.loader.registerLoaderForType(
    "plist",
    { 
        type: "MAC Plist file", 
        loader: function(url:string) { 
            return new ResourceLoaderXML(url); 
        } 
    });

New ResourceLoader types

Since a ResourceLoader object is created for each resource type, extending the loaders ecosystem may seem interesting. To do so, an object with a method with the following signature must be created:

constructor( url {string} );
load( loaded {cc.plugin.loader.ResourceLoaderResourceOkCallback}, 
      error  {cc.plugin.loader.ResourceLoaderResourceErrorCallback} );

The Loader takes care of the choreography between loaders, resource loaders and callbacks.

Loader initialization

The Loader object is created as follows:

var loader= new cc.plugin.loader.Loader( initializer );

The initializer is an object of type:

{
    /**
     * Optional common prefix to add to every resource uri before loading.
     * @member cc.plugin.loader.LoaderInitializer#prefix
     * @type {string=}
     */
    prefix : {string=};

    /**
     * Optional resource list.
     * @member cc.plugin.loader.LoaderInitializer#resources
     * @type {Array<string>=}
     */
     resources : {string[]=};
}   

so a common Loader call could be:

var loader= new cc.plugin.loader.Load( {
    prefix : "../res/",
    resources: [
        "map.png@map",
        "map.json@map-atlas",
        "grossini_family.png@grossini",
        "grossini_family.plist@g-atlas",
        "font.txt@font.txt",
        "arial-14.png@arial",
        "arial-14.fnt@arialfnt"
    ]
} );

Resource URL format

The Loader needs an array of url resources to load and manage. When the Loader ends doing its job, it returns a map of the form map<string,object>.

The string, is the resource id, by default, the whole url where the resource was loaded from. If there's 'prefix' set for the loader, the prefix will be part of the if too. The id can be forced to be something different. to do so, you can name resources like: url@id.

The object, is what comes from the ResourceLoader object, image, text, json, etc.

Callbacks

Creating the Loader is the first step, and then a call like the following must be done:

startLoading( 
    onEnd      {cc.plugin.loader.LoaderFinishedCallback}, 
    onProgress {cc.plugin.loader.LoaderProgressCallback=}, 
    onError    {cc.plugin.loader.LoaderErrorCallback} ) 

it is only mandatory to set the onEnd callback.

• onEnd

This callback receives a map object which binds the Resource id, with an object of any type, either an Image, JSON, AudioBuffer, etc. The signature of the callback is:

function( resources {Array<{ id {string}, value {object} >} )

• onProgress

Invoked for each Resource, either loaded correctly or failed. Unlike onEnd, this callback will receive a cc.plugin.loader.Resource object which contains information of the url, type, status, etc.

function( 
    resource {cc.plugin.loader.Resource}, 
    index {number}, 
    size {number}, 
    errored {boolean}
)

The progress callback will be invoked even for errored resources.

• onError

This callback will be invoked when an error occurs loading a Resource. onProgress callback will be called first. Like onProgress, a cc.plugin.loader.Resource is received. The callback signature is:

function( resource {cc.plugin.loader.Resource} )