Engine API Reference - v1.77.0
    Preparing search index...

    Class AssetRegistry

    Container for all assets that are available to this application. Note that PlayCanvas scripts are provided with an AssetRegistry instance as app.assets.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    bundles prefix

    Methods

    add filter find findAll findByTag fire get getByUrl hasEvent list load loadFromUrl loadFromUrlAndFilename off on once remove

    Events

    EVENT_ADD EVENT_ERROR EVENT_LOAD EVENT_REMOVE

    Constructors

    Properties

    bundles: null | BundleRegistry = null

    BundleRegistry

    prefix: null | string = null

    A URL prefix that will be added to all asset loading requests.

    Methods

    • Add an asset to the registry.

      Parameters

      • asset: Asset

        The asset to add.

      Returns void

      const asset = new pc.Asset("My Asset", "texture", {
          url: "../path/to/image.jpg"
      });
      app.assets.add(asset);

    • Return all Assets that satisfy a filter callback.

      Parameters

      • callback: FilterAssetCallback

        The callback function that is used to filter assets. Return true to include an asset in the returned array.

      Returns Asset[]

      A list of all Assets found.

      const assets = app.assets.filter(asset => asset.name.includes('monster'));
      console.log(`Found ${assets.length} assets with a name containing 'monster'`);

    • Return the first Asset with the specified name and type found in the registry.

      Parameters

      • name: string

        The name of the Asset to find.

      • Optionaltype: string

        The type of the Asset to find.

      Returns null | Asset

      A single Asset or null if no Asset is found.

      const asset = app.assets.find("myTextureAsset", "texture");

    • Return all Assets with the specified name and type found in the registry.

      Parameters

      • name: string

        The name of the Assets to find.

      • Optionaltype: string

        The type of the Assets to find.

      Returns Asset[]

      A list of all Assets found.

      const assets = app.assets.findAll('brick', 'texture');
      console.log(`Found ${assets.length} texture assets named 'brick'`);

    • Return all Assets that satisfy the search query. Query can be simply a string, or comma separated strings, to have inclusive results of assets that match at least one query. A query that consists of an array of tags can be used to match assets that have each tag of array.

      Parameters

      • ...args: any

      Returns Asset[]

      A list of all Assets matched query.

      const assets = app.assets.findByTag("level-1");
      // returns all assets that tagged by `level-1`

      const assets = app.assets.findByTag("level-1", "level-2");
      // returns all assets that tagged by `level-1` OR `level-2`

      const assets = app.assets.findByTag(["level-1", "monster"]);
      // returns all assets that tagged by `level-1` AND `monster`

      const assets = app.assets.findByTag(["level-1", "monster"], ["level-2", "monster"]);
      // returns all assets that tagged by (`level-1` AND `monster`) OR (`level-2` AND `monster`)

    • Fire an event, all additional arguments are passed on to the event listener.

      Parameters

      • name: string

        Name of event to fire.

      • Optionalarg1: any

        First argument that is passed to the event handler.

      • Optionalarg2: any

        Second argument that is passed to the event handler.

      • Optionalarg3: any

        Third argument that is passed to the event handler.

      • Optionalarg4: any

        Fourth argument that is passed to the event handler.

      • Optionalarg5: any

        Fifth argument that is passed to the event handler.

      • Optionalarg6: any

        Sixth argument that is passed to the event handler.

      • Optionalarg7: any

        Seventh argument that is passed to the event handler.

      • Optionalarg8: any

        Eighth argument that is passed to the event handler.

      Returns EventHandler

      Self for chaining.

      obj.fire('test', 'This is the message');

    • Retrieve an asset from the registry by its id field.

      Parameters

      • id: number

        The id of the asset to get.

      Returns undefined | Asset

      The asset.

      const asset = app.assets.get(100);

    • Retrieve an asset from the registry by its file's URL field.

      Parameters

      • url: string

        The url of the asset to get.

      Returns undefined | Asset

      The asset.

      const asset = app.assets.getByUrl("../path/to/image.jpg");

    • Test if there are any handlers bound to an event name.

      Parameters

      • name: string

        The name of the event to test.

      Returns boolean

      True if the object has handlers bound to the specified event name.

      obj.on('test', function () { }); // bind an event to 'test'
      obj.hasEvent('test'); // returns true
      obj.hasEvent('hello'); // returns false

    • Create a filtered list of assets from the registry.

      Parameters

      • filters: any = {}

        Properties to filter on, currently supports: 'preload: true|false'.

      Returns Asset[]

      The filtered list of assets.

    • Load the asset's file from a remote source. Listen for "load" events on the asset to find out when it is loaded.

      Parameters

      • asset: Asset

        The asset to load.

      • Optionaloptions: {
            bundlesFilter?: BundlesFilterCallback;
            bundlesIgnore?: boolean;
            force?: boolean;
        }

        Options for asset loading.

        • OptionalbundlesFilter?: BundlesFilterCallback

          A callback that will be called when loading an asset that is contained in any of the bundles. It provides an array of bundles and will ensure asset is loaded from bundle returned from a callback. By default smallest filesize bundle is choosen.

        • OptionalbundlesIgnore?: boolean

          If set to true, then asset will not try to load from a bundle. Defaults to false.

        • Optionalforce?: boolean

          If set to true, then the check of asset being loaded or is already loaded is bypassed, which forces loading of asset regardless.

      Returns void

      // load some assets
      const assetsToLoad = [
          app.assets.find("My Asset"),
          app.assets.find("Another Asset")
      ];
      let count = 0;
      assetsToLoad.forEach(function (assetToLoad) {
          assetToLoad.ready(function (asset) {
              count++;
              if (count === assetsToLoad.length) {
                  // done
              }
          });
          app.assets.load(assetToLoad);
      });

    • Use this to load and create an asset if you don't have assets created. Usually you would only use this if you are not integrated with the PlayCanvas Editor.

      Parameters

      • url: string

        The url to load.

      • type: string

        The type of asset to load.

      • callback: LoadAssetCallback

        Function called when asset is loaded, passed (err, asset), where err is null if no errors were encountered.

      Returns void

      app.assets.loadFromUrl("../path/to/texture.jpg", "texture", function (err, asset) {
          const texture = asset.resource;
      });

    • Use this to load and create an asset when both the URL and filename are required. For example, use this function when loading BLOB assets, where the URL does not adequately identify the file.

      Parameters

      • url: string

        The url to load.

      • filename: string

        The filename of the asset to load.

      • type: string

        The type of asset to load.

      • callback: LoadAssetCallback

        Function called when asset is loaded, passed (err, asset), where err is null if no errors were encountered.

      Returns void

      const file = magicallyObtainAFile();
      app.assets.loadFromUrlAndFilename(URL.createObjectURL(file), "texture.png", "texture", function (err, asset) {
          const texture = asset.resource;
      });

    • Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

      Parameters

      • Optionalname: string

        Name of the event to unbind.

      • Optionalcallback: HandleEventCallback

        Function to be unbound.

      • Optionalscope: any

        Scope that was used as the this when the event is fired.

      Returns EventHandler

      Self for chaining.

      const handler = function () {
      };
      obj.on('test', handler);

      obj.off(); // Removes all events
      obj.off('test'); // Removes all events called 'test'
      obj.off('test', handler); // Removes all handler functions, called 'test'
      obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this

    • Attach an event handler to an event.

      Parameters

      • name: string

        Name of the event to bind the callback to.

      • callback: HandleEventCallback

        Function that is called when event is fired. Note the callback is limited to 8 arguments.

      • Optionalscope: any = ...

        Object to use as 'this' when the event is fired, defaults to current this.

      Returns EventHandle

      Can be used for removing event in the future.

      obj.on('test', function (a, b) {
          console.log(a + b);
      });
      obj.fire('test', 1, 2); // prints 3 to the console

      const evt = obj.on('test', function (a, b) {
          console.log(a + b);
      });
      // some time later
      evt.off();

    • Attach an event handler to an event. This handler will be removed after being fired once.

      Parameters

      • name: string

        Name of the event to bind the callback to.

      • callback: HandleEventCallback

        Function that is called when event is fired. Note the callback is limited to 8 arguments.

      • Optionalscope: any = ...

        Object to use as 'this' when the event is fired, defaults to current this.

      Returns EventHandle

      • can be used for removing event in the future.
      obj.once('test', function (a, b) {
          console.log(a + b);
      });
      obj.fire('test', 1, 2); // prints 3 to the console
      obj.fire('test', 1, 2); // not going to get handled

    • Remove an asset from the registry.

      Parameters

      • asset: Asset

        The asset to remove.

      Returns boolean

      True if the asset was successfully removed and false otherwise.

      const asset = app.assets.get(100);
      app.assets.remove(asset);

    Events

    EVENT_ADD: string = 'add'

    Fired when an asset is added to the registry. This event is available in three forms. They are as follows:

    1. add - Fired when any asset is added to the registry.
    2. add:[id] - Fired when an asset is added to the registry, where [id] is the unique id of the asset.
    3. add:url:[url] - Fired when an asset is added to the registry and matches the URL [url], where [url] is the URL of the asset.
    app.assets.on('add', (asset) => {
       console.log(`Asset added: ${asset.name}`);
    });

    const id = 123456;
    app.assets.on('add:' + id, (asset) => {
       console.log(`Asset added: ${asset.name}`);
    });

    const id = 123456;
    const asset = app.assets.get(id);
    app.assets.on('add:url:' + asset.file.url, (asset) => {
       console.log(`Asset added: ${asset.name}`);
    });
    EVENT_ERROR: string = 'error'

    Fired when an error occurs during asset loading. This event is available in two forms. They are as follows:

    1. error - Fired when any asset reports an error in loading.
    2. error:[id] - Fired when an asset reports an error in loading, where [id] is the unique id of the asset.
    const id = 123456;
    const asset = app.assets.get(id);
    app.assets.on('error', (err, asset) => {
        console.error(err);
    });
    app.assets.load(asset);

    const id = 123456;
    const asset = app.assets.get(id);
    app.assets.on('error:' + id, (err, asset) => {
        console.error(err);
    });
    app.assets.load(asset);
    EVENT_LOAD: string = 'load'

    Fired when an asset completes loading. This event is available in three forms. They are as follows:

    1. load - Fired when any asset finishes loading.
    2. load:[id] - Fired when a specific asset has finished loading, where [id] is the unique id of the asset.
    3. load:url:[url] - Fired when an asset finishes loading whose URL matches [url], where [url] is the URL of the asset.
    app.assets.on('load', (asset) => {
        console.log(`Asset loaded: ${asset.name}`);
    });

    const id = 123456;
    const asset = app.assets.get(id);
    app.assets.on('load:' + id, (asset) => {
        console.log(`Asset loaded: ${asset.name}`);
    });
    app.assets.load(asset);

    const id = 123456;
    const asset = app.assets.get(id);
    app.assets.on('load:url:' + asset.file.url, (asset) => {
        console.log(`Asset loaded: ${asset.name}`);
    });
    app.assets.load(asset);
    EVENT_REMOVE: string = 'remove'

    Fired when an asset is removed from the registry. This event is available in three forms. They are as follows:

    1. remove - Fired when any asset is removed from the registry.
    2. remove:[id] - Fired when an asset is removed from the registry, where [id] is the unique id of the asset.
    3. remove:url:[url] - Fired when an asset is removed from the registry and matches the URL [url], where [url] is the URL of the asset.

    The asset that was removed.

    app.assets.on('remove', (asset) => {
       console.log(`Asset removed: ${asset.name}`);
    });

    const id = 123456;
    app.assets.on('remove:' + id, (asset) => {
       console.log(`Asset removed: ${asset.name}`);
    });

    const id = 123456;
    const asset = app.assets.get(id);
    app.assets.on('remove:url:' + asset.file.url, (asset) => {
       console.log(`Asset removed: ${asset.name}`);
    });

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods
    Events