Comprehensive asset loading system supporting textures, fonts, JSON, and custom formats. Includes caching, URL resolution, progress tracking, and background loading with a powerful plugin architecture for handling different asset types.
Main static class for asset management providing a simple interface for loading, caching, and resolving assets.
/**
* Main assets management class
*/
class Assets {
/**
* Load assets by URL or alias
* @param urls - URLs or aliases to load
* @param onProgress - Progress callback
* @returns Promise resolving to loaded assets
*/
static load<T = any>(urls: string | string[], onProgress?: ProgressCallback): Promise<T>;
/**
* Add assets to the resolver
* @param assets - Asset configurations to add
*/
static add(assets: string | AssetInitOptions | (string | AssetInitOptions)[]): void;
/**
* Get cached asset by key
* @param keys - Asset keys to retrieve
* @returns Cached asset(s)
*/
static get<T = any>(keys: string | string[]): T;
/**
* Check if asset exists in cache
* @param key - Asset key to check
* @returns True if asset exists
*/
static has(key: string): boolean;
/**
* Unload assets and remove from cache
* @param urls - URLs or aliases to unload
* @returns Promise resolving when unloaded
*/
static unload(urls: string | string[]): Promise<void>;
/**
* Initialize assets system
* @param options - Initialization options
* @returns Promise resolving when initialized
*/
static init(options?: AssetsInitOptions): Promise<void>;
/** Asset cache system */
static readonly cache: Cache;
/** Asset URL resolver */
static readonly resolver: Resolver;
/** Asset loader */
static readonly loader: Loader;
/**
* Set base URL for all assets
* @param url - Base URL
*/
static setBaseUrl(url: string): void;
/**
* Reset assets system
*/
static reset(): void;
}Configuration objects for adding assets to the system.
interface AssetInitOptions {
/** Asset alias */
alias?: string | string[];
/** Asset URL */
src: string | string[];
/** Asset data */
data?: any;
/** Asset format */
format?: string;
/** Load parser */
loadParser?: string;
/** Cache parser */
cacheParser?: string;
}
interface AssetsInitOptions {
/** Base URL for assets */
basePath?: string;
/** Default search parameters */
defaultSearchParams?: Record<string, string>;
/** Prefer worker loading */
preferWorkers?: boolean;
/** Manifest URL */
manifest?: string;
/** Asset bundles */
bundles?: BundleIdentifierOptions[];
}
interface BundleIdentifierOptions {
/** Bundle name */
name: string;
/** Assets in bundle */
assets: AssetInitOptions[];
}Asset loading system with queue management and progress tracking.
/**
* Asset loader with queue management
*/
class Loader {
constructor();
/**
* Add assets to load queue
* @param assetsToLoad - Assets to add
* @returns This loader
*/
add(assetsToLoad: string | LoadAsset | (string | LoadAsset)[]): this;
/**
* Load all queued assets
* @param onProgress - Progress callback
* @returns Promise resolving to loaded assets
*/
load<T>(onProgress?: ProgressCallback): Promise<T>;
/**
* Load assets by URLs
* @param urls - URLs to load
* @param onProgress - Progress callback
* @returns Promise resolving to loaded assets
*/
load<T>(urls: string | string[], onProgress?: ProgressCallback): Promise<T>;
/**
* Reset loader state
* @returns This loader
*/
reset(): this;
/**
* Get loading progress
* @returns Progress percentage (0-1)
*/
get progress(): number;
/** Currently loading flag */
readonly loading: boolean;
/** Number of assets to load */
readonly totalToLoad: number;
}
interface LoadAsset {
/** Asset alias */
alias?: string[];
/** Asset URL */
src: string;
/** Loading data */
data?: any;
/** Load parser to use */
loadParser?: string;
}
type ProgressCallback = (progress: number) => void;URL resolution system for asset aliases and bundles.
/**
* Asset URL resolver
*/
class Resolver {
constructor();
/**
* Add asset configurations
* @param assets - Assets to add
*/
add(assets: string | ResolveAsset | (string | ResolveAsset)[]): void;
/**
* Resolve URL from alias
* @param key - Asset key or alias
* @returns Resolved URL(s)
*/
resolveUrl(key: string): string | string[];
/**
* Resolve asset configuration
* @param key - Asset key
* @returns Resolved asset configuration
*/
resolve(key: string): ResolveAsset;
/**
* Check if key exists
* @param key - Asset key
* @returns True if exists
*/
hasKey(key: string): boolean;
/**
* Remove asset from resolver
* @param key - Asset key to remove
*/
remove(key: string): void;
/**
* Add bundle of assets
* @param bundleId - Bundle identifier
* @param assets - Assets in bundle
*/
addBundle(bundleId: string, assets: ResolveAsset[]): void;
/**
* Remove bundle
* @param bundleId - Bundle identifier
*/
removeBundle(bundleId: string): void;
/**
* Get bundle asset keys
* @param bundleId - Bundle identifier
* @returns Asset keys in bundle
*/
resolveBundle(bundleId: string): string[];
/**
* Set base URL
* @param url - Base URL
*/
setBaseUrl(url: string): void;
/**
* Reset resolver
*/
reset(): void;
}
interface ResolveAsset {
/** Asset alias */
alias?: string[];
/** Asset URL */
src: string;
/** Asset format */
format?: string;
/** Asset data */
data?: any;
}Asset caching system for storing loaded assets.
/**
* Asset cache system
*/
class Cache {
constructor();
/**
* Set cached asset
* @param key - Asset key
* @param asset - Asset to cache
*/
set<T>(key: string, asset: T): void;
/**
* Get cached asset
* @param key - Asset key
* @returns Cached asset
*/
get<T>(key: string): T;
/**
* Check if asset is cached
* @param key - Asset key
* @returns True if cached
*/
has(key: string): boolean;
/**
* Remove asset from cache
* @param key - Asset key
*/
remove(key: string): void;
/**
* Clear all cached assets
*/
reset(): void;
/** All cached keys */
readonly keys: string[];
}Parsers for different asset types and formats.
/**
* Asset parser interface
*/
interface LoaderParser<ASSET = any, META_DATA = any> {
/** Parser name */
name?: string;
/** Supported extensions */
extension: string | string[];
/** Test if parser can handle asset */
test?: (url: string, options?: LoadAsset) => boolean;
/** Load asset */
load?: (url: string, asset: LoadAsset, loader: Loader) => Promise<ASSET>;
/** Unload asset */
unload?: (asset: ASSET, resolvedAsset?: ResolveAsset) => void | Promise<void>;
}
/**
* Texture loader parser
*/
const loadTextures: LoaderParser;
/**
* JSON loader parser
*/
const loadJson: LoaderParser;
/**
* Web font loader parser
*/
const loadWebFont: LoaderParser;
/**
* SVG loader parser
*/
const loadSVG: LoaderParser;
/**
* Video texture loader parser
*/
const loadVideoTextures: LoaderParser;Background asset loading system for preloading assets.
/**
* Background loader for preloading assets
*/
class BackgroundLoader {
constructor(loader: Loader);
/**
* Add assets to background load queue
* @param urls - URLs to load in background
*/
add(urls: string | string[]): void;
/**
* Start background loading
*/
start(): void;
/**
* Stop background loading
*/
stop(): void;
/** Is currently loading */
readonly active: boolean;
}Usage Examples:
import { Assets, Texture, Sprite } from 'pixi.js';
// Basic asset loading
const texture = await Assets.load('character.png');
const sprite = new Sprite(texture);
// Multiple assets
const assets = await Assets.load([
'background.jpg',
'character.png',
'music.mp3'
]);
// Using aliases
Assets.add([
{ alias: 'hero', src: 'characters/hero.png' },
{ alias: 'villain', src: 'characters/villain.png' },
{ alias: 'bgm', src: 'audio/background.mp3' }
]);
const heroTexture = await Assets.load('hero');
const villain = await Assets.load('villain');
// Progress tracking
const manifest = await Assets.load({
alias: 'gameAssets',
src: [
'level1/background.jpg',
'level1/tiles.png',
'level1/enemies.json',
'level1/music.mp3'
]
}, (progress) => {
console.log(`Loading: ${Math.round(progress * 100)}%`);
});
// Bundle loading
Assets.addBundle('level1', [
{ alias: 'bg', src: 'level1/bg.jpg' },
{ alias: 'tiles', src: 'level1/tiles.png' },
{ alias: 'config', src: 'level1/config.json' }
]);
const level1Assets = await Assets.loadBundle('level1');
// Preloading with background loader
Assets.backgroundLoad([
'level2/background.jpg',
'level2/enemies.png',
'level3/background.jpg'
]);
// Custom asset types
Assets.add({
alias: 'gameData',
src: 'data/game.json',
data: { parseAsGameConfig: true }
});
// Unloading assets
await Assets.unload(['level1', 'unused-texture.png']);
// Cache management
const cachedTexture = Assets.get('hero');
if (Assets.has('hero')) {
console.log('Hero texture is cached');
}
// Web fonts
Assets.add({
alias: 'gameFont',
src: 'fonts/GameFont.woff2',
data: { family: 'GameFont' }
});
await Assets.load('gameFont');
// Video textures
const videoTexture = await Assets.load('intro-video.mp4');
const videoSprite = new Sprite(videoTexture);