StaticcacheThe global cache for all loaded assets. Manages storage and retrieval of processed assets.
// Check if an asset is cached
if (Assets.cache.has('myTexture')) {
const texture = Assets.cache.get('myTexture');
}
Cache For detailed cache documentation
Static AdvancedloaderThe loader responsible for loading all assets. Handles different file types and transformations.
Static AdvancedresolverThe URL resolver for assets. Maps various asset keys and URLs to their final loadable form.
StaticdetectionsAdvancedAll the detection parsers currently added to the Assets class.
StaticaddAdvancedRegisters assets with the Assets resolver. This method maps keys (aliases) to asset sources, allowing you to load assets using friendly names instead of direct URLs.
The unresolved assets to add to the resolver
// Basic usage - single asset
Assets.add({
alias: 'myTexture',
src: 'assets/texture.png'
});
const texture = await Assets.load('myTexture');
// Multiple aliases for the same asset
Assets.add({
alias: ['hero', 'player'],
src: 'hero.png'
});
const hero1 = await Assets.load('hero');
const hero2 = await Assets.load('player'); // Same texture
// Multiple format support
Assets.add({
alias: 'character',
src: 'character.{webp,png}' // Will choose best format
});
Assets.add({
alias: 'character',
src: ['character.webp', 'character.png'], // Explicitly specify formats
});
// With texture options
Assets.add({
alias: 'sprite',
src: 'sprite.png',
data: { scaleMode: 'nearest' }
});
// Multiple assets at once
Assets.add([
{ alias: 'bg', src: 'background.png' },
{ alias: 'music', src: 'music.mp3' },
{ alias: 'spritesheet', src: 'sheet.json', data: { ignoreMultiPack: false } }
]);
data property is passed to the asset loaderStaticaddRegisters a bundle of assets that can be loaded as a group. Bundles are useful for organizing assets into logical groups, such as game levels or UI screens.
Unique identifier for the bundle
Assets to include in the bundle
// Add a bundle using array format
Assets.addBundle('animals', [
{ alias: 'bunny', src: 'bunny.png' },
{ alias: 'chicken', src: 'chicken.png' },
{ alias: 'thumper', src: 'thumper.png' },
]);
// Add a bundle using object format
Assets.addBundle('animals', {
bunny: 'bunny.png',
chicken: 'chicken.png',
thumper: 'thumper.png',
});
// Add a bundle with advanced options
Assets.addBundle('ui', [
{
alias: 'button',
src: 'button.{webp,png}',
data: { scaleMode: 'nearest' }
},
{
alias: ['logo', 'brand'], // Multiple aliases
src: 'logo.svg',
data: { resolution: 2 }
}
]);
// Load the bundle
await Assets.loadBundle('animals');
// Use the loaded assets
const bunny = Sprite.from('bunny');
const chicken = Sprite.from('chicken');
loadBundle is calledbackgroundLoadBundleStaticbackgroundInitiates background loading of assets. This allows assets to be loaded passively while other operations continue, making them instantly available when needed later.
Background loading is useful for:
Single URL/alias or array of URLs/aliases to load in the background
// Basic background loading
Assets.backgroundLoad('images/level2-assets.png');
// Background load multiple assets
Assets.backgroundLoad([
'images/sprite1.png',
'images/sprite2.png',
'images/background.png'
]);
// Later, when you need the assets
const textures = await Assets.load([
'images/sprite1.png',
'images/sprite2.png'
]); // Resolves immediately if background loading completed
StaticbackgroundInitiates background loading of asset bundles. Similar to backgroundLoad but works with predefined bundles of assets.
Perfect for:
Single bundle ID or array of bundle IDs to load in the background
// Define bundles in your manifest
await Assets.init({
manifest: {
bundles: [
{
name: 'home',
assets: [
{
alias: 'background',
src: 'images/home-bg.png',
},
{
alias: 'logo',
src: 'images/logo.png',
}
]
},
{
name: 'level-1',
assets: [
{
alias: 'background',
src: 'images/level1/bg.png',
},
{
alias: 'sprites',
src: 'images/level1/sprites.json'
}
]
}]
}
});
// Load the home screen assets right away
await Assets.loadBundle('home');
showHomeScreen();
// Start background loading while showing home screen
Assets.backgroundLoadBundle('level-1');
// When player starts level, load completes faster
await Assets.loadBundle('level-1');
hideHomeScreen();
startLevel();
Assets.loadBundle()addBundleStaticgetInstantly gets an asset already loaded from the cache. Returns undefined if the asset hasn't been loaded yet.
The key or keys for the assets to retrieve
The cached asset(s) or undefined if not loaded
// Get a single cached asset
const texture = Assets.get('hero');
if (texture) {
const sprite = new Sprite(texture);
}
// Get multiple cached assets
const textures = Assets.get([
'hero',
'background',
'enemy'
]);
// Safe pattern with loading fallback
let texture = Assets.get('hero');
if (!texture) {
texture = await Assets.load('hero');
}
// Working with bundles
await Assets.loadBundle('game-ui');
const uiAssets = Assets.get([
'button',
'panel',
'icons'
]);
Assets.load() for thatload() for already cached assets
When in doubt, use Assets.load() instead. It will return cached
assets instantly if they're already loaded.
Instantly gets an asset already loaded from the cache. Returns undefined if the asset hasn't been loaded yet.
The key or keys for the assets to retrieve
The cached asset(s) or undefined if not loaded
// Get a single cached asset
const texture = Assets.get('hero');
if (texture) {
const sprite = new Sprite(texture);
}
// Get multiple cached assets
const textures = Assets.get([
'hero',
'background',
'enemy'
]);
// Safe pattern with loading fallback
let texture = Assets.get('hero');
if (!texture) {
texture = await Assets.load('hero');
}
// Working with bundles
await Assets.loadBundle('game-ui');
const uiAssets = Assets.get([
'button',
'panel',
'icons'
]);
Assets.load() for thatload() for already cached assets
When in doubt, use Assets.load() instead. It will return cached
assets instantly if they're already loaded.
StaticinitInitializes the Assets class with configuration options. While not required, calling this before loading assets is recommended to set up default behaviors.
Configuration options for the Assets system
// Basic initialization (optional as Assets.load will call this automatically)
await Assets.init();
// With CDN configuration
await Assets.init({
basePath: 'https://my-cdn.com/assets/',
defaultSearchParams: { version: '1.0.0' }
});
// With manifest and preferences
await Assets.init({
manifest: {
bundles: [{
name: 'game-screen',
assets: [
{
alias: 'hero',
src: 'hero.{png,webp}',
data: { scaleMode: SCALE_MODES.NEAREST }
},
{
alias: 'map',
src: 'map.json'
}
]
}]
},
// Optimize for device capabilities
texturePreference: {
resolution: window.devicePixelRatio,
format: ['webp', 'png']
},
// Set global preferences
preferences: {
crossOrigin: 'anonymous',
}
});
// Load assets after initialization
const heroTexture = await Assets.load('hero');
skipDetections is trueStaticloadLoads one or more assets and returns a promise that resolves with the loaded content. Assets are cached, so subsequent loads will return the same instance of the asset without re-fetching.
Single URL/alias or array of URLs/aliases to load
OptionalonProgress: ProgressCallbackOptional callback for load progress (0.0 to 1.0)
Promise that resolves with loaded asset(s)
// Load a single asset
const texture = await Assets.load('images/sprite.png');
// Load using an alias
const heroTexture = await Assets.load({ alias: 'hero', src: 'images/hero.png' });
// Load multiple assets
const assets = await Assets.load([
'images/background.png',
'images/character.png',
'fonts/game.fnt'
]);
console.log(assets['images/background.png']); // Access by URL
// Load with progress tracking
const textures = await Assets.load(['sprite1.png', 'sprite2.png'],
(progress) => console.log(`Loading: ${Math.round(progress * 100)}%`)
);
// Load with format preference
const characterTexture = await Assets.load({
alias: 'character',
src: 'character.{webp,png}' // Will choose best format
});
// Load with custom options
const spriteTexture = await Assets.load({
alias: 'sprite',
src: 'sprite.png',
data: {
scaleMode: SCALE_MODES.NEAREST,
mipmap: MIPMAP_MODES.ON
}
});
// Load with a specific loader, can be useful if your asset does not have an extension
const image = await Assets.load({
alias: 'imageWithoutExtension',
src: 'images/imageWithoutExtension',
loadParser: 'loadTextures' // Use the JSON loader
});
loadParser property, which is useful for assets that do not have a file extension.Loads one or more assets and returns a promise that resolves with the loaded content. Assets are cached, so subsequent loads will return the same instance of the asset without re-fetching.
Single URL/alias or array of URLs/aliases to load
OptionalonProgress: ProgressCallbackOptional callback for load progress (0.0 to 1.0)
Promise that resolves with loaded asset(s)
// Load a single asset
const texture = await Assets.load('images/sprite.png');
// Load using an alias
const heroTexture = await Assets.load({ alias: 'hero', src: 'images/hero.png' });
// Load multiple assets
const assets = await Assets.load([
'images/background.png',
'images/character.png',
'fonts/game.fnt'
]);
console.log(assets['images/background.png']); // Access by URL
// Load with progress tracking
const textures = await Assets.load(['sprite1.png', 'sprite2.png'],
(progress) => console.log(`Loading: ${Math.round(progress * 100)}%`)
);
// Load with format preference
const characterTexture = await Assets.load({
alias: 'character',
src: 'character.{webp,png}' // Will choose best format
});
// Load with custom options
const spriteTexture = await Assets.load({
alias: 'sprite',
src: 'sprite.png',
data: {
scaleMode: SCALE_MODES.NEAREST,
mipmap: MIPMAP_MODES.ON
}
});
// Load with a specific loader, can be useful if your asset does not have an extension
const image = await Assets.load({
alias: 'imageWithoutExtension',
src: 'images/imageWithoutExtension',
loadParser: 'loadTextures' // Use the JSON loader
});
loadParser property, which is useful for assets that do not have a file extension.StaticloadLoads a bundle or multiple bundles of assets. Bundles are collections of related assets that can be loaded together.
Single bundle ID or array of bundle IDs to load
OptionalonProgress: ProgressCallbackOptional callback for load progress (0.0 to 1.0)
Promise that resolves with the loaded bundle assets
// Define bundles in your manifest
const manifest = {
bundles: [
{
name: 'load-screen',
assets: [
{
alias: 'background',
src: 'sunset.png',
},
{
alias: 'bar',
src: 'load-bar.{png,webp}', // use an array of individual assets
},
],
},
{
name: 'game-screen',
assets: [
{
alias: 'character',
src: 'robot.png',
},
{
alias: 'enemy',
src: 'bad-guy.png',
},
],
},
]
};
// Initialize with manifest
await Assets.init({ manifest });
// Or add bundles programmatically
Assets.addBundle('load-screen', [...]);
Assets.loadBundle('load-screen');
// Load a single bundle
await Assets.loadBundle('load-screen');
const bg = Sprite.from('background'); // Uses alias from bundle
// Load multiple bundles
await Assets.loadBundle([
'load-screen',
'game-screen'
]);
// Load with progress tracking
await Assets.loadBundle('game-screen', (progress) => {
console.log(`Loading: ${Math.round(progress * 100)}%`);
});
backgroundLoadBundleStaticsetSets global preferences for asset loading behavior. This method configures how assets are loaded and processed across all parsers.
Asset loading preferences
// Basic preferences
Assets.setPreferences({
crossOrigin: 'anonymous',
parseAsGraphicsContext: false
});
Preferences are applied to all compatible parsers and affect future asset loading. Common preferences include:
crossOrigin: CORS setting for loaded assetspreferWorkers: Whether to use web workers for loading texturespreferCreateImageBitmap: Use createImageBitmap for texture creation. Turning this off will use the Image constructor instead.AssetsPreferences For all available preferences
StaticunloadUnloads assets and releases them from memory. This method ensures proper cleanup of loaded assets when they're no longer needed.
Single URL/alias or array of URLs/aliases to unload
// Unload a single asset
await Assets.unload('images/sprite.png');
// Unload using an alias
await Assets.unload('hero'); // Unloads the asset registered with 'hero' alias
// Unload multiple assets
await Assets.unload([
'images/background.png',
'images/character.png',
'hero'
]);
// Unload and handle creation of new instances
await Assets.unload('hero');
const newHero = await Assets.load('hero'); // Will load fresh from source
StaticunloadUnloads all assets in a bundle. Use this to free memory when a bundle's assets are no longer needed, such as when switching game levels.
Single bundle ID or array of bundle IDs to unload
// Define and load a bundle
Assets.addBundle('level-1', {
background: 'level1/bg.png',
sprites: 'level1/sprites.json',
music: 'level1/music.mp3'
});
// Load the bundle
const level1 = await Assets.loadBundle('level-1');
// Use the assets
const background = Sprite.from(level1.background);
// When done with the level, unload everything
await Assets.unloadBundle('level-1');
// background sprite is now invalid!
// Unload multiple bundles
await Assets.unloadBundle([
'level-1',
'level-2',
'ui-elements'
]);
The global Assets class is a singleton that manages loading, caching, and unloading of all resources in your PixiJS application.
Key responsibilities:
Advanced Features:
Supported Asset Types:
.png,.jpg,.gif,.webp,.avif,.svg.mp4,.m4v,.webm,.ogg,.ogv,.h264,.avi,.mov.json.fnt,.xml,.txt.ttf,.otf,.woff,.woff2.json.txt.basis,.dds,.ktx,.ktx2Some loaders allow for custom configuration, please refer to the specific loader documentation for details.
Example
Remarks
When unloading assets, ensure they aren't being used elsewhere in your application to prevent missing texture references.
See