Class: Assets

Assets

The global Assets class, it's a singleton so you don't need to instantiate it.

The Assets class has four main responsibilities:

  1. Allows users to map URLs to keys and resolve them according to the user's browser capabilities
  2. Loads the resources and transforms them into assets that developers understand.
  3. Caches the assets and provides a way to access them.
  4. Allow developers to unload assets and clear the cache.

It also has a few advanced features:

  1. Allows developers to provide a assets.Manifest upfront of all assets and help manage them via Bundles.
  2. Allows users to background load assets. Shortening (or eliminating) load times and improving UX. With this feature, in-game loading bars can be a thing of the past!

Example

 import { Assets } from 'pixi.js';

 const bunny = await Assets.load('bunny.png');

Members

cache Cache

The global cache of all assets within PixiJS

detections FormatDetectionParser[]

All the detection parsers currently added to the Assets class.

loader Loader

The loader, loads stuff!

resolver Resolver

the resolver to map various urls

Methods

add (assets) void

Allows you to specify how to resolve any assets load requests. There are a few ways to add things here as shown below:

Name Type Description
assets (ArrayOr<UnresolvedAsset>)

the unresolved assets to add to the resolver

Example
 import { Assets } from 'pixi.js';

 // Simple
 Assets.add({alias: 'bunnyBooBoo', src: 'bunny.png'});
 const bunny = await Assets.load('bunnyBooBoo');

 // Multiple keys:
 Assets.add({alias: ['burger', 'chicken'], src: 'bunny.png'});

 const bunny = await Assets.load('burger');
 const bunny2 = await Assets.load('chicken');

 // passing options to to the object
 Assets.add({
     alias: 'bunnyBooBooSmooth',
     src: 'bunny{png,webp}',
     data: { scaleMode: SCALE_MODES.NEAREST }, // Base texture options
 });

 // Multiple assets

 // The following all do the same thing:

 Assets.add({alias: 'bunnyBooBoo', src: 'bunny{png,webp}'});

 Assets.add({
     alias: 'bunnyBooBoo',
     src: [
         'bunny.png',
         'bunny.webp',
    ],
 });

 const bunny = await Assets.load('bunnyBooBoo'); // Will try to load WebP if available

addBundle (bundleId, assets) void

This adds a bundle of assets in one go so that you can load 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
 import { Assets } from 'pixi.js';

 Assets.addBundle('animals', [
  { alias: 'bunny', src: 'bunny.png' },
  { alias: 'chicken', src: 'chicken.png' },
  { alias: 'thumper', src: 'thumper.png' },
 ]);
 // or
 Assets.addBundle('animals', {
     bunny: 'bunny.png',
     chicken: 'chicken.png',
     thumper: 'thumper.png',
 });

 const assets = await Assets.loadBundle('animals');

backgroundLoad (urls) Promise<void>

Initiate a background load of some assets. It will passively begin to load these assets in the background. So when you actually come to loading them you will get a promise that resolves to the loaded assets immediately

An example of this might be that you would background load game assets after your inital load. then when you got to actually load your game screen assets when a player goes to the game - the loading would already have stared or may even be complete, saving you having to show an interim load bar.

Name Type Description
urls ArrayOr<string>

the url / urls you want to background load

Returns:
Type Description
Promise<void>
Example
 import { Assets } from 'pixi.js';

 Assets.backgroundLoad('bunny.png');

 // later on in your app...
 await Assets.loadBundle('bunny.png'); // Will resolve quicker as loading may have completed!

backgroundLoadBundle (bundleIds) Promise<void>

Initiate a background of a bundle, works exactly like backgroundLoad but for bundles. this can only be used if the loader has been initiated with a manifest

Name Type Description
bundleIds ArrayOr<string>

the bundleId / bundleIds you want to background load

Returns:
Type Description
Promise<void>
Example
 import { Assets } from 'pixi.js';

 await Assets.init({
     manifest: {
         bundles: [
             {
                 name: 'load-screen',
                 assets: [...],
             },
             ...
         ],
     },
 });

 Assets.backgroundLoadBundle('load-screen');

 // Later on in your app...
 await Assets.loadBundle('load-screen'); // Will resolve quicker as loading may have completed!

get (keys) T | T<string, Record>

Instantly gets an asset already loaded from the cache. If the asset has not yet been loaded, it will return undefined. So it's on you! When in doubt just use Assets.load instead. (Remember, the loader will never load things more than once!)

Name Type Description
keys ArrayOr<string>

