# ResourceLoader

Class · category: Asset

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/framework/handlers/loader.js#L43

The ResourceLoader turns a URL and an asset type into a loaded resource. It owns one
[ResourceHandler](https://api.playcanvas.com/engine/classes/ResourceHandler.md) 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](https://api.playcanvas.com/engine/classes/AppBase.md#loader).

Most code never calls the loader directly: the [AssetRegistry](https://api.playcanvas.com/engine/classes/AssetRegistry.md) does so on its behalf when
an [Asset](https://api.playcanvas.com/engine/classes/Asset.md) loads. Use the loader to add support for a new asset type with
[addHandler](https://api.playcanvas.com/engine/classes/ResourceLoader.md#addhandler), to reach an existing handler with [getHandler](https://api.playcanvas.com/engine/classes/ResourceLoader.md#gethandler), or to tune requests
with [maxConcurrentRequests](https://api.playcanvas.com/engine/classes/ResourceLoader.md#maxconcurrentrequests), [withCredentials](https://api.playcanvas.com/engine/classes/ResourceLoader.md#withcredentials) and [enableRetry](https://api.playcanvas.com/engine/classes/ResourceLoader.md#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**

```ts
app.loader.getHandler('model').addParser(new ObjModelParser(app.graphicsDevice));
```

**Example**

```ts
app.loader.getHandler('gsplat').addParser(new SpzParser(app));
```

## Constructors

### constructor

```ts
new ResourceLoader(app: AppBase)
```

Create a new ResourceLoader instance.

**Parameters**

- `app` ([`AppBase`](https://api.playcanvas.com/engine/classes/AppBase.md)): The application.

## Accessors

### maxConcurrentRequests

```ts
get maxConcurrentRequests(): number
set maxConcurrentRequests(value: number)
```

Gets the maximum number of asset requests that can be in flight at the same time.

### withCredentials

```ts
get withCredentials(): boolean
set withCredentials(value: boolean)
```

Gets whether asset requests are sent with credentials.

## Methods

### addHandler

```ts
addHandler(type: string & {} | AssetType, handler: ResourceHandler): void
```

Add a [ResourceHandler](https://api.playcanvas.com/engine/classes/ResourceHandler.md) 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.

**Parameters**

- `type` (`string & {} |` [`AssetType`](https://api.playcanvas.com/engine/types/AssetType.md)): The name of the resource type that the handler will
  be registered with: one of the built-in [AssetType](https://api.playcanvas.com/engine/types/AssetType.md) names, such as `'texture'`, `'model'`
  or `'container'`, or a new name for an application-defined handler. See [AssetMap](https://api.playcanvas.com/engine/interfaces/AssetMap.md) for
  typing the resource of a new name.
- `handler` ([`ResourceHandler`](https://api.playcanvas.com/engine/classes/ResourceHandler.md)): An instance of a resource handler
  supporting at least `load()` and `open()`.

**Example**

```ts
// register a handler for a new 'csv' asset type (see ResourceHandler for the class)
app.loader.addHandler('csv', new CsvHandler(app));
```

### clearCache

```ts
clearCache(url: string, type: string): void
```

Remove resource from cache.

**Parameters**

- `url` (`string`): The URL of the resource.
- `type` (`string`): The type of resource.

### destroy

```ts
destroy(): void
```

Destroys the resource loader.

### disableRetry

```ts
disableRetry(): void
```

Disables retrying of failed requests when loading assets.

### enableRetry

```ts
enableRetry(maxRetries?: number): void
```

Enables retrying of failed requests when loading assets. Retries use exponential backoff and
are also enabled by default for new applications.

**Parameters**

- `maxRetries` (`number`, optional, default `5`): The maximum number of times to retry loading an asset.
  Defaults to 5.

### getFromCache

```ts
getFromCache(url: string, type: string): any
```

Check cache for resource from a URL. If present, return the cached value.

**Parameters**

- `url` (`string`): The URL of the resource to get from the cache.
- `type` (`string`): The type of the resource.

**Returns** `any`: The resource loaded from the cache.

### getHandler

```ts
getHandler(type: string & {} | AssetType): ResourceHandler | undefined
```

Get a [ResourceHandler](https://api.playcanvas.com/engine/classes/ResourceHandler.md) for a resource type.

**Parameters**

- `type` (`string & {} |` [`AssetType`](https://api.playcanvas.com/engine/types/AssetType.md)): The name of the resource type that the handler is
  registered with.

**Returns** [`ResourceHandler`](https://api.playcanvas.com/engine/classes/ResourceHandler.md) `| undefined`: The registered handler, or
undefined if the requested handler is not registered.

### load

```ts
load(url: string, type: string, callback: ResourceLoaderCallback, asset?: Asset<string>, options?: object): void
```

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.

**Parameters**

- `url` (`string`): The URL of the resource to load.
- `type` (`string`): The type of resource expected.
- `callback` ([`ResourceLoaderCallback`](https://api.playcanvas.com/engine/types/ResourceLoaderCallback.md)): The callback used when the resource is loaded or
  an error occurs. Passed (err, resource) where err is null if there are no errors.
- `asset` ([`Asset`](https://api.playcanvas.com/engine/classes/Asset.md)`<string>`, optional): Optional asset that is passed into
  handler.
- `options` (`object`, optional): Additional options for loading.
    - `options.bundlesFilter` ([`BundlesFilterCallback`](https://api.playcanvas.com/engine/types/BundlesFilterCallback.md), optional): 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.
    - `options.bundlesIgnore` (`boolean`, optional): If set to true, then asset will not try to load
      from a bundle. Defaults to false.

**Example**

```ts
app.loader.load("../path/to/texture.png", "texture", function (err, texture) {
    // use texture here
});
```

### open

```ts
open(type: string, data: any): any
```

Convert raw resource data into a resource instance. E.g. Take 3D model format JSON and
return a [Model](https://api.playcanvas.com/engine/classes/Model.md).

**Parameters**

- `type` (`string`): The type of resource.
- `data` (`any`): The raw resource data.

**Returns** `any`: The parsed resource data.

### patch

```ts
patch(asset: Asset<string>, assets: AssetRegistry): void
```

Perform any operations on a resource, that requires a dependency on its asset data or any
other asset data.

**Parameters**

- `asset` ([`Asset`](https://api.playcanvas.com/engine/classes/Asset.md)`<string>`): The asset to patch.
- `assets` ([`AssetRegistry`](https://api.playcanvas.com/engine/classes/AssetRegistry.md)): The asset registry.

### removeHandler

```ts
removeHandler(type: string & {} | AssetType): void
```

Remove a [ResourceHandler](https://api.playcanvas.com/engine/classes/ResourceHandler.md) for a resource type.

**Parameters**

- `type` (`string & {} |` [`AssetType`](https://api.playcanvas.com/engine/types/AssetType.md)): The name of the type that the handler will be removed.