Background Loading

Background loading lets PixiJS fetch and prepare assets passively while other work happens. Use it to prime the next level while the current one is playing, preload assets during a splash screen, or prepare UI assets during initial load. backgroundLoad and backgroundLoadBundle are non-blocking and return immediately.

Quick Start

await Assets.loadBundle("menu");
showMenu();

Assets.backgroundLoadBundle("level1");

playerClicksStart(() => {
  Assets.loadBundle("level1").then(() => startLevel());
});

The backgroundLoadBundle call starts loading level1 immediately without blocking. The later loadBundle call resolves quickly if background loading finished in the meantime.

Core Patterns

Background-loading a single asset

Assets.backgroundLoad("images/level2-assets.png");

// later, when we need it:
const texture = await Assets.load("images/level2-assets.png");

Fire-and-forget. Background loading happens one asset at a time to avoid blocking the main thread. When your code later calls Assets.load(url) for the same asset, it either resolves immediately (if background work finished) or waits for the already-in-progress load.

Background-loading an array

Assets.backgroundLoad([
  "images/sprite1.png",
  "images/sprite2.png",
  "images/background.png",
]);

Queues multiple assets for background loading. They're processed sequentially.

Background-loading a bundle

await Assets.init({
  manifest: {
    bundles: [
      { name: "home", assets: [{ alias: "bg", src: "home-bg.png" }] },
      { name: "level-1", assets: [{ alias: "map", src: "level1-map.json" }] },
    ],
  },
});

await Assets.loadBundle("home");
showHome();

Assets.backgroundLoadBundle("level-1");

onPlayClicked(async () => {
  await Assets.loadBundle("level-1");
  startLevel();
});

Same idea for bundles. Bundle assets are queued one at a time. Requires the bundle to exist via the manifest or addBundle.

Interrupting background loading

Assets.backgroundLoadBundle("level-2");

onPlayerDecidedLevel3(async () => {
  await Assets.loadBundle("level-3");
});

Calling Assets.load() or Assets.loadBundle() interrupts background loading safely. The current background asset finishes, then the explicit load takes priority. Your explicit load resolves normally.

Combining with a progress bar

Background loading has no progress callback; it runs silently. To show a loading bar, use Assets.loadBundle(name, onProgress) in the foreground instead. Typical pattern: use background loading for nice-to-have preloads and foreground loading for the bundles you're actually waiting on.

Common Mistakes

[HIGH] Expecting progress from background loading

Wrong:

Assets.backgroundLoadBundle("level2", (p) => updateBar(p));

Correct:

Assets.backgroundLoadBundle("level2");
// show a spinner or no UI while it runs

backgroundLoad and backgroundLoadBundle don't accept progress callbacks. They're silent. For visible progress, use the foreground Assets.load / Assets.loadBundle with an onProgress argument.

[MEDIUM] Assuming background load completes before next foreground load

Wrong:

Assets.backgroundLoadBundle("level-2");
setTimeout(() => startLevel2(), 0);

Correct:

Assets.backgroundLoadBundle("level-2");

onStart(async () => {
  await Assets.loadBundle("level-2");
  startLevel2();
});

Background loading is best-effort. If the player hits Start before it finishes, the foreground loadBundle still needs to await the remaining work. Always await the real load before using the assets.

[MEDIUM] Background-loading assets that are never used

Each queued background load consumes bandwidth and GPU memory. If the player never visits level 2, you've wasted that bandwidth. Background-load only what you're confident will be needed soon.

API Reference

• Assets
• BackgroundLoader