0
# Asset Loading
1

2
Modern asset loading system with support for various formats, bundles, and caching strategies. The Assets API replaces the legacy PIXI.Loader with a more flexible and powerful approach.
3

4
## Capabilities
5

6
### Assets API
7

8
The main Assets class provides static methods for loading and managing assets.
9

10
```typescript { .api }
11
/**
12
 * Modern asset loading system
13
 */
14
class Assets {
15
    /**
16
     * Load one or more assets
17
     * @param urls - URLs or aliases to load
18
     * @param onProgress - Progress callback
19
     */
20
    static load<T = any>(urls: string | string[], onProgress?: (progress: number) => void): Promise<T>;
21
    
22
    /**
23
     * Load asset bundles
24
     * @param bundleIds - Bundle IDs to load
25
     * @param onProgress - Progress callback
26
     */
27
    static loadBundle<T = any>(bundleIds: string | string[], onProgress?: (progress: number) => void): Promise<T>;
28
    
29
    /**
30
     * Get cached assets
31
     * @param keys - Asset keys/aliases
32
     */
33
    static get<T = any>(keys: string | string[]): T;
34
    
35
    /**
36
     * Unload assets and free memory
37
     * @param urls - URLs or aliases to unload
38
     */
39
    static unload(urls: string | string[]): Promise<void>;
40
    
41
    /**
42
     * Add assets to the resolver
43
     * @param assets - Asset manifest or individual assets
44
     */
45
    static add(assets: string | AssetsManifest | (string | AssetsManifest)[]): void;
46
    
47
    /**
48
     * Initialize the asset system
49
     * @param options - Initialization options
50
     */
51
    static init(options?: AssetsInitOptions): Promise<void>;
52
    
53
    /**
54
     * Set base path for assets
55
     * @param basePath - Base path URL
56
     */
57
    static setBasePath(basePath: string): void;
58
    
59
    /**
60
     * Check if asset is loaded
61
     * @param key - Asset key/alias
62
     */
63
    static has(key: string): boolean;
64
    
65
    /**
66
     * Get resolver instance
67
     */
68
    static get resolver(): Resolver;
69
    
70
    /**
71
     * Get loader instance
72
     */
73
    static get loader(): Loader;
74
    
75
    /**
76
     * Get cache instance
77
     */
78
    static get cache(): Cache;
79
}
80

81
interface AssetsInitOptions {
82
    /** Base path for all assets */
83
    basePath?: string;
84
    /** Asset manifest to load */
85
    manifest?: AssetsManifest;
86
    /** Texture preferences */
87
    texturePreference?: {
88
        /** Preferred resolution */
89
        resolution?: number;
90
        /** Preferred format */
91
        format?: string[];
92
    };
93
    /** Enable detailed loading logs */
94
    verbose?: boolean;
95
}
96
```
97

98
### Asset Manifests and Bundles
99

100
Organize assets into logical bundles for efficient loading.
101

102
```typescript { .api }
103
/**
104
 * Asset manifest for organizing assets and bundles
105
 */
106
interface AssetsManifest {
107
    /** List of asset bundles */
108
    bundles?: AssetsBundle[];
109
    /** Individual assets */
110
    assets?: AssetsManifestEntry[];
111
}
112

113
/**
114
 * Bundle of related assets
115
 */
116
interface AssetsBundle {
117
    /** Bundle identifier */
118
    name: string;
119
    /** Assets in this bundle */
120
    assets: AssetsManifestEntry[];
121
}
122

123
/**
124
 * Individual asset entry
125
 */
126
interface AssetsManifestEntry {
127
    /** Asset alias/key */
128
    alias: string | string[];
129
    /** Asset source URL(s) */
130
    src: string | string[];
131
    /** Additional asset data */
132
    data?: {
133
        /** Tags for filtering */
134
        tags?: string[];
135
        /** Resolution variants */
136
        resolution?: number;
137
        /** Format variants */
138
        format?: string;
139
        /** Load priority */
140
        priority?: number;
141
    };
142
}
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { Assets } from "pixi.js";
149

150
// Simple asset loading
151
const texture = await Assets.load('https://example.com/image.png');
152
const sprite = new Sprite(texture);
153

154
// Load multiple assets
155
const assets = await Assets.load([
156
    'https://example.com/player.png',
157
    'https://example.com/enemy.png',
158
    'https://example.com/background.jpg'
159
]);
160

161
// With progress tracking
162
const textures = await Assets.load(['image1.png', 'image2.png'], (progress) => {
163
    console.log(`Loading progress: ${Math.round(progress * 100)}%`);
164
});
165

166
// Using asset manifest
167
const manifest = {
168
    bundles: [
169
        {
170
            name: 'game-assets',
171
            assets: [
172
                { alias: 'player', src: 'sprites/player.png' },
173
                { alias: 'enemy', src: 'sprites/enemy.png' },
174
                { alias: 'background', src: 'images/bg.jpg' }
175
            ]
176
        },
177
        {
178
            name: 'ui-assets',
179
            assets: [
180
                { alias: 'button', src: 'ui/button.png' },
181
                { alias: 'panel', src: 'ui/panel.png' }
182
            ]
183
        }
184
    ]
185
};
186

187
Assets.add(manifest);
188
await Assets.loadBundle('game-assets');
189

190
// Access loaded assets
191
const playerTexture = Assets.get('player');
192
const enemyTexture = Assets.get('enemy');
193
```
194

