PixiJS

Namespace: Assets

PIXI.Assets

A one stop shop for all Pixi resource management! Super modern and easy to use, with enough flexibility to customize and do what you need!

Only one Asset Class exists accessed via the Global Asset object.

It 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 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!

Do not be afraid to load things multiple times - under the hood, it will NEVER load anything more than once.

for example:

promise1 = PIXI.Assets.load('bunny.png')
promise2 = PIXI.Assets.load('bunny.png')

//promise1 === promise2

here both promises will be the same. Once resolved.. forever resolved! It makes for really easy resource management!

Out of the box it supports the following files:

  • textures (avif, webp, png, jpg, gif)
  • sprite sheets (json)
  • bitmap fonts (xml, fnt, txt)
  • web fonts (ttf, woff, woff2)
  • json files (json)
  • text files (txt)

More types can be added fairly easily by creating additional loader parsers.

Textures

  • Textures are loaded as ImageBitmap on a worker thread where possible. Leading to much less janky load + parse times.
  • By default, we will prefer to load AVIF and WebP image files if you specify them. But if the browser doesn't support AVIF or WebP we will fall back to png and jpg.
  • Textures can also be accessed via Texture.from(...) and now use this asset manager under the hood!
  • Don't worry if you set preferences for textures that don't exist (for example you prefer 2x resolutions images but only 1x is available for that texture, the Asset manager will pick that up as a fallback automatically)

Sprite sheets

  • it's hard to know what resolution a sprite sheet is without loading it first, to address this there is a naming convention we have added that will let Pixi understand the image format and resolution of the spritesheet via its file name:

my-spritesheet{resolution}.{imageFormat}.json

for example:

my-spritesheet@2x.webp.json // 2x resolution, WebP sprite sheet my-spritesheet@0.5x.png.json // 0.5x resolution, png sprite sheet

This is optional! you can just load a sprite sheet as normal, This is only useful if you have a bunch of different res / formatted spritesheets

Fonts

  • Web fonts will be loaded with all weights. it is possible to load only specific weights by doing the following:
// load specific weights..
await PIXI.Assets.load({
   data: {
     weights: ['normal'], // only loads the weight
   },
   src: `outfit.woff2`,
});

// load everything...
await PIXI.Assets.load(`outfit.woff2`);

Background Loading

Background loading will load stuff for you passively behind the scenes. To minimize jank, it will only load one asset at a time. As soon as a developer calls PIXI.Assets.load(...) the background loader is paused and requested assets are loaded as a priority. Don't worry if something is in there that's already loaded, it will just get skipped!

You still need to call PIXI.Assets.load(...) to get an asset that has been loaded in the background. It's just that this promise will resolve instantly if the asset has already been loaded.

Manifest and Bundles

  • Manifest is a JSON file that contains a list of all assets and their properties.
  • Bundles are a way to group assets together.
// 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',
         }
     ]
  }]
}}

await PIXI.Asset.init({
 manifest
});

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

Example


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

Members

cache PIXI.Cache

The global cache of all assets within PixiJS

detections FormatDetectionParser[]

All the detection parsers currently added to the Assets class.

loader PIXI.AssetLoader

The loader, loads stuff!

resolver PIXI.Resolver

the resolver to map various urls

Methods

add (keysIn, assetsIn, data) void

Assets.ts:316

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 Attributes Description
keysIn string | string[]

the key or keys that you will reference when loading this asset
assetsIn string | (PIXI.ResolveAsset | string)[]

the asset or assets that will be chosen from when loading via the specified key
data unknown <optional>

asset-specific data that will be passed to the loaders

  • Useful if you want to initiate loaded objects with specific data
Example

 // simple
 PIXI.Assets.add('bunnyBooBoo', 'bunny.png');
 const bunny = await PIXI.Assets.load('bunnyBooBoo');

 // multiple keys:
 PIXI.Assets.add(['burger', 'chicken'], 'bunny.png');

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

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

 // multiple assets,

 // the following all do the same thing:

 PIXI.Assets.add('bunnyBooBoo', 'bunny{png,webp}');

 PIXI.Assets.add('bunnyBooBoo', [
 'bunny.png',
 'bunny.webp'
 ]);

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

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

addBundle (bundleId, assets) void

Assets.ts:426

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

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

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

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

backgroundLoad (urls) Promise<void>

Assets.ts:538

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

the url / urls you want to background load
Returns:
Type Description
Promise<void>
Example

 PIXI.Assets.backgroundLoad('bunny.png');

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

backgroundLoadBundle (bundleIds) Promise<void>

Assets.ts:569

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

the bundleId / bundleIds you want to background load
Returns:
Type Description
Promise<void>
Example

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

 PIXI.Assets.backgroundLoadBundle('load-screen');

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

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

Assets.ts:624

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 PIXI.Assets.load instead. (remember, the loader will never load things more than once!)

Name Type Description
keys string | 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>

Assets.ts:239

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 Asset class to work, only if you want to set any initial properties

Name Type Description
options PIXI.AssetInitOptions

options to initialize the Asset manager with
Returns:
Type Description
Promise<void>

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

Assets.ts:370

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

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

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

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

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

loadBundle (bundleIds, onProgress) Promise<any>

Assets.ts:445

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 string | 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.
Returns:
Type Description
Promise<any> 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',
          }
      ]
   }]
 }}

 await Asset.init({
  manifest
 });

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

reset () void

Assets.ts:610

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

unload (urls) Promise<void>

Assets.ts:692

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

the urls to unload
Returns:
Type Description
Promise<void>
Example

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

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

 myImageTexture <-- will now be destroyed.

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

unloadBundle (bundleIds) Promise<void>

Assets.ts:732

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

the bundle id or ids to unload
Returns:
Type Description
Promise<void>
Example

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

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

 // now to unload..

 await await PIXI.Assets.unloadBundle('thumper');

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