/** * Callback used by {@link ResourceLoader#load} when a resource is loaded (or an error occurs). */ export type ResourceLoaderCallback = (err: string | null, resource?: any) => void; /** * @import { AppBase } from '../app-base.js' * @import { AssetRegistry } from '../asset/asset-registry.js' * @import { Asset } from '../asset/asset.js' * @import { AssetType } from '../asset/asset.js' * @import { BundlesFilterCallback } from '../asset/asset-registry.js' * @import { ResourceHandler } from './handler.js' */ /** * @callback ResourceLoaderCallback * Callback used by {@link ResourceLoader#load} when a resource is loaded (or an error occurs). * @param {string|null} err - The error message in the case where the load fails. * @param {any} [resource] - The resource that has been successfully loaded. * @returns {void} */ /** * The ResourceLoader turns a URL and an asset type into a loaded resource. It owns one * {@link ResourceHandler} per type, dispatches each request to the matching handler, and caches the * result by URL and type so the same request is fetched once. Each application has one at * {@link AppBase#loader}. * * Most code never calls the loader directly: the {@link AssetRegistry} does so on its behalf when * an {@link Asset} loads. Use the loader to add support for a new asset type with * {@link addHandler}, to reach an existing handler with {@link getHandler}, or to tune requests * with {@link maxConcurrentRequests}, {@link withCredentials} and {@link enableRetry}. * * Parsers for formats the engine does not load by default ship in the package and are registered on * an existing handler rather than added as one: `playcanvas/scripts/esm/parsers/obj-model.mjs` adds * `.obj` model loading and `playcanvas/scripts/esm/parsers/spz-parser.mjs` adds `.spz` * Gaussian-splat loading. * * @example * app.loader.getHandler('model').addParser(new ObjModelParser(app.graphicsDevice)); * @example * app.loader.getHandler('gsplat').addParser(new SpzParser(app)); * @category Asset */ export class ResourceLoader { static makeKey(url: any, type: any): string; /** * Create a new ResourceLoader instance. * * @param {AppBase} app - The application. */ constructor(app: AppBase); _handlers: {}; _requests: {}; _cache: {}; _app: AppBase; /** * Add a {@link ResourceHandler} for a resource type. Handler should support at least `load()` * and `open()`. Handlers can optionally support patch(asset, assets) to handle dependencies on * other assets. * * @param {AssetType | (string & {})} type - The name of the resource type that the handler will * be registered with: one of the built-in {@link AssetType} names, such as `'texture'`, `'model'` * or `'container'`, or a new name for an application-defined handler. See {@link AssetMap} for * typing the resource of a new name. * @param {ResourceHandler} handler - An instance of a resource handler * supporting at least `load()` and `open()`. * @example * // register a handler for a new 'csv' asset type (see ResourceHandler for the class) * app.loader.addHandler('csv', new CsvHandler(app)); */ addHandler(type: AssetType | (string & {}), handler: ResourceHandler): void; /** * Remove a {@link ResourceHandler} for a resource type. * * @param {AssetType | (string & {})} type - The name of the type that the handler will be removed. */ removeHandler(type: AssetType | (string & {})): void; /** * Get a {@link ResourceHandler} for a resource type. * * @param {AssetType | (string & {})} type - The name of the resource type that the handler is * registered with. * @returns {ResourceHandler|undefined} The registered handler, or * undefined if the requested handler is not registered. */ getHandler(type: AssetType | (string & {})): ResourceHandler | undefined; /** * Make a request for a resource from a remote URL. Parse the returned data using the handler * for the specified type. When loaded and parsed, use the callback to return an instance of * the resource. * * @param {string} url - The URL of the resource to load. * @param {string} type - The type of resource expected. * @param {ResourceLoaderCallback} callback - The callback used when the resource is loaded or * an error occurs. Passed (err, resource) where err is null if there are no errors. * @param {Asset} [asset] - Optional asset that is passed into * handler. * @param {object} [options] - Additional options for loading. * @param {boolean} [options.bundlesIgnore] - If set to true, then asset will not try to load * from a bundle. Defaults to false. * @param {BundlesFilterCallback} [options.bundlesFilter] - 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, * the smallest filesize bundle is chosen. * @example * app.loader.load("../path/to/texture.png", "texture", function (err, texture) { * // use texture here * }); */ load(url: string, type: string, callback: ResourceLoaderCallback, asset?: Asset, options?: { bundlesIgnore?: boolean; bundlesFilter?: BundlesFilterCallback; }): void; _loadNull(handler: any, callback: any, asset: any): void; _onSuccess(key: any, result: any, extra: any): void; _onFailure(key: any, err: any): void; /** * Convert raw resource data into a resource instance. E.g. Take 3D model format JSON and * return a {@link Model}. * * @param {string} type - The type of resource. * @param {*} data - The raw resource data. * @returns {*} The parsed resource data. */ open(type: string, data: any): any; /** * Perform any operations on a resource, that requires a dependency on its asset data or any * other asset data. * * @param {Asset} asset - The asset to patch. * @param {AssetRegistry} assets - The asset registry. */ patch(asset: Asset, assets: AssetRegistry): void; /** * Remove resource from cache. * * @param {string} url - The URL of the resource. * @param {string} type - The type of resource. */ clearCache(url: string, type: string): void; /** * Check cache for resource from a URL. If present, return the cached value. * * @param {string} url - The URL of the resource to get from the cache. * @param {string} type - The type of the resource. * @returns {*} The resource loaded from the cache. */ getFromCache(url: string, type: string): any; /** * Enables retrying of failed requests when loading assets. Retries use exponential backoff and * are also enabled by default for new applications. * * @param {number} [maxRetries] - The maximum number of times to retry loading an asset. * Defaults to 5. */ enableRetry(maxRetries?: number): void; /** * Disables retrying of failed requests when loading assets. */ disableRetry(): void; /** * Sets the maximum number of asset requests that can be in flight at the same time. Additional * requests are queued and dispatched as earlier ones complete. This prevents browsers from * rejecting requests with `net::ERR_INSUFFICIENT_RESOURCES` when an app loads a very large * number of assets at once. Set to `0` to disable throttling. Defaults to 128. * * Note: this is a process-global limit (it applies to the shared HTTP layer, matching the * browser's per-process resource limit), so with multiple applications the last value set wins. * It applies to all XHR-based requests, which covers the large majority of asset loads. * * @type {number} * @example * // never have more than 50 asset requests in flight at once * app.loader.maxConcurrentRequests = 50; */ set maxConcurrentRequests(value: number); /** * Gets the maximum number of asset requests that can be in flight at the same time. * * @type {number} */ get maxConcurrentRequests(): number; /** * Sets whether asset requests are sent with credentials. When true, cross-origin requests * include credentials (cookies, client TLS certificates and HTTP authentication), allowing * assets to be loaded from an authenticated cross-origin host. The server must respond with a * non-wildcard `Access-Control-Allow-Origin` and `Access-Control-Allow-Credentials: true`. * Defaults to false. * * Set this before assets start loading (i.e. before {@link AppBase#preload} or * {@link AssetRegistry#load}). Note this is a process-global setting (it applies to the shared * HTTP layer), so with multiple applications the last value set wins. It covers every asset * load, including the asset bundle and gaussian splat loaders that fetch their data directly * rather than through the HTTP layer. * * @type {boolean} * @example * // load all assets from an authenticated cross-origin host * app.loader.withCredentials = true; */ set withCredentials(value: boolean); /** * Gets whether asset requests are sent with credentials. * * @type {boolean} */ get withCredentials(): boolean; /** * Destroys the resource loader. */ destroy(): void; } import type { AppBase } from '../app-base.js'; import type { AssetType } from '../asset/asset.js'; import type { ResourceHandler } from './handler.js'; import type { Asset } from '../asset/asset.js'; import type { BundlesFilterCallback } from '../asset/asset-registry.js'; import type { AssetRegistry } from '../asset/asset-registry.js';