195
### Resolver System
196

197
The resolver handles asset URL resolution and format selection.
198

199
```typescript { .api }
200
/**
201
 * Resolves asset URLs and selects appropriate formats
202
 */
203
class Resolver {
204
    /** Base path for all assets */
205
    basePath: string;
206
    
207
    /**
208
     * Add assets to resolver
209
     * @param assets - Assets to add
210
     */
211
    add(assets: string | ResolverManifest | (string | ResolverManifest)[]): void;
212
    
213
    /**
214
     * Resolve asset URL
215
     * @param key - Asset key
216
     */
217
    resolve(key: string): ResolvedAsset;
218
    
219
    /**
220
     * Check if asset exists
221
     * @param key - Asset key
222
     */
223
    hasKey(key: string): boolean;
224
    
225
    /**
226
     * Remove asset from resolver
227
     * @param key - Asset key
228
     */
229
    remove(key: string): void;
230
    
231
    /**
232
     * Set preferences for asset resolution
233
     * @param preferences - Resolution preferences
234
     */
235
    setPreferences(preferences: ResolverPreferences): void;
236
    
237
    /**
238
     * Get all resolved assets
239
     */
240
    getAll(): Record<string, ResolvedAsset>;
241
    
242
    /**
243
     * Reset resolver
244
     */
245
    reset(): void;
246
}
247

248
interface ResolvedAsset {
249
    /** Asset alias */
250
    alias: string[];
251
    /** Resolved URL */
252
    src: string;
253
    /** Asset format */
254
    format: string;
255
    /** Load priority */
256
    priority: number;
257
    /** Additional data */
258
    data: any;
259
}
260

261
interface ResolverPreferences {
262
    /** Preferred resolution */
263
    resolution?: number;
264
    /** Preferred formats in order */
265
    format?: string[];
266
}
267

268
interface ResolverManifest {
269
    [key: string]: string | {
270
        src: string | string[];
271
        format?: string;
272
        resolution?: number;
273
        priority?: number;
274
        data?: any;
275
    };
276
}
277
```
278

279
### Loader System
280

281
The core loading functionality with extensible parsers.
282

283
```typescript { .api }
284
/**
285
 * Core asset loader with parser system
286
 */
287
class Loader extends EventEmitter {
288
    /**
289
     * Load assets
290
     * @param assetsToLoad - Assets to load
291
     * @param onProgress - Progress callback
292
     */
293
    load<T>(assetsToLoad: string | ResolvedAsset | (string | ResolvedAsset)[], onProgress?: (progress: number) => void): Promise<T>;
294
    
295
    /**
296
     * Unload assets
297
     * @param assetsToUnload - Assets to unload
298
     */
299
    unload(assetsToUnload: string | ResolvedAsset | (string | ResolvedAsset)[]): Promise<void>;
300
    
301
    /**
302
     * Add parser for specific asset types
303
     * @param parser - Parser to add
304
     */
305
    static addParser(parser: LoaderParser): void;
306
    
307
    /**
308
     * Remove parser
309
     * @param parser - Parser to remove
310
     */
311
    static removeParser(parser: LoaderParser): void;
312
}
313

314
/**
315
 * Parser interface for handling specific asset types
316
 */
317
interface LoaderParser {
318
    /** Parser name */
319
    name: string;
320
    /** File extensions this parser handles */
321
    extension: string | string[];
322
    /** Test function to determine if parser should handle asset */
323
    test?: (url: string, resolved: ResolvedAsset) => boolean;
324
    /** Load function */
325
    load: (url: string, asset: ResolvedAsset, loader: Loader) => Promise<any>;
326
    /** Unload function */
327
    unload?: (asset: any) => void;
328
}
329
```
330

331
### Cache System
332

333
Asset caching for performance optimization.
334

335
```typescript { .api }
336
/**
337
 * Asset cache for storing loaded assets
338
 */
339
class Cache extends EventEmitter {
340
    /**
341
     * Set asset in cache
342
     * @param key - Cache key
343
     * @param asset - Asset to cache
344
     */
345
    set(key: string, asset: any): void;
346
    
347
    /**
348
     * Get asset from cache
349
     * @param key - Cache key
350
     */
351
    get<T = any>(key: string): T;
352
    
353
    /**
354
     * Check if asset exists in cache
355
     * @param key - Cache key
356
     */
357
    has(key: string): boolean;
358
    
359
    /**
360
     * Remove asset from cache
361
     * @param key - Cache key
362
     */
363
    remove(key: string): boolean;
364
    
365
    /**
366
     * Get all cached assets
367
     */
368
    getAll(): Record<string, any>;
369
    
370
    /**
371
     * Clear all cached assets
372
     */
373
    clear(): void;
374
    
375
    /**
376
     * Get cache keys
377
     */
378
    getKeys(): string[];
379
    
380
    /**
381
     * Reset cache
382
     */
383
    reset(): void;
384
}
385
```
386

