Cocos Creator API

1.0.0

Cocos Creator is a highly customizable game development tool that utilizes the power of cocos2d-x.

loader

Extends Pipeline
Module: cc

Loader for resource loading process. It's a singleton object.

Properties

downloader Object

The downloader in cc.loader's pipeline, it's by default the first pipe. It's used to download files with several handlers: pure text, image, script, audio, font, uuid. You can add your own download function with addDownloadHandlers

loader Object

The downloader in cc.loader's pipeline, it's by default the second pipe. It's used to parse downloaded content with several handlers: JSON, image, plist, fnt, uuid. You can add your own download function with addLoadHandlers

There are no properties that match your current filter settings. You can change your filter settings in the index section on this page. index

Methods

addDownloadHandlers
(
  • extMap
)

Add custom supported types handler or modify existing type handler for download process.

name type description
extMap Object

Custom supported types with corresponded handler

examples:

cc.loader.addDownloadHandlers({
     // This will match all url with .scene extension or all url with scene type
     'scene' : function (url, callback) {}
 });

addLoadHandlers
(
  • extMap
)

Add custom supported types handler or modify existing type handler for load process.

name type description
extMap Object

Custom supported types with corresponded handler

examples:

cc.loader.addLoadHandlers({
     // This will match all url with .scene extension or all url with scene type
     'scene' : function (url, callback) {}
 });

load
(
  • resources
  • [progressCallback ]
  • completeCallback
)

Load resources with a progression callback and a complete callback. The progression callback is the same as Pipeline's onProgress The complete callback is almost the same as Pipeline's onComplete The only difference is when user pass a single url as resources, the complete callback will set its result directly as the second parameter.

name type description
resources String | Array

Url list in an array

progressCallback optional Function

Callback invoked when progression change

completeCallback Function

Callback invoked when all resources loaded

examples:

cc.loader.load('a.png', function (err, tex) {
    cc.log('Result should be a texture: ' + (tex instanceof cc.Texture2D));
});

cc.loader.load('http://example.com/a.png', function (err, tex) {
    cc.log('Should load a texture from external url: ' + (tex instanceof cc.Texture2D));
});

cc.loader.load({id: 'http://example.com/getImageREST?file=a.png', type: 'png'}, function (err, tex) {
    cc.log('Should load a texture from RESTful API by specify the type: ' + (tex instanceof cc.Texture2D));
});

cc.loader.load(['a.png', 'b.json'], function (errors, results) {
    if (errors) {
        for (var i = 0; i < errors.length; i++) {
            cc.log('Error url [' + errors[i] + ']: ' + results.getError(errors[i]));
        }
    }
    var aTex = results.getContent('a.png');
    var bJsonObj = results.getContent('b.json');
});

loadRes
(
  • url
  • completeCallback
)

Load resources from the "resources" folder inside the "assets" folder of your project.

Note: All asset urls in Creator use forward slashes, urls using backslashes will not work.

name type description
url String

Url of the target resource. The url is relative to the "resources" folder, extensions must be omitted.

completeCallback Function

Callback invoked when the resource loaded.

  • error Error

    The error info or null if loaded successfully.

  • resource Object

    The loaded resource if it can be found otherwise returns null.

examples:

// load the sprite frame (project/assets/resources/imgs/cocos.png/cocos) from resources folder with no extension
cc.loader.loadRes('imgs/cocos/cocos', function (err, spriteFrame) {
    if (err) {
        cc.error(err.message || err);
        return;
    }
    cc.log('Result should be a sprite frame: ' + ( spriteFrame instanceof cc.SpriteFrame));
});

getRes
(
  • url
)

Get resource data by id.
When you load resources with load or loadRes, the url will be the unique identity of the resource. After loaded, you can acquire them by passing the url to this API.

name type description
url String

returns:

type:

release
(
  • url
)

Release the cache of resource by url.

name type description
url String

releaseAsset
(
  • asset
)

Release the loaded cache of asset.

name type description
asset Asset

releaseRes
(
  • url
)

Release the cache of resource which loaded by loadRes.

name type description
url String

releaseAll ( )

Resource cache of all resources.

Pipeline
(
  • pipes
)

Inherited from Pipeline:

Constructor, pass an array of pipes to construct a new Pipeline, the pipes will be chained in the given order. A pipe is an object which must contain an id in string and a handle function, the id must be unique in the pipeline. It can also include async property to identify whether it's an asynchronous process.

name type description
pipes Array

examples:

var pipeline = new Pipeline([
     {
         id: 'Downloader',
         handle: function (item, callback) {},
         async: true
     },
     {id: 'Parser', handle: function (item) {}, async: false}
 ]);

insertPipe
(
  • pipe
  • index
)

Inherited from Pipeline:

Insert a new pipe at the given index of the pipeline. A pipe must contain an id in string and a handle function, the id must be unique in the pipeline.

name type description
pipe Object

The pipe to be inserted

index Number

The index to insert

appendPipe
(
  • pipe
)

Inherited from Pipeline:

Add a new pipe at the end of the pipeline. A pipe must contain an id in string and a handle function, the id must be unique in the pipeline.

name type description
pipe Object

The pipe to be appended

flowIn
(
  • urlList
)
Array

Inherited from Pipeline:

Let new items flow into the pipeline. Each item can be a simple url string or an object, if it's an object, it must contain id property. You can specify its type by type property, by default, the type is the extension name in src. By adding a skips property including pipe ids, you can skip these pipe. The object can contain any supplementary property as you want.

name type description
urlList Array

returns:

type: Array

Items accepted by the pipeline

examples:

pipeline.flowIn([
     'res/Background.png',
     {
         id: 'res/scene.json',
         type: 'scene',
         name: 'scene',
         skips: ['Downloader']
     }
 ]);

flowInDeps
(
  • urlList
  • callback
)
Array

Inherited from Pipeline:

Let new items flow into the pipeline and give a callback when the list of items are all completed. This is for loading dependencies for an existing item in flow, usually used in a pipe logic. For example, we have a loader for scene configuration file in JSON, the scene will only be fully loaded after all its dependencies are loaded, then you will need to use function to flow in all dependencies found in the configuration file, and finish the loader pipe only after all dependencies are loaded (in the callback).

name type description
urlList Array
callback Function

returns:

type: Array

Items accepted by the pipeline

copyItemStates
(
  • srcItem
  • dstItems
)

Inherited from Pipeline:

Copy the item states from one source item to all destination items. It's quite useful when a pipe generate new items from one source item, then you should flowIn these generated items into pipeline, but you probably want them to skip all pipes the source item already go through, you can achieve it with this API.

For example, an unzip pipe will generate more items, but you won't want them to pass unzip or download pipe again.

name type description
srcItem Object

The source item

dstItems Array | Object

A single destination item or an array of destination items

isFlowing ( ) Boolean

Inherited from Pipeline:

Returns whether the pipeline is flowing (contains item) currently.

returns:

type: Boolean

getItems ( ) LoadingItems

Inherited from Pipeline:

Returns all items in pipeline.

returns:

type: LoadingItems

removeItem ( ) Boolean

Inherited from Pipeline:

Removes an item in pipeline, no matter it's in progress or completed.

returns:

type: Boolean

succeed or not

clear ( )

Inherited from Pipeline:

Clear the current pipeline, this function will clean up the items.

onProgress
(
  • completedCount
  • totalCount
  • item
)

Inherited from Pipeline:

This is a callback which will be invoked while an item flow out the pipeline, you should overwrite this function.

name type description
completedCount Number

The number of the items that are already completed.

totalCount Number

The total number of the items.

item Object

The latest item which flow out the pipeline.

examples:

pipeline.onProgress = function (completedCount, totalCount, item) {
     var progress = (100 * completedCount / totalCount).toFixed(2);
     cc.log(progress + '%');
 }

onComplete
(
  • error
  • items
)

Inherited from Pipeline:

This is a callback which will be invoked while all items flow out the pipeline, you should overwirte this function.

name type description
error Array

All errored urls will be stored in this array, if no error happened, then it will be null

items LoadingItems

All items.

examples:

pipeline.onComplete = function (error, items) {
     if (error)
         cc.log('Completed with ' + error.length + ' errors');
     else
         cc.log('Completed ' + items.totalCount + ' items');
 }

There are no methods that match your current filter settings. You can change your filter settings in the index section on this page. index