Assets

The Assets class provides a modern, centralized system for managing and loading resources in PixiJS. It offers caching, background loading, bundle management, and smart format detection while supporting a wide range of file types.

Basic Usage

Load assets using the global Assets singleton:

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

// Initialize the asset system
await Assets.init({
    basePath: 'assets/',
});

// Load a single asset
const texture = await Assets.load<Texture>('bunny.png');

// Load multiple assets
const assets = await Assets.load(['bunny.png', 'spritesheet.json', 'font.ttf']);
Copy

Core Features

Asset Loading

The system supports many file types out of the box:

// Load textures (avif, webp, png, jpg, gif, svg)
const texture = await Assets.load('sprite.{webp,png}');

// Load video textures (mp4, webm, ogg)
const video = await Assets.load('clip.{webm,mp4}');

// Load spritesheets
const sheet = await Assets.load('sprites.json');

// Load fonts (ttf, woff, woff2)
const font = await Assets.load('font.ttf');

// Load data files
const data = await Assets.load('config.json');
const text = await Assets.load('info.txt');
Copy

Supported Asset Types:

Type	Extensions	Loaders
Textures	.png, .jpg, .gif, .webp, .avif, .svg	loadTextures, loadSvg
Video Textures	.mp4, .m4v, .webm, .ogg, .ogv, .h264, .avi, .mov	loadVideoTextures
Sprite Sheets	.json	spritesheetAsset
Bitmap Fonts	.fnt, .xml, .txt	loadBitmapFont
Web Fonts	.ttf, .otf, .woff, .woff2	loadWebFont
JSON	.json	loadJson
Text	.txt	loadTxt
Compressed Textures	.basis, .dds, .ktx, .ktx2	loadBasis, loadDDS, loadKTX, loadKTX2

Load Options & Strategies

Asset loading can fail for many reasons (network issues, corrupt files, unsupported formats). The loader provides configurable behavior through LoadOptions. These options can be supplied per call or globally (via Assets.init or by mutating Loader.defaultOptions / loader.loadOptions).

Supported options:

• onProgress(progress: number): Called as each asset completes (0.0–1.0)
• onError(error: Error, asset): Called whenever an individual asset fails
• strategy: 'throw' | 'skip' | 'retry'
• retryCount: Number of retry attempts when strategy is 'retry' (default 3)
• retryDelay: Delay in ms between retries (default 250)

Strategies

Strategy	Behavior	Error propagation	Use when
throw	First failure rejects the load promise	Yes (immediate)	Critical assets must all succeed
skip	Failed assets are ignored; others continue	No (but onError fires)	Optional / best-effort assets
retry	Retries each failing asset up to retryCount, then throws if still failing	Yes (after final attempt)	Transient network/CDN instability

Load Options Examples

await Assets.init({
    loadOptions: {
        strategy: 'retry',
        retryCount: 4,
        retryDelay: 400,
        onError: (err, asset) => console.debug('Retrying:', asset.src),
    },
});

// Later calls inherit these unless overridden
await Assets.load('critical.json');

// Skip missing optional texture
const tex = await Assets.load('optional.png', {
    strategy: 'skip',
    onError: (err, asset) => console.warn('Skipped:', asset, err.message),
});
Copy

Asset Bundles

Group related assets into bundles for organized loading:

// Define bundles
Assets.addBundle('loading-screen', [
    { alias: 'background', src: 'bg.png' },
    { alias: 'progress-bar', src: 'bar.png' },
]);

Assets.addBundle('game', [
    { alias: 'character', src: 'hero.png' },
    { alias: 'enemies', src: 'monsters.json' },
]);

// Load bundles
const loadingAssets = await Assets.loadBundle('loading-screen');
const gameAssets = await Assets.loadBundle('game');
Copy

Background Loading

Load assets in the background while maintaining performance:

// Start background loading
Assets.backgroundLoad(['level1.json', 'level2.json']);

// Later, get the assets instantly
const level1 = await Assets.load('level1.json'); // Resolves immediately if loaded
const level2 = await Assets.load('level2.json'); // Resolves immediately if loaded
Copy

Asset Configuration

Manifests

Define all your game's assets in a manifest:

const manifest = {
    bundles: [
        {
            name: 'game-essential',
            assets: [
                {
                    alias: 'hero',
                    src: 'characters/hero.{webp,png}',
                },
                {
                    alias: 'ui',
                    src: 'interface.json',
                },
            ],
        },
    ],
};

await Assets.init({ manifest });
// Load a bundle from the manifest
const gameAssets = await Assets.loadBundle('game-essential');
// or load individual assets
const heroTexture = await Assets.load('hero');
Copy

Format Preferences

Configure preferred asset formats and resolutions:

await Assets.init({
    texturePreference: {
        format: ['webp', 'png'], // Prefer WebP over PNG
        resolution: 2, // Prefer 2x resolution
    },
    defaultSearchParams: {
        // URL parameters
        version: '1.0.0',
    },
});
Copy

Cache Management

Control the asset cache:

// Check if asset is cached
const isCached = Assets.cache.has('texture.png');

// Get cached asset
const texture = Assets.get('texture.png');

// Unload specific assets
await Assets.unload('texture.png');

// Reset entire cache
Assets.reset();
Copy

Best Practices

• Use Assets.init() before loading any assets
• Leverage bundles for organized loading
• Use format fallbacks (e.g., image.{webp,png})
• Take advantage of background loading for better performance
• Clean up unused assets with Assets.unload()
• Consider using manifests for large applications

Related Documentation

• See Assets for the main asset manager
• See AssetsManifest for manifest configuration
• See LoaderParser for custom loaders
• See CacheParser for cache handling
• See BackgroundLoader for background loading
• See Texture for texture management
• See Spritesheet for sprite sheets
• See loadTextures for texture loading
• See loadWebFont for font loading

For more specific implementation details and advanced usage, refer to the API documentation of individual classes and interfaces.