Create a new ResourceLoader instance.
The application.
Gets the maximum number of asset requests that can be in flight at the same time.
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.
Gets whether asset requests are sent with credentials.
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 AppBase#preload or 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.
Add a 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.
An instance of a resource handler
supporting at least load() and open().
Remove resource from cache.
The URL of the resource.
The type of resource.
Destroys the resource loader.
Disables retrying of failed requests when loading assets.
Enables retrying of failed requests when loading assets. Retries use exponential backoff and are also enabled by default for new applications.
OptionalmaxRetries: number = 5
The maximum number of times to retry loading an asset. Defaults to 5.
Check cache for resource from a URL. If present, return the cached value.
The URL of the resource to get from the cache.
The type of the resource.
The resource loaded from the cache.
Get a ResourceHandler for a resource type.
The name of the resource type that the handler is registered with.
The registered handler, or undefined if the requested handler is not registered.
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.
The URL of the resource to load.
The type of resource expected.
The callback used when the resource is loaded or an error occurs. Passed (err, resource) where err is null if there are no errors.
Optionalasset: Asset<string>
Optional asset that is passed into handler.
Optionaloptions: { bundlesFilter?: BundlesFilterCallback; bundlesIgnore?: boolean }
Additional options for loading.
OptionalbundlesFilter?: BundlesFilterCallbackA 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.
OptionalbundlesIgnore?: booleanIf set to true, then asset will not try to load from a bundle. Defaults to false.
Convert raw resource data into a resource instance. E.g. Take 3D model format JSON and return a Model.
The type of resource.
The raw resource data.
The parsed resource data.
Perform any operations on a resource, that requires a dependency on its asset data or any other asset data.
The asset to patch.
The asset registry.
Remove a ResourceHandler for a resource type.
The name of the type that the handler will be removed.
The ResourceLoader turns a URL and an asset type into a loaded resource. It owns one 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 AppBase#loader.
Most code never calls the loader directly: the AssetRegistry does so on its behalf when an Asset loads. Use the loader to add support for a new asset type with addHandler, to reach an existing handler with getHandler, or to tune requests with maxConcurrentRequests, withCredentials and 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.mjsadds.objmodel loading andplaycanvas/scripts/esm/parsers/spz-parser.mjsadds.spzGaussian-splat loading.Example
Example