Developers Manual > Cocos2d-JS > Features Of Cocos2d-JS > Loading Resources with ccloader

Loading Resources with cc.loader

version: cocos2d-js v3.x
update: Updated about 2 years ago

Summary

The old cc.Loader has been refactored as cc.loader with plugin mode.

All kinds of loader plugins of resources are registered in each module. Quite different from which in version 2.x.

In this way we can manage resources better and developers can customize their own resource loader plugins.

cc.loader has some APIs for base operations of resources like loadJs, loadImg and so on.

API description

(full-path means base-path + res-path followed.)

resPath

Base path of resources (Exclude audio).

We set cc.loader.resPath = "res", then the full-path of a.png will be res/a.png.

audioPath

Base path of audio.

getXMLHttpRequest

The way to get XMLHttpRequest.

loadJs

The way to load JavaScript.

1
2
3
4
5
Arguments:
url     full-path of resource
cb      callback

return  none
  • Usage1:
1
2
3
4
5
6
cc.loader.loadJs("src", [
    "a.js", "b.js"
], function(err){
    if(err) return console.log("load failed");
    //success
});
  • Usage2:
1
2
3
4
5
6
cc.loader.loadJs([
    "src/a.js", "src/b.js"
], function(err){
    if(err) return console.log("load failed");
    //success
});
  • Usage3:
1
2
3
4
cc.loader.loadJs("src/a.js", function(err){
    if(err) return console.log("load failed");
    //success
});
loadJsWithImg

Load JavaScript with a loading image.

loadTxt

The way th load text.

1
2
3
4
5
Arguments:
url     full-path of resource
cb      callback

return  none

Usage:

1
2
3
4
cc.loader.loadTxt("res/a.txt", function(err, data){
    if(err) return console.log("load failed");
    //success
});
loadImg

The way to load image.

1
2
3
4
5
6
Arguments:
url     full-path of resource
option  Optional. The structure is `{isCrossOrigin : true}`. `isCrossOrigin` default to be `true`(optional).
cb      callback

return  An instance of Image.
loadBinary

The way to load binary file asynchronously.

1
2
3
4
5
Arguments:
url     full-path of resource
cb      callback

return  Data of binary.
loadBinarySync

The way to load binary file synchronously (not recommended).

1
2
3
4
5
Arguments:
url     full-path of resource
cb      callback

return  Data of binary.
getUrl

The way to get the full-path of resource.

1
2
3
4
5
Arguments:
basePath    basePath of resource
url         path of resource

return      full-path

Usage:

1
2
cc.loader.getUrl("res", "a.png");//-->"res/a.png"
cc.loader.getUrl("a.png");//(set cc.loader.resPath = "res")--->"res/a.png"。
load

Replace the old cc.Loader.preload.

1
2
3
4
5
6
7
8
Arguments:
res         Resources list. It can be a string or an array.
option      Optional. Keys like:
            cb              callback
            cbTarget        the target of callback
            trigger         trigger
            triggerTarget   the target of trigger
cb          callback (Optional)

Usage:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
var res = ["res/a.png", "res/a.plist", "audio/b.mp3"];
var testTarget = {
    name : "the name is testTarget",
    trigger : function(){...},
    cb : function(err){...}
};
var option = {
    trigger : testTarget.trigger,
    triggerTarget : testTarget,
    cbTarget : testTarget
}
//Usage1
cc.loader.load(res, option, function(err){
    if(err) return console.log("load failed");
    console.log(this.name);//the name is testTarget
});

//Usage2
cc.loader.load(res, function(err){
    if(err) return console.log("load failed");
});

//Usage3
option.cb = testTarget.cb;
cc.loader.load(res, option);

//Usage4
cc.loader.load(res);

loadAliases

Load a plist config file to get aliases.

Arguments:
url             The url of config file.
                The content of the config file like:
                    
                    
                    
                    
                        metadata
                        
                            version
                            1
                        
                        filenames
                        
                            grossini.bmp
                            res/Images/grossini.png
                        
                    
                    

cb              callback

Usage:

cc.loader.loadAliases("res/lookup-html5.plist", function(){
    var sprite = cc.Sprite.create("grossini.bmp");
    self.addChild( sprite );
    sprite.x = winSize.width/2;
    sprite.y = winSize.height/2;
});

register

The way to register a resource loader plugin.

1
2
3
4
5
6
7
8
9
Arguments:
extNames        A string or an string array which means the extname of resources.
loader          The loader plugin object which must has a function named "load".
                `realUrl`, `url`, `res`, `cb` will be pass into the `load` function as arguments.
                If there is a function named `getBasePath` in this loader plugin,
                then the base path of this kind of resource will be the value returned by the `getBasePath` function.
                Default to be `cc.loader.resPath`.

return          none

Usage:

1
2
3
4
5
6
cc.txtLoader = {
    load : function(realUrl, url, res, cb){
        cc.loader.loadTxt(realUrl, cb);
    }
}
cc.loader.register(["txt", "xml", "tmx", "tsx"], cc.txtLoader);
getRes

The way to get resource cached.

1
2
3
4
Arguments:
url         path of resource (not a full-path)

return      data of resource

Usage:

1
var img = cc.loader.getRes("a.png");
release

Release the data of resource cached.

1
2
3
4
Arguments:
url         path of resource (not a full-path)

return      none

Usage:

1
cc.loader.release("a.png");
releaseAlll

Release all data of resources cached.

1
2
3
Arguments:      none

return          none

Usage:

1
cc.loader.releaseAll();

Register a resource loader plugin

See the codes in CCLoaders.js then you will understand it.

The structure to config resources

version 2.x:

var resources = [
    {src:"res/a.png"},
    {fontName:"Marker Felt",src:[{src:"res/cocosgui/Marker Felt.ttf",type:"truetype"}]},
    {
        fontName:"Schwarzwald Regular",
        src:[
            {src:"res/fonts/Schwarzwald_Regular.eot", type:"embedded-opentype"},
            {src:"res/fonts/Schwarzwald Regular.ttf",type:"truetype"}
        ]
    }
]

version 3.x:

var resources = [
    "res/a.png",
    "res/cocosgui/Marker Felt.ttf",
    {
        type:"font",
        name:"Schwarzwald Regular",
        srcs:["res/fonts/Schwarzwald_Regular.eot", "res/fonts/Schwarzwald Regular.ttf"]
    }
]

In version 3.x, you just need to config a resource as a string, not an object.

In some special condition, you can use type to state which loader plugin to handle this resource.
And use name + . + type to be the key to cache the resource.

The structure in version 2.x is not supported in version 3.x.

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.