PixiJS

Class: Resolver

PIXI.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 PIXI.Resolver

Members

basePath string

Set the base path to append 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 PIXI.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(settings.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'
 ]);

Methods

add (keysIn, assetsIn, data) void

Resolver.ts:224

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

Name Type Attributes Description
keysIn string | string[]

The keys to map, can be an array or a single key
assetsIn string | PIXI.ResolveAsset | (PIXI.ResolveAsset | string)[]

The assets to associate with the key(s)
data unknown <optional>

The data that will be attached to the object that resolved object.
Example

 // single key, single asset:
 resolver.add('foo', 'bar.png');
 resolver.resolveUrl('foo') // => 'bar.png'

 // multiple keys, single asset:
 resolver.add(['foo', 'boo'], 'bar.png');
 resolver.resolveUrl('foo') // => 'bar.png'
 resolver.resolveUrl('boo') // => 'bar.png'

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

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

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

addBundle (bundleId, assets) void

Resolver.ts:178

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 PIXI.ResolverBundle["assets"]

A record of the asset or assets that will be chosen from when loading via the specified key
Example

  resolver.addBundle('animals', {
    bunny: 'bunny.png',
    chicken: 'chicken.png',
    thumper: 'thumper.png',
  });

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

addManifest (manifest) void

Resolver.ts:156

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 ResolverManifest

the manifest to add to the resolver

prefer (…preferOrders) void

Resolver.ts:52

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 PIXI.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

Resolver.ts:145

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

resolve (keys) PIXI.ResolveAsset | PIXI.ResolveAsset<string, Record>

Resolver.ts:420

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 string | string[]

key or keys to resolve
Returns:
Type Description
PIXI.ResolveAsset | PIXI.ResolveAsset<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, PIXI.ResolveAsset> | PIXI.ResolveAsset<string, Record<string, Record>>

Resolver.ts:336

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 string | string[]

The bundle ids to resolve
Returns:
Type Description
Record<string, PIXI.ResolveAsset> | PIXI.ResolveAsset<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:[
          {
             name: 'background',
             srcs: 'sunset.png',
          },
          {
             name: 'bar',
             srcs: 'load-bar.{png,webp}',
          }
      ]
   },
   {
      name:'game-screen',
      assets:[
          {
             name: 'character',
             srcs: 'robot.png',
          },
          {
             name: 'enemy',
             srcs: 'bad-guy.png',
          }
      ]
   }]
 }}
 resolver.setManifest(manifest);
 const resolved = resolver.resolveBundle('load-screen');

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

Resolver.ts:396

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

Name Type Description
key string | string[]

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