Options
All
  • Public
  • Public/Protected
  • All
Menu

Class CCLoader

Loader for resource loading process. The engine automatically initialize its singleton object {{loader}}.

static
deprecated

since v3.0 loader is deprecated, please backup your project and upgrade to assetManager

Hierarchy

  • CCLoader

Index

Properties

Accessors

Methods

Properties

_autoReleaseSetting

_autoReleaseSetting: Record<string, boolean> = Object.create(null)

Private _parseLoadResArgs

_parseLoadResArgs: parseLoadResArgs = parseLoadResArgs

Accessors

cache

  • get cache(): null | {}

downloader

  • The downloader in loader's pipeline, it's by default the second 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

    deprecated

    since v3.0 loader.downloader is deprecated, please use assetManager.downloader instead

    Returns Downloader

loader

  • The loader in loader's pipeline, it's by default the third 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

    deprecated

    since v3.0 loader.loader is deprecated, please use assetManager.parser instead

    Returns Parser

md5Pipe

  • get md5Pipe(): { transformURL: any }

  • The md5 pipe in loader's pipeline, it could be absent if the project isn't build with md5 option.
    It's used to modify the url to the real downloadable url with md5 suffix.

    deprecated

    since v3.0 loader.md5Pipe is deprecated, assetLoader and md5Pipe were merged into assetManager.transformPipeline

    Returns { transformURL: any }

onProgress

  • set onProgress(val: ProgressCallback): void

  • The default progression callback during the loading process, if no progression callback is passed to {{load}} function, then this default callback will be used.

    deprecated

    since v3.0, loader.onProgress is deprecated, please transfer onProgress to API as a parameter

    Parameters

    • val: ProgressCallback

    Returns void

Methods

addDownloadHandlers

  • addDownloadHandlers(extMap: Record<string, (item: { url: string }, cb: CompleteCallback) => void>): void

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

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

    since v3.0 loader.addDownloadHandlers is deprecated, please use assetManager.downloader.register instead

    Parameters

    • extMap: Record<string, (item: { url: string }, cb: CompleteCallback) => void>

      Handlers for corresponding type in a map

    Returns void

addLoadHandlers

  • addLoadHandlers(extMap: Record<string, (namedParameters: { any: any }, cb: CompleteCallback) => void>): void

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

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

    since v3.0 loader.addLoadHandlers is deprecated, please use assetManager.parser.register instead

    Parameters

    • extMap: Record<string, (namedParameters: { any: any }, cb: CompleteCallback) => void>

      Handlers for corresponding type in a map

    Returns void

getDependsRecursively

  • getDependsRecursively(owner: Asset | string): string[]

  • Get all resource dependencies of the requested asset in an array, including itself.
    The owner parameter accept the following types: 1. The asset itself; 2. The resource url; 3. The asset's uuid.
    The returned array stores the dependencies with their uuids, after retrieve dependencies,
    you can release them, access dependent assets by passing the uuid to getRes, or other stuffs you want.
    For release all dependencies of an asset, please refer to release Here is some examples:

    example
    // Release all dependencies of a loaded prefab
let deps = loader.getDependsRecursively(prefab);
loader.release(deps);
// Retrieve all dependent textures
let deps = loader.getDependsRecursively('prefabs/sample');
let textures = [];
for (let i = 0; i < deps.length; ++i) {
    let item = loader.getRes(deps[i]);
    if (item instanceof cc.Texture2D) {
        textures.push(item);
    }
}
    deprecated

    since v3.0 loader.getDependsRecursively is deprecated, please use use assetManager.dependUtil.getDepsRecursively instead

    Parameters

    • owner: Asset | string

      The owner asset or the resource url or the asset's uuid

    Returns string[]

    the dependencies list

getItem

  • getItem(id: any): null | { content: undefined | Asset }

  • Returns an item in pipeline.

    deprecated

    since v3.0 loader.getItem is deprecated, please use assetManager.assets.get instead

    Parameters

    • id: any

      The id of the item

    Returns null | { content: undefined | Asset }

getRes

  • getRes<T>(url: string, type?: Constructor<T>): T | null

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

    deprecated

    since v3.0 loader.getRes is deprecated, please use resources.get instead

    Type parameters

    Parameters

    • url: string
    • Optional type: Constructor<T>

      Only asset of type will be returned if this argument is supplied.

    Returns T | null

