0
# Asset Loading and Management
1

2
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.
3

4
## Capabilities
5

6
### Assets Class
7

8
Main static class for asset management providing a simple interface for loading, caching, and resolving assets.
9

10
```typescript { .api }
11
/**
12
 * Main assets management class
13
 */
14
class Assets {
15
  /**
16
   * Load assets by URL or alias
17
   * @param urls - URLs or aliases to load
18
   * @param onProgress - Progress callback
19
   * @returns Promise resolving to loaded assets
20
   */
21
  static load<T = any>(urls: string | string[], onProgress?: ProgressCallback): Promise<T>;
22
  
23
  /**
24
   * Add assets to the resolver
25
   * @param assets - Asset configurations to add
26
   */
27
  static add(assets: string | AssetInitOptions | (string | AssetInitOptions)[]): void;
28
  
29
  /**
30
   * Get cached asset by key
31
   * @param keys - Asset keys to retrieve
32
   * @returns Cached asset(s)
33
   */
34
  static get<T = any>(keys: string | string[]): T;
35
  
36
  /**
37
   * Check if asset exists in cache
38
   * @param key - Asset key to check
39
   * @returns True if asset exists
40
   */
41
  static has(key: string): boolean;
42
  
43
  /**
44
   * Unload assets and remove from cache
45
   * @param urls - URLs or aliases to unload
46
   * @returns Promise resolving when unloaded
47
   */
48
  static unload(urls: string | string[]): Promise<void>;
49
  
50
  /**
51
   * Initialize assets system
52
   * @param options - Initialization options
53
   * @returns Promise resolving when initialized
54
   */
55
  static init(options?: AssetsInitOptions): Promise<void>;
56
  
57
  /** Asset cache system */
58
  static readonly cache: Cache;
59
  
60
  /** Asset URL resolver */
61
  static readonly resolver: Resolver;
62
  
63
  /** Asset loader */
64
  static readonly loader: Loader;
65
  
66
  /**
67
   * Set base URL for all assets
68
   * @param url - Base URL
69
   */
70
  static setBaseUrl(url: string): void;
71
  
72
  /**
73
   * Reset assets system
74
   */
75
  static reset(): void;
76
}
77
```
78

79
### Asset Configuration
80

81
Configuration objects for adding assets to the system.
82

83
```typescript { .api }
84
interface AssetInitOptions {
85
  /** Asset alias */
86
  alias?: string | string[];
87
  
88
  /** Asset URL */
89
  src: string | string[];
90
  
91
  /** Asset data */
92
  data?: any;
93
  
94
  /** Asset format */
95
  format?: string;
96
  
97
  /** Load parser */
98
  loadParser?: string;
99
  
100
  /** Cache parser */
101
  cacheParser?: string;
102
}
103

104
interface AssetsInitOptions {
105
  /** Base URL for assets */
106
  basePath?: string;
107
  
108
  /** Default search parameters */
109
  defaultSearchParams?: Record<string, string>;
110
  
111
  /** Prefer worker loading */
112
  preferWorkers?: boolean;
113
  
114
  /** Manifest URL */
115
  manifest?: string;
116
  
117
  /** Asset bundles */
118
  bundles?: BundleIdentifierOptions[];
119
}
120

121
interface BundleIdentifierOptions {
122
  /** Bundle name */
123
  name: string;
124
  
125
  /** Assets in bundle */
126
  assets: AssetInitOptions[];
127
}
128
```
129

130
### Loader
131

132
Asset loading system with queue management and progress tracking.
133

