PixiJS

Class: Resolver

Resolver

A class that is responsible for resolving mapping asset URLs to keys. At its most basic it can be used for Aliases:

resolver.add('foo', 'bar');
resolver.resolveUrl('foo') // => 'bar'

It can also be used to resolve the most appropriate asset for a given URL:

resolver.prefer({
    params: {
        format: 'webp',
        resolution: 2,
    }
});

resolver.add('foo', ['bar@2x.webp', 'bar@2x.png', 'bar.webp', 'bar.png']);

resolver.resolveUrl('foo') // => 'bar@2x.webp'

Other features include:

  • Ability to process a manifest file to get the correct understanding of how to resolve all assets
  • Ability to add custom parsers for specific file types
  • Ability to add custom prefer rules

This class only cares about the URL, not the loading of the asset itself.

It is not intended that this class is created by developers - its part of the Asset class This is the third major system of PixiJS' main Assets class

new Resolver ()

Members

RETINA_PREFIX RegExp static

The prefix that denotes a URL is for a retina asset.

Default Value:
  • /@([0-9\.]+)x/
Example
`@2x`

basePath string

Set the base path to prepend to all urls when resolving

Example
resolver.basePath = 'https://home.com/';
resolver.add('foo', 'bar.ong');
resolver.resolveUrl('foo', 'bar.png'); // => 'https://home.com/bar.png'

parsers ResolveURLParser[]

All the active URL parsers that help the parser to extract information and create an asset object-based on parsing the URL itself.

Can be added using the extensions API

Example
 resolver.add('foo', [
     {
         resolution: 2,
         format: 'png',
         src: 'image@2x.png',
     },
     {
         resolution:1,
         format:'png',
         src: 'image.png',
     },
 ]);

 // With a url parser the information such as resolution and file format could extracted from the url itself:
 extensions.add({
     extension: ExtensionType.ResolveParser,
     test: loadTextures.test, // test if url ends in an image
     parse: (value: string) =>
     ({
         resolution: parseFloat(Resolver.RETINA_PREFIX.exec(value)?.[1] ?? '1'),
         format: value.split('.').pop(),
         src: value,
     }),
 });

 // Now resolution and format can be extracted from the url
 resolver.add('foo', [
     'image@2x.png',
     'image.png',
 ]);

rootPath string

Set the root path for root-relative URLs. By default the basePath's root is used. If no basePath is set, then the default value for browsers is window.location.origin

Example
// Application hosted on https://home.com/some-path/index.html
resolver.basePath = 'https://home.com/some-path/';
resolver.rootPath = 'https://home.com/';
resolver.add('foo', '/bar.png');
resolver.resolveUrl('foo', '/bar.png'); // => 'https://home.com/bar.png'

Methods

add (aliases) void

ts:420

Tells the resolver what keys are associated with witch asset. The most important thing the resolver does

Name Type Description
aliases ArrayOr<UnresolvedAsset>