getResCount

  • getResCount(): number

getXMLHttpRequest

  • getXMLHttpRequest(): XMLHttpRequest

  • Gets a new XMLHttpRequest instance.

    deprecated

    since v3.0 loader.getXMLHttpRequest is deprecated, please use XMLHttpRequest directly

    Returns XMLHttpRequest

isAutoRelease

  • isAutoRelease(asset: Asset | string): boolean

  • Returns whether the asset is configured as auto released, despite how "Auto Release Assets" property is set on scene asset.

    See: {{setAutoRelease}}, {{setAutoReleaseRecursively}}

    method

    isAutoRelease

    deprecated

    cc.loader.isAutoRelease is deprecated

    Parameters

    • asset: Asset | string

      asset object or the raw asset's url

    Returns boolean

load

  • load(res: string | string[] | Record<string, any>, progressCallback?: ((...args: any[]) => void) | null, completeCallback?: ((...args: any[]) => void) | null): void

  • Load resources with a progression callback and a complete callback.

    example
    loader.load('a.png', function (err, tex) {
    cc.log('Result should be a texture: ' + (tex instanceof cc.Texture2D));
});
loader.load('http://example.com/a.png', function (err, tex) {
    cc.log('Should load a texture from external url: ' + (tex instanceof cc.Texture2D));
});
loader.load({url: '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));
});
    deprecated

    since v3.0, loader.load is deprecated, please use assetManager.loadRemote instead

    Parameters

    • res: string | string[] | Record<string, any>

      Url list in an array

    • Optional progressCallback: ((...args: any[]) => void) | null

      Callback invoked when progression change

    • Optional completeCallback: ((...args: any[]) => void) | null

      Callback invoked when all resources loaded

    Returns void

loadRes

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

    deprecated

    since v3.0 loader.loadRes is deprecated, please use resources.load instead

    example

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

    Type parameters

    Parameters

    • url: string

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

    • type: Constructor<T>

      Only asset of type will be loaded if this argument is supplied.

    • progressCallback: LoadProgressCallback

      Callback invoked when progression change.

    • completeCallback: LoadCompleteCallback<T>

      Callback invoked when the resource loaded.

    Returns any

  • Type parameters

    Parameters

    Returns any

  • Type parameters

    Parameters

    Returns any

  • Type parameters

    Parameters

    Returns any

loadResArray

  • This method is like loadRes except that it accepts array of url.

    deprecated

    since v3.0 loader.loadResArray is deprecated, please use resources.load instead

    example
    // load the SpriteFrames from resources folder
let spriteFrames;
let urls = ['misc/characters/character_01', 'misc/weapons/weapons_01'];
loader.loadResArray(urls, cc.SpriteFrame, function (err, assets) {
    if (err) {
        cc.error(err);
        return;
    }
    spriteFrames = assets;
    // ...
});

    Type parameters

    Parameters

    • urls: string[]

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

    • Optional type: Constructor<T>

      Only asset of type will be loaded if this argument is supplied.

    • Optional progressCallback: LoadProgressCallback

      Callback invoked when progression change.

    • Optional completeCallback: LoadCompleteCallback<T[]>

      A callback which is called when all assets have been loaded, or an error occurs.

    Returns void

loadResDir

release

  • release(asset: Asset | string | Array<Asset | string>): void

  • Release the content of an asset or an array of assets by uuid.
    This method will not only remove the cache of the asset in loader, but also clean up its content.
    For example, if you release a texture, the texture asset and its gl texture data will be freed up.
    In complexe project, you can use this function with getDependsRecursively to free up memory in critical circumstances.
    Notice, this method may cause the texture to be unusable, if there are still other nodes use the same texture, they may turn to black and report gl errors.

    example
    // Release a texture which is no longer need
loader.release(texture);
// Release all dependencies of a loaded prefab
let deps = loader.getDependsRecursively('prefabs/sample');
loader.release(deps);
// If there is no instance of this prefab in the scene, the prefab and its dependencies like textures, sprite frames, etc, will be freed up.
// If you have some other nodes share a texture in this prefab, you can skip it in two ways:
// 1. Forbid auto release a texture before release
loader.setAutoRelease(texture2d, false);
// 2. Remove it from the dependencies array
let deps = loader.getDependsRecursively('prefabs/sample');
let index = deps.indexOf(texture2d._uuid);
if (index !== -1)
    deps.splice(index, 1);