387
**Usage Examples:**
388

389
```typescript
390
import { Assets, Cache } from "pixi.js";
391

392
// Cache management
393
const texture = await Assets.load('player.png');
394
console.log(Cache.has('player.png')); // true
395

396
// Manual cache operations
397
Cache.set('custom-data', { score: 100, level: 5 });
398
const gameData = Cache.get('custom-data');
399

400
// Clear specific assets
401
Cache.remove('old-texture');
402

403
// Clear all cache
404
Cache.clear();
405
```
406

407
### Advanced Loading Patterns
408

409
```typescript
410
// Resolution-aware loading
411
Assets.setPreferences({
412
    resolution: window.devicePixelRatio,
413
    format: ['webp', 'png', 'jpg']
414
});
415

416
// Add resolution variants
417
Assets.add({
418
    alias: 'hero',
419
    src: [
420
        'hero@1x.png',
421
        'hero@2x.png',
422
        'hero@3x.png'
423
    ]
424
});
425

426
// Bundle-based loading with dependencies
427
const gameManifest = {
428
    bundles: [
429
        {
430
            name: 'preload',
431
            assets: [
432
                { alias: 'loading-bar', src: 'ui/loading.png' },
433
                { alias: 'logo', src: 'ui/logo.png' }
434
            ]
435
        },
436
        {
437
            name: 'level-1',
438
            assets: [
439
                { alias: 'level1-bg', src: 'levels/level1/bg.jpg' },
440
                { alias: 'level1-tileset', src: 'levels/level1/tiles.png' },
441
                { alias: 'level1-music', src: 'audio/level1.mp3' }
442
            ]
443
        },
444
        {
445
            name: 'characters',
446
            assets: [
447
                { alias: 'player-idle', src: 'sprites/player/idle.json' },
448
                { alias: 'player-run', src: 'sprites/player/run.json' },
449
                { alias: 'enemy-basic', src: 'sprites/enemies/basic.png' }
450
            ]
451
        }
452
    ]
453
};
454

455
// Initialize with manifest
456
await Assets.init({ manifest: gameManifest });
457

458
// Load preload assets first
459
await Assets.loadBundle('preload');
460

461
// Show loading screen, then load game assets
462
const loadingPromises = [
463
    Assets.loadBundle('level-1'),
464
    Assets.loadBundle('characters')
465
];
466

467
await Promise.all(loadingPromises);
468

469
// Assets are now available
470
const playerTexture = Assets.get('player-idle');
471
const backgroundTexture = Assets.get('level1-bg');
472
```
473

474
### Format Support
475

476
PixiJS supports various asset formats through built-in and extensible parsers:
477

478
```typescript
479
// Image formats
480
await Assets.load('image.png');     // PNG
481
await Assets.load('image.jpg');     // JPEG
482
await Assets.load('image.webp');    // WebP
483
await Assets.load('image.svg');     // SVG
484

485
// Spritesheet formats
486
await Assets.load('sprites.json');   // TexturePacker JSON
487
await Assets.load('atlas.xml');      // XML atlas
488

489
// Font formats
490
await Assets.load('font.woff2');     // Web fonts
491
await Assets.load('bitmap-font.fnt'); // Bitmap fonts
492

493
// Audio formats (with additional plugins)
494
await Assets.load('music.mp3');     // MP3
495
await Assets.load('sound.wav');     // WAV
496

497
// Video formats
498
await Assets.load('video.mp4');     // MP4
499
await Assets.load('video.webm');    // WebM
500

501
// JSON data
502
await Assets.load('data.json');     // JSON data
503

504
// Custom formats via parsers
505
Loader.addParser({
506
    name: 'custom-parser',
507
    extension: 'custom',
508
    load: async (url) => {
509
        const response = await fetch(url);
510
        return await response.text();
511
    }
512
});
513
```
514

515
## Performance Best Practices
516

517
```typescript
518
// Preload critical assets
519
const criticalAssets = ['ui-skin', 'player-spritesheet', 'level1-bg'];
520
await Assets.load(criticalAssets);
521

522
// Load bundles progressively
523
await Assets.loadBundle('preload');
524
showLoadingScreen();
525
await Assets.loadBundle('game-core');
526
hideLoadingScreen();
527

528
// Background loading of future content
529
Assets.loadBundle('level-2').then(() => {
530
    console.log('Level 2 assets ready');
531
});
532

533
// Unload unused assets to free memory
534
await Assets.unload(['old-level-assets', 'unused-textures']);
535

536
// Use appropriate formats
537
// - WebP for modern browsers with fallbacks
538
// - Compressed textures for mobile
539
// - Multiple resolutions for different DPI
540
```