134
```typescript { .api }
135
/**
136
 * Asset loader with queue management
137
 */
138
class Loader {
139
  constructor();
140
  
141
  /**
142
   * Add assets to load queue
143
   * @param assetsToLoad - Assets to add
144
   * @returns This loader
145
   */
146
  add(assetsToLoad: string | LoadAsset | (string | LoadAsset)[]): this;
147
  
148
  /**
149
   * Load all queued assets
150
   * @param onProgress - Progress callback
151
   * @returns Promise resolving to loaded assets
152
   */
153
  load<T>(onProgress?: ProgressCallback): Promise<T>;
154
  
155
  /**
156
   * Load assets by URLs
157
   * @param urls - URLs to load
158
   * @param onProgress - Progress callback
159
   * @returns Promise resolving to loaded assets
160
   */
161
  load<T>(urls: string | string[], onProgress?: ProgressCallback): Promise<T>;
162
  
163
  /**
164
   * Reset loader state
165
   * @returns This loader
166
   */
167
  reset(): this;
168
  
169
  /**
170
   * Get loading progress
171
   * @returns Progress percentage (0-1)
172
   */
173
  get progress(): number;
174
  
175
  /** Currently loading flag */
176
  readonly loading: boolean;
177
  
178
  /** Number of assets to load */
179
  readonly totalToLoad: number;
180
}
181

182
interface LoadAsset {
183
  /** Asset alias */
184
  alias?: string[];
185
  
186
  /** Asset URL */
187
  src: string;
188
  
189
  /** Loading data */
190
  data?: any;
191
  
192
  /** Load parser to use */
193
  loadParser?: string;
194
}
195

196
type ProgressCallback = (progress: number) => void;
197
```
198

199
### Resolver
200

201
URL resolution system for asset aliases and bundles.
202

203
```typescript { .api }
204
/**
205
 * Asset URL resolver
206
 */
207
class Resolver {
208
  constructor();
209
  
210
  /**
211
   * Add asset configurations
212
   * @param assets - Assets to add
213
   */
214
  add(assets: string | ResolveAsset | (string | ResolveAsset)[]): void;
215
  
216
  /**
217
   * Resolve URL from alias
218
   * @param key - Asset key or alias
219
   * @returns Resolved URL(s)
220
   */
221
  resolveUrl(key: string): string | string[];
222
  
223
  /**
224
   * Resolve asset configuration
225
   * @param key - Asset key
226
   * @returns Resolved asset configuration
227
   */
228
  resolve(key: string): ResolveAsset;
229
  
230
  /**
231
   * Check if key exists
232
   * @param key - Asset key
233
   * @returns True if exists
234
   */
235
  hasKey(key: string): boolean;
236
  
237
  /**
238
   * Remove asset from resolver
239
   * @param key - Asset key to remove
240
   */
241
  remove(key: string): void;
242
  
243
  /**
244
   * Add bundle of assets
245
   * @param bundleId - Bundle identifier
246
   * @param assets - Assets in bundle
247
   */
248
  addBundle(bundleId: string, assets: ResolveAsset[]): void;
249
  
250
  /**
251
   * Remove bundle
252
   * @param bundleId - Bundle identifier
253
   */
254
  removeBundle(bundleId: string): void;
255
  
256
  /**
257
   * Get bundle asset keys
258
   * @param bundleId - Bundle identifier
259
   * @returns Asset keys in bundle
260
   */
261
  resolveBundle(bundleId: string): string[];
262
  
263
  /**
264
   * Set base URL
265
   * @param url - Base URL
266
   */
267
  setBaseUrl(url: string): void;
268
  
269
  /**
270
   * Reset resolver
271
   */
272
  reset(): void;
273
}
274

275
interface ResolveAsset {
276
  /** Asset alias */
277
  alias?: string[];
278
  
279
  /** Asset URL */
280
  src: string;
281
  
282
  /** Asset format */
283
  format?: string;
284
  
285
  /** Asset data */
286
  data?: any;
287
}
288
```
289

290
### Cache
291

292
Asset caching system for storing loaded assets.
293

294
```typescript { .api }
295
/**
296
 * Asset cache system
297
 */
298
class Cache {
299
  constructor();
300
  
301
  /**
302
   * Set cached asset
303
   * @param key - Asset key
304
   * @param asset - Asset to cache
305
   */
306
  set<T>(key: string, asset: T): void;
307
  
308
  /**
309
   * Get cached asset
310
   * @param key - Asset key
311
   * @returns Cached asset
312
   */
313
  get<T>(key: string): T;
314
  
315
  /**
316
   * Check if asset is cached
317
   * @param key - Asset key
318
   * @returns True if cached
319
   */
320
  has(key: string): boolean;
321
  
322
  /**
323
   * Remove asset from cache
324
   * @param key - Asset key
325
   */
326
  remove(key: string): void;
327
  
328
  /**
329
   * Clear all cached assets
330
   */
331
  reset(): void;
332
  
333
  /** All cached keys */
334
  readonly keys: string[];
335
}
336
```
337

338
### Asset Parsers
339

340
Parsers for different asset types and formats.
341

342
```typescript { .api }
343
/**
344
 * Asset parser interface
345
 */
346
interface LoaderParser<ASSET = any, META_DATA = any> {
347
  /** Parser name */
348
  name?: string;
349
  
350
  /** Supported extensions */
351
  extension: string | string[];
352
  
353
  /** Test if parser can handle asset */
354
  test?: (url: string, options?: LoadAsset) => boolean;
355
  
356
  /** Load asset */
357
  load?: (url: string, asset: LoadAsset, loader: Loader) => Promise<ASSET>;
358
  
359
  /** Unload asset */
360
  unload?: (asset: ASSET, resolvedAsset?: ResolveAsset) => void | Promise<void>;
361
}
362

363
/**
364
 * Texture loader parser
365
 */
366
const loadTextures: LoaderParser;
367

368
/**
369
 * JSON loader parser  
370
 */
371
const loadJson: LoaderParser;
372

373
/**
374
 * Web font loader parser
375
 */
376
const loadWebFont: LoaderParser;
377

378
/**
379
 * SVG loader parser
380
 */
381
const loadSVG: LoaderParser;
382

383
/**
384
 * Video texture loader parser
385
 */
386
const loadVideoTextures: LoaderParser;
387
```
388

389
### Background Loading
390

391
Background asset loading system for preloading assets.
392

393
```typescript { .api }
394
/**
395
 * Background loader for preloading assets
396
 */
397
class BackgroundLoader {
398
  constructor(loader: Loader);
399
  
400
  /**
401
   * Add assets to background load queue
402
   * @param urls - URLs to load in background
403
   */
404
  add(urls: string | string[]): void;
405
  
406
  /**
407
   * Start background loading
408
   */
409
  start(): void;
410
  
411
  /**
412
   * Stop background loading
413
   */
414
  stop(): void;
415
  
416
  /** Is currently loading */
417
  readonly active: boolean;
418
}
419
```
420

421
**Usage Examples:**
422

423
```typescript
424
import { Assets, Texture, Sprite } from 'pixi.js';
425

426
// Basic asset loading
427
const texture = await Assets.load('character.png');
428
const sprite = new Sprite(texture);
429

430
// Multiple assets
431
const assets = await Assets.load([
432
  'background.jpg',
433
  'character.png',
434
  'music.mp3'
435
]);
436

437
// Using aliases
438
Assets.add([
439
  { alias: 'hero', src: 'characters/hero.png' },
440
  { alias: 'villain', src: 'characters/villain.png' },
441
  { alias: 'bgm', src: 'audio/background.mp3' }
442
]);
443

444
const heroTexture = await Assets.load('hero');
445
const villain = await Assets.load('villain');
446

447
// Progress tracking
448
const manifest = await Assets.load({
449
  alias: 'gameAssets',
450
  src: [
451
    'level1/background.jpg',
452
    'level1/tiles.png',
453
    'level1/enemies.json',
454
    'level1/music.mp3'
455
  ]
456
}, (progress) => {
457
  console.log(`Loading: ${Math.round(progress * 100)}%`);
458
});
459

460
// Bundle loading
461
Assets.addBundle('level1', [
462
  { alias: 'bg', src: 'level1/bg.jpg' },
463
  { alias: 'tiles', src: 'level1/tiles.png' },
464
  { alias: 'config', src: 'level1/config.json' }
465
]);
466

467
const level1Assets = await Assets.loadBundle('level1');
468

469
// Preloading with background loader
470
Assets.backgroundLoad([
471
  'level2/background.jpg',
472
  'level2/enemies.png',
473
  'level3/background.jpg'
474
]);
475

476
// Custom asset types
477
Assets.add({
478
  alias: 'gameData',
479
  src: 'data/game.json',
480
  data: { parseAsGameConfig: true }
481
});
482

483
// Unloading assets
484
await Assets.unload(['level1', 'unused-texture.png']);
485

486
// Cache management
487
const cachedTexture = Assets.get('hero');
488
if (Assets.has('hero')) {
489
  console.log('Hero texture is cached');
490
}
491

492
// Web fonts
493
Assets.add({
494
  alias: 'gameFont',
495
  src: 'fonts/GameFont.woff2',
496
  data: { family: 'GameFont' }
497
});
498
await Assets.load('gameFont');
499

500
// Video textures
501
const videoTexture = await Assets.load('intro-video.mp4');
502
const videoSprite = new Sprite(videoTexture);
503
```