The key or keys for the assets that you want to access

Returns:
Type Description
T | T<string, Record>
  • The assets or hash of assets requested

init (options) Promise<void>

Best practice is to call this function before any loading commences Initiating is the best time to add any customization to the way things are loaded.

you do not need to call this for the Assets class to work, only if you want to set any initial properties

Name Type Description
options AssetInitOptions

options to initialize the Assets manager with

Returns:
Type Description
Promise<void>

load (urls, onProgress) Promise<T | Record<string, T>>

Loads your assets! You pass in a key or URL and it will return a promise that resolves to the loaded asset. If multiple assets a requested, it will return a hash of assets.

Don't worry about loading things multiple times, behind the scenes assets are only ever loaded once and the same promise reused behind the scenes so you can safely call this function multiple times with the same key and it will always return the same asset.

Name Type Attributes Description
urls ArrayOr<string> | UnresolvedAsset<ArrayOr>

the urls to load

onProgress ProgressCallback <optional>

optional function that is called when progress on asset loading is made. The function is passed a single parameter, progress, which represents the percentage (0.0 - 1.0) of the assets loaded.

Returns:
Type Description
Promise<T | Record<string, T>>
  • the assets that were loaded, either a single asset or a hash of assets
Example
 import { Assets } from 'pixi.js';

 // Load a URL:
 const myImageTexture = await Assets.load('http://some.url.com/image.png'); // => returns a texture

 Assets.add('thumper', 'bunny.png');
 Assets.add('chicko', 'chicken.png');

 // Load multiple assets:
 const textures = await Assets.load(['thumper', 'chicko']); // => {thumper: Texture, chicko: Texture}

loadBundle (bundleIds, onProgress) Promise<any>

Bundles are a way to load multiple assets at once. If a manifest has been provided to the init function then you can load a bundle, or bundles. you can also add bundles via addBundle

Name Type Attributes Description
bundleIds ArrayOr<string>

the bundle id or ids to load

onProgress ProgressCallback <optional>

Optional function that is called when progress on asset loading is made. The function is passed a single parameter, progress, which represents the percentage (0.0 - 1.0) of the assets loaded. Do not use this function to detect when assets are complete and available, instead use the Promise returned by this function.

Returns:
Type Description
Promise<any> all the bundles assets or a hash of assets for each bundle specified
Example
 import { Assets } from 'pixi.js';

 // 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',
                 },
             ],
         },
     ]
 };

 await Assets.init({ manifest });

 // Load a bundle...
 loadScreenAssets = await Assets.loadBundle('load-screen');
 // Load another bundle...
 gameScreenAssets = await Assets.loadBundle('game-screen');

reset () void

Only intended for development purposes. This will wipe the resolver and caches. You will need to reinitialize the Asset

setPreferences (preferences) void

General setter for preferences. This is a helper function to set preferences on all parsers.

Name Type Description
preferences Partial<AssetsPreferences>

the preferences to set

unload (urls) Promise<void>

Unload an asset or assets. As the Assets class is responsible for creating the assets via the load function this will make sure to destroy any assets and release them from memory. Once unloaded, you will need to load the asset again.

Use this to help manage assets if you find that you have a large app and you want to free up memory.

  • it's up to you as the developer to make sure that textures are not actively being used when you unload them, Pixi won't break but you will end up with missing assets. Not a good look for the user!
Name Type Description
urls ArrayOr<string> | ResolvedAsset | ResolvedAsset[]

the urls to unload

Returns:
Type Description
Promise<void>
Example
 import { Assets } from 'pixi.js';

 // Load a URL:
 const myImageTexture = await Assets.load('http://some.url.com/image.png'); // => returns a texture

 await Assets.unload('http://some.url.com/image.png')

 // myImageTexture will be destroyed now.

 // Unload multiple assets:
 const textures = await Assets.unload(['thumper', 'chicko']);

unloadBundle (bundleIds) Promise<void>

Bundles are a way to manage multiple assets at once. this will unload all files in a bundle.

once a bundle has been unloaded, you need to load it again to have access to the assets.

Name Type Description
bundleIds ArrayOr<string>

the bundle id or ids to unload

Returns:
Type Description
Promise<void>
Example
 import { Assets } from 'pixi.js';

 Assets.addBundle({
     'thumper': 'http://some.url.com/thumper.png',
 })

 const assets = await Assets.loadBundle('thumper');

 // Now to unload...

 await Assets.unloadBundle('thumper');

 // All assets in the assets object will now have been destroyed and purged from the cache