loader.release(deps);
    deprecated

    since v3.0 loader.release is deprecated, please use assetManager.releaseAsset instead

    Parameters

    • asset: Asset | string | Array<Asset | string>

      Asset or assets to be released

    Returns void

releaseAll

  • releaseAll(): void

  • Resource all assets. Refer to {{release}} for detailed informations.

    deprecated

    since v3.0 loader.releaseAll is deprecated, please use assetManager.releaseAll instead

    Returns void

releaseAsset

  • releaseAsset(asset: Asset): void

  • Release the asset by its object. Refer to {{release}} for detailed informations.

    deprecated

    since v3.0 loader.releaseAsset is deprecated, please use assetManager.releaseAsset instead

    Parameters

    • asset: Asset

      The asset to be released

    Returns void

releaseRes

  • Release the asset loaded by {{loadRes}}. Refer to {{release}} for detailed informations.

    deprecated

    since v3.0 loader.releaseRes is deprecated, please use cc.assetManager.releaseRes instead

    Parameters

    • res: string

      The asset url, it should be related path without extension to the resources folder.

    • Optional type: Constructor<Asset>

      If type is provided, the asset for correspond type will be returned

    Returns void

removeItem

  • removeItem(id: any): boolean

  • Removes an completed item in pipeline. It will only remove the cache in the pipeline or loader, its dependencies won't be released. cc.loader provided another method to completely cleanup the resource and its dependencies, please refer to {{Loader.release}}

    deprecated

    since 3.0, loader.removeItem is deprecated, please use assetManager.assets.remove instead

    Parameters

    • id: any

      The id of the item

    Returns boolean

    succeed or not

setAutoRelease

  • setAutoRelease(asset: Asset | string, autoRelease: boolean): void

  • Indicates whether to release the asset when loading a new scene.
    By default, when loading a new scene, all assets in the previous scene will be released or preserved
    according to whether the previous scene checked the "Auto Release Assets" option.
    On the other hand, assets dynamically loaded by using loader.loadRes or loader.loadResDir
    will not be affected by that option, remain not released by default.
    Use this API to change the default behavior on a single asset, to force preserve or release specified asset when scene switching.

    See: {{setAutoReleaseRecursively}}, {{isAutoRelease}}

    example
    // auto release the texture event if "Auto Release Assets" disabled in current scene
loader.setAutoRelease(texture2d, true);
// don't release the texture even if "Auto Release Assets" enabled in current scene
loader.setAutoRelease(texture2d, false);
// first parameter can be url
loader.setAutoRelease(audioUrl, false);
    deprecated

    since v3.0 loader.setAutoRelease is deprecated, if you want to prevent some asset from auto releasing, please use Asset.addRef instead

    Parameters

    • asset: Asset | string

      The asset or its url or its uuid

    • autoRelease: boolean

      Whether to release automatically during scene switch

    Returns void

setAutoReleaseRecursively

  • setAutoReleaseRecursively(asset: Asset | string, autoRelease: boolean): void

  • Indicates whether to release the asset and its referenced other assets when loading a new scene.
    By default, when loading a new scene, all assets in the previous scene will be released or preserved
    according to whether the previous scene checked the "Auto Release Assets" option.
    On the other hand, assets dynamically loaded by using loader.loadRes or loader.loadResDir
    will not be affected by that option, remain not released by default.
    Use this API to change the default behavior on the specified asset and its recursively referenced assets, to force preserve or release specified asset when scene switching.

    See: {{setAutoRelease}}, {{isAutoRelease}}

    example
    // auto release the SpriteFrame and its Texture event if "Auto Release Assets" disabled in current scene
loader.setAutoReleaseRecursively(spriteFrame, true);
// don't release the SpriteFrame and its Texture even if "Auto Release Assets" enabled in current scene
loader.setAutoReleaseRecursively(spriteFrame, false);
// don't release the Prefab and all the referenced assets
loader.setAutoReleaseRecursively(prefab, false);
    deprecated

    loader.setAutoReleaseRecursively is deprecated, if you want to prevent some asset from auto releasing, please use Asset.addRef instead

    Parameters

    • asset: Asset | string

      The asset or its url or its uuid

    • autoRelease: boolean

      Whether to release automatically during scene switch

    Returns void

Generated using TypeDoc