the UnresolvedAsset or array of UnresolvedAssets to add to the resolver
Example
 // Single key, single asset:
 resolver.add({alias: 'foo', src: 'bar.png');
 resolver.resolveUrl('foo') // => 'bar.png'

 // Multiple keys, single asset:
 resolver.add({alias: ['foo', 'boo'], src: 'bar.png'});
 resolver.resolveUrl('foo') // => 'bar.png'
 resolver.resolveUrl('boo') // => 'bar.png'

 // Multiple keys, multiple assets:
 resolver.add({alias: ['foo', 'boo'], src: ['bar.png', 'bar.webp']});
 resolver.resolveUrl('foo') // => 'bar.png'

 // Add custom data attached to the resolver
 Resolver.add({
     alias: 'bunnyBooBooSmooth',
     src: 'bunny{png,webp}',
     data: { scaleMode:SCALE_MODES.NEAREST }, // Base texture options
 });

 resolver.resolve('bunnyBooBooSmooth') // => { src: 'bunny.png', data: { scaleMode: SCALE_MODES.NEAREST } }

addBundle (bundleId, assets) void

ts:343

This adds a bundle of assets in one go so that you can resolve them as a group. For example you could add a bundle for each screen in you pixi app

Name Type Description
bundleId string

The id of the bundle to add
assets AssetsBundle["assets"]

A record of the asset or assets that will be chosen from when loading via the specified key
Example
 resolver.addBundle('animals', [
  { alias: 'bunny', src: 'bunny.png' },
  { alias: 'chicken', src: 'chicken.png' },
  { alias: 'thumper', src: 'thumper.png' },
 ]);
 // or
 resolver.addBundle('animals', {
     bunny: 'bunny.png',
     chicken: 'chicken.png',
     thumper: 'thumper.png',
 });

 const resolvedAssets = await resolver.resolveBundle('animals');

addManifest (manifest) void

ts:321

Add a manifest to the asset resolver. This is a nice way to add all the asset information in one go. generally a manifest would be built using a tool.

Name Type Description
manifest AssetsManifest

the manifest to add to the resolver

getAlias (asset) string[]

ts:299

Returns the aliases for a given asset

Name Type Description
asset UnresolvedAsset

the asset to get the aliases for
Returns:
Type Description
string[]

hasBundle (key) boolean

ts:741

Checks if a bundle with the given key exists in the resolver

Name Type Description
key string

The key of the bundle
Returns:
Type Description
boolean

hasKey (key) boolean

ts:732

Checks if an asset with a given key exists in the resolver

Name Type Description
key string

The key of the asset
Returns:
Type Description
boolean

prefer (…preferOrders) void

ts:149

Let the resolver know which assets you prefer to use when resolving assets. Multiple prefer user defined rules can be added.

Name Type Description
preferOrders PreferOrder[]

the prefer options
Example
resolver.prefer({
    // first look for something with the correct format, and then then correct resolution
    priority: ['format', 'resolution'],
    params:{
        format:'webp', // prefer webp images
        resolution: 2, // prefer a resolution of 2
    }
})
resolver.add('foo', ['bar@2x.webp', 'bar@2x.png', 'bar.webp', 'bar.png']);
resolver.resolveUrl('foo') // => 'bar@2x.webp'

reset () void

ts:262

Used for testing, this resets the resolver to its initial state

resolve (keys) ResolvedAsset | ResolvedAsset<string, Record>

ts:660

Resolves each key in the list to an asset object. Another key function of the resolver! After adding all the various key/asset pairs. this will run the logic of finding which asset to return based on any preferences set using the prefer function by default the same key passed in will be returned if nothing is matched by the resolver.

Name Type Description
keys ArrayOr<string>

key or keys to resolve
Returns:
Type Description
ResolvedAsset | ResolvedAsset<string, Record>
  • the resolve asset or a hash of resolve assets for each key specified
Example
 resolver.add('boo', 'bunny.png');

 resolver.resolve('boo') // => { src: 'bunny.png' }

 // Will return the same string as no key was added for this value..
 resolver.resolve('another-thing.png') // => { src: 'another-thing.png' }

resolveBundle (bundleIds) Record<string, ResolvedAsset> | ResolvedAsset<string, Record<string, Record>>

ts:562

If the resolver has had a manifest set via setManifest, this will return the assets urls for a given bundleId or bundleIds.

Name Type Description
bundleIds ArrayOr<string>

The bundle ids to resolve
Returns:
Type Description
Record<string, ResolvedAsset> | ResolvedAsset<string, Record<string, Record>> All the bundles assets or a hash of assets for each bundle specified
Example
 // Manifest Example
 const manifest = {
     bundles: [
         {
             name: 'load-screen',
             assets: [
                 {
                     alias: 'background',
                     src: 'sunset.png',
                 },
                 {
                     alias: 'bar',
                     src: 'load-bar.{png,webp}',
                 },
             ],
         },
         {
             name: 'game-screen',
             assets: [
                 {
                     alias: 'character',
                     src: 'robot.png',
                 },
                 {
                     alias: 'enemy',
                     src: 'bad-guy.png',
                 },
             ],
         },
     ]
 };

 resolver.setManifest(manifest);
 const resolved = resolver.resolveBundle('load-screen');

resolveUrl (key) string | Record<string, string>

ts:636

Does exactly what resolve does, but returns just the URL rather than the whole asset object

Name Type Description
key ArrayOr<string>

The key or keys to resolve
Returns:
Type Description
string | Record<string, string>
  • The URLs associated with the key(s)

setBundleIdentifier (bundleIdentifier) void

ts:132

Override how the resolver deals with generating bundle ids. must be called before any bundles are added

Name Type Description
bundleIdentifier BundleIdentifierOptions

the bundle identifier options

setDefaultSearchParams (searchParams) void

ts:279

Sets the default URL search parameters for the URL resolver. The urls can be specified as a string or an object.

Name Type Description
searchParams string | Record<string, unknown>

the default url parameters to append when resolving urls