Skip to main content

Assets

PixiJS has the Assets singleton which is used to streamline resource loading. It’s modern, Promise-based, cache-aware, and highly extensible—making it the one stop shop for all PixiJS resource management!

import { Assets } from 'pixi.js';

await Assets.init({ ... });

const texture = await Assets.load('path/to/hero.png');

Key Capabilities​

  • Asynchronous loading of assets via Promises or async/await.
  • Caching prevents redundant network requests.
  • Built-in support for common media formats (images, video, fonts).
  • Custom parsers and resolvers for flexibility.
  • Background loading, manifest-based bundles, and smart fallbacks.

Supported File Types​

TypeExtensionsLoaders
Textures.png, .jpg, .gif, .webp, .avif, .svgloadTextures, loadSvg
Video Textures.mp4, .m4v, .webm, .ogg, .ogv, .h264, .avi, .movloadVideoTextures
Sprite Sheets.jsonspritesheetAsset
Bitmap Fonts.fnt, .xml, .txtloadBitmapFont
Web Fonts.ttf, .otf, .woff, .woff2loadWebFont
JSON.jsonloadJson
Text.txtloadTxt
Compressed Textures.basis, .dds, .ktx, .ktx2loadBasis, loadDDS, loadKTX

Need more? Add custom parsers!

Getting started​

Loading Assets​

Loading an asset with PixiJS is as simple as calling Assets.load() and passing in the asset’s URL. This function returns a Promise that resolves to the loaded resource—whether that’s a texture, font, JSON, or another supported format.

You can provide either an absolute URL (e.g. from a CDN):

const texture = await Assets.load('https://example.com/assets/hero.png');

Or a relative path within your project:

const texture = await Assets.load('assets/hero.png');

PixiJS will typically automatically determine how to load the asset based on its file extension and will cache the result to avoid redundant downloads.

import { Application, Assets, Texture } from 'pixi.js';

const app = new Application();
// Application must be initialized before loading assets
await app.init({ backgroundColor: 0x1099bb });

// Load a single asset
const bunnyTexture = await Assets.load<Texture>('path/to/bunny.png');
const sprite = new Sprite(bunnyTexture);

// Load multiple assets at once
const textures = await Assets.load<Texture>(['path/to/bunny.png', 'path/to/cat.png']);
const bunnySprite = new Sprite(textures['path/to/bunny.png']);
const catSprite = new Sprite(textures['path/to/cat.png']);

Repeated Loads Are Safe​

Assets caches by URL or alias. Requests for the same resource return the same texture.

const p1 = await Assets.load('bunny.png');
const p2 = await Assets.load('bunny.png');
console.log(p1 === p2); // true

Asset Aliases​

You can also use aliases to refer to assets instead of their full URLs. This provides a more convenient way to manage assets, especially when you have long or complex URLs.

await Assets.load<Texture>({ alias: 'bunny', src: 'path/to/bunny.png' });
const bunnyTexture = Assets.get('bunny');

All Asset APIs support aliases, including Assets.load(), Assets.get(), and Assets.unload().

There is more complex ways of defining assets and you can read about them in the Resolver section.

Retrieving Loaded Assets​

You can also retrieve assets that have already been loaded using Assets.get():

await Assets.load<Texture>('path/to/bunny.png');
const bunnyTexture = Assets.get('path/to/bunny.png');
const sprite = new Sprite(bunnyTexture);

This is useful for when you have preloaded your assets elsewhere in your code and want to access them later without having to pass round references from the initial load.

Unloading Assets​

To unload an asset, you can use Assets.unload(). This will remove the asset from the cache and free up memory. Note that if you try to access the asset after unloading it, you will need to load it again.

await Assets.load<Texture>('path/to/bunny.png');
const bunnyTexture = Assets.get('path/to/bunny.png');
const sprite = new Sprite(bunnyTexture);
// Unload the asset
await Assets.unload('path/to/bunny.png');

Customizing Asset Loading​

You can customize the asset loading process by providing options to the Assets.init() method. This allows you to set preferences for how assets are loaded, specify a base path for assets, and more.

import { Assets } from 'pixi.js';

await Assets.init({...});
OptionTypeDescription
basePathstringPrefix applied to all relative asset paths (e.g. for CDNs).
defaultSearchParamsstringA default URL parameter string to append to all assets loaded
skipDetectionsbooleanSkip environment detection parsers for assets.
manifestManifestA descriptor of named asset bundles and their contents.
preferencesAssetPreferencesSpecifies preferences for each loader
bundleIdentifierBundleIdentifierOptionsAdvanced - Override how bundlesIds are generated.

Advanced Usage​

There are several advanced features available in the Assets API that can help you manage your assets more effectively. You can read more about these features in the rest of the documentation:

API Reference​