pixijs-assets

The `Assets` API is PixiJS's asset loader, resolver, and cache in one singleton. Use it to load textures, video, spritesheets, fonts, JSON, and other resources with format detection, resolution switching, bundle grouping, progress tracking, and GPU cleanup. ## Quick Start ```ts await Assets.init({ basePath: "/static/" }); const texture = await Assets.load("bunny.png"); const sprite = new Sprite(texture); app.stage.addChild(sprite); const [hero, enemy] = await Assets.load(["hero.png", "enemy.png"]); await Assets.load({ alias: "logo", src: "logo.webp", }); const logo = new Sprite(Assets.get("logo")); ``` `Assets.init()` is optional but recommended for setting `basePath`, `texturePreference`, or a manifest. After init, call `Assets.load()` with a URL, alias, array, or `UnresolvedAsset`; resolved assets are cached and re-resolved by `Assets.get()`. ## Supported file types | Type | Extensions | Parser ID | Loader | | ------------------- | ---------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Textures | `.png`, `.jpg`, `.jpeg`, `.webp`, `.avif` | `texture` | `loadTextures` | | SVG | `.svg` | `svg` | `loadSvg` (see `references/svg.md`) | | Video textures | `.mp4`, `.m4v`, `.webm`, `.ogg`, `.ogv`, `.h264`, `.avi`, `.mov` | `video` | `loadVideoTextures` (see `references/video.md`) | | Sprite sheets | `.json` (Spritesheet format) | `spritesheet` | `spritesheetAsset` (see `references/spritesheet.md`) | | Bitmap fonts | `.fnt`, `.xml` | `bitmap-font` | `loadBitmapFont` (loading works by default; rendering `BitmapText` requires `'pixi.js/text-bitmap'`; see `references/fonts.md`) | | Web fonts | `.ttf`, `.otf`, `.woff`, `.woff2` | `web-font` | `loadWebFont` (see `references/fonts.md`) | | JSON | `.json` | `json` | `loadJson` | | Text | `.txt` | `text` | `loadTxt` | | Compressed textures | `.basis`, `.dds`, `.ktx`, `.ktx2` | `basis`, `dds`, `ktx`, `ktx2` | See `references/compressed-textures.md` | | Animated GIFs | `.gif` | `gif` | Requires `'pixi.js/gif'`; returns `GifSource` (see `references/gif.md`) | The **Parser ID** column is the value you pass to the top-level `parser` field on an asset descriptor to force a specific loader. See "Forcing a parser" below. ## Forcing a parser with `parser` By default, PixiJS picks a loader by matching the file extension or MIME type. When your URL lacks an extension (CDN signed URLs, blob URLs, API endpoints, content-hashed paths), the resolver can't tell the loader what to do. Set the top-level `parser` field on the asset descriptor to force a specific loader: ```ts // Signed CDN URL with no extension const texture = await Assets.load({ src: "https://cdn.example.com/signed/abc123?token=xyz", parser: "texture", }); // API endpoint that returns JSON const data = await Assets.load({ alias: "config", src: "https://api.example.com/v1/config", parser: "json", }); // Extension-less font URL with explicit family await Assets.load({ src: "https://cdn.example.com/fonts/hero-v2", parser: "web-font", data: { family: "Hero", weights: ["400", "700"] }, }); // Video stream without a file extension const clipTexture = await Assets.load({ src: "https://cdn.example.com/stream/xyz", parser: "video", data: { mime: "video/mp4", muted: true, playsinline: true }, }); ``` The `parser` field goes at the top level of the asset descriptor (alongside `src` and `data`), not inside `data`. It takes any parser ID from the "Supported file types" table above: - `'texture'`, `'svg'`, `'video'`: image, SVG, and video textures - `'json'`, `'text'`: JSON and plain text - `'web-font'`, `'bitmap-font'`: web and bitmap fonts - `'spritesheet'`: texture atlas JSON - `'gif'`: animated GIFs (requires `'pixi.js/gif'`) - `'basis'`, `'dds'`, `'ktx'`, `'ktx2'`: compressed textures (each requires its side-effect import) ### When you need it - **Signed CDN URLs**: `https://cdn.example.com/get?id=abc123` has no extension the loader can test against. - **Blob or ObjectURL**: `URL.createObjectURL(blob)` produces `blob:...` URLs with no extension. - **Custom routing**: `/api/assets/hero-v2` where the server decides the content type. - **Content-hashed paths without suffix**: some build pipelines produce names like `/static/abc123def` instead of `/static/abc123def.png`. If the URL _does_ have an extension, you don't need `parser`; let auto-detection do its job. Only set `parser` when detection can't work. ### `loadParser` is deprecated The v7 `loadParser` field still works but emits a deprecation warning. Use `parser` for new code. ```ts // Old (deprecated) await Assets.load({ src: "...", loadParser: "loadTextures" }); // New await Assets.load({ src: "...", parser: "texture" }); ``` ## Topics Every asset workflow is covered in a reference file. Pick the one that matches the question: | Topic | Reference | When | | ------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------- | | Texture atlases and animations | [references/spritesheet.md](references/spritesheet.md) | Loading sprite sheets with `AnimatedSprite` | | Video textures | [references/video.md](references/video.md) | `.mp4`, `.webm`, autoplay, looping, mobile | | Web and bitmap fonts | [references/fonts.md](references/fonts.md) | `.woff2`, `.fnt`, font families, SDF fonts | | Animated GIFs | [references/gif.md](references/gif.md) | `.gif`, `GifSprite`, playback control | | Grouping assets by feature | [references/bundles.md](references/bundles.md) | `addBundle`, `loadBundle`, `unloadBundle` | | Declaring everything upfront | [references/manifests.md](references/manifests.md) | `Assets.init({ manifest })` workflows | | Cache lookups and cleanup | [references/caching.md](references/caching.md) | `Assets.get`, `Assets.unload`, `Cache` | | Priming future assets | [references/background.md](references/background.md) | `backgroundLoad`, `backgroundLoadBundle` | | Loading screens | [references/progress.md](references/progress.md) | `onProgress`, LoadOptions progress | | GPU-compressed formats | [references/compressed-textures.md](references/compressed-textures.md) | `.ktx2`, `.basis`, `.dds`, `.ktx` | | Vector vs raster SVG | [references/svg.md](references/svg.md) | `parseAsGraphicsContext`, texture mode | | Retina + format detection | [references/resolution.md](references/resolution.md) | `@{1,2}x`, `format` preferences | ## Decision guide - **Need to load a single image?** Use `Assets.load(url)`. No setup required. - **Loading many assets grouped by level/scene?** Use a bundle. See `references/bundles.md`. - **Know all assets at build time?** Use a manifest in `Assets.init`. See `references/manifests.md`. - **Need a loading bar?** Pass a progress callback to `Assets.load`. See `references/progress.md`. - **Smooth transitions between levels?** Background-load the next level. See `references/background.md`. - **Memory budget matters?** Use compressed textures and `Assets.unload` between screens. See `references/compressed-textures.md` and `references/caching.md`. - **Need crisp SVG icons at any size?** Load as Graphics, not texture. See `references/svg.md`. - **Retina + WebP/AVIF?** Configure `texturePreference` and use format patterns. See `references/resolution.md`. ## Load options and error handling There are two separate "options" concepts when loading assets: 1. **`LoadOptions`**: the second argument to `Assets.load`/`loadBundle`. Controls error recovery, retries, progress, and completion callbacks across a whole load. 2. **`data`**: a field on each asset descriptor. Forwards parser-specific options (scale mode, resolution, font family, autoplay flags, etc.) to the specific loader for that asset. ### LoadOptions (per call) ```ts await Assets.load(["hero.png", "enemy.png"], { onProgress: (p) => updateBar(p), onError: (err, url) => { const src = typeof url === "string" ? url : url.src; console.warn("failed:", src, err); }, strategy: "retry", retryCount: 3, retryDelay: 250, }); ``` - `onProgress(progress)`: `[0, 1]` as assets in the call complete. - `onError(error, url)`: `url` is `string | ResolvedAsset`. Guard before reading `.src`; when `url` is a string, `.src` is undefined. - `strategy: 'throw' | 'skip' | 'retry'` — default `'throw'`. `'skip'` resolves with any successful assets; `'retry'` reattempts the failed ones. - `retryCount` — default `3`, retries per asset when `strategy` is `'retry'`. - `retryDelay` — default `250` ms between retries. Global defaults live on `Loader.defaultOptions`, or pass `loadOptions` to `Assets.init()`. ### `data` options (per asset) Each loader parser reads its own options from the `data` field on the asset descriptor. Use the table below to pick the right options for each asset type: | Asset type | `data` shape | Key options | Reference |