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

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:

// 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.

// 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	Loading sprite sheets with `AnimatedSprite`
Video textures	references/video.md	`.mp4` , `.webm` , autoplay, looping, mobile
Web and bitmap fonts	references/fonts.md	`.woff2` , `.fnt` , font families, SDF fonts
Animated GIFs	references/gif.md	`.gif` , `GifSprite` , playback control
Grouping assets by feature	references/bundles.md	`addBundle` , `loadBundle` , `unloadBundle`
Declaring everything upfront	references/manifests.md	`Assets.init({ manifest })` workflows
Cache lookups and cleanup	references/caching.md	`Assets.get` , `Assets.unload` , `Cache`
Priming future assets	references/background.md	`backgroundLoad` , `backgroundLoadBundle`
Loading screens	references/progress.md	`onProgress` , LoadOptions progress
GPU-compressed formats	references/compressed-textures.md	`.ktx2` , `.basis` , `.dds` , `.ktx`
Vector vs raster SVG	references/svg.md	`parseAsGraphicsContext` , texture mode
Retina + format detection	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:

LoadOptions
: the second argument to
```
Assets.load
```
/
```
loadBundle
```
. Controls error recovery, retries, progress, and completion callbacks across a whole load.
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)

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

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
Texture (image)	`TextureSourceOptions`	`resolution` , `scaleMode` , `alphaMode` , `autoGenerateMipmaps` , `antialias` , `addressMode`	`references/resolution.md`
SVG	`{ parseAsGraphicsContext?, resolution? }`	`parseAsGraphicsContext` for Graphics mode; `resolution` for sharper raster	`references/svg.md`
Video	`VideoSourceOptions`	`autoPlay` , `loop` , `muted` , `playsinline` , `preload` , `updateFPS` , `crossorigin` , `mime`	`references/video.md`
Web font	`LoadFontData`	`family` , `weights` , `style` , `display` , `unicodeRange` , `featureSettings`	`references/fonts.md`
Bitmap font	(none; auto-configured)	Distance-field detection sets scale mode and mipmaps	`references/fonts.md`
Spritesheet	`{ texture?, imageFilename?, ignoreMultiPack?, textureOptions?, cachePrefix? }`	`textureOptions` forwards `TextureSourceOptions` (e.g. `scaleMode` ) to the atlas image; `texture` to skip image load; `imageFilename` to override the referenced image; `ignoreMultiPack` to skip multi-pack follow-ups; `cachePrefix` to namespace frames	`references/spritesheet.md`
GIF	`GifBufferOptions`	`fps` , `scaleMode` , `resolution` , `autoGenerateMipmaps`	`references/gif.md`
Compressed texture	`TextureSourceOptions`	`scaleMode` , `addressMode` , `autoGenerateMipmaps`	`references/compressed-textures.md`
JSON / Text	(none)	Returned as-is	—

Example combining

LoadOptions

and

data

await Assets.load(
  {
    alias: "hero",
    src: "hero.png",
    data: { scaleMode: "nearest", resolution: 2 },
  },
  { strategy: "retry", retryCount: 3 },
);

Inside a manifest or bundle, every entry can carry its own

data

await Assets.init({
  manifest: {
    bundles: [
      {
        name: "level1",
        assets: [
          { alias: "tiles", src: "tiles.png", data: { scaleMode: "nearest" } },
          { alias: "font", src: "hero.woff2", data: { family: "Hero" } },
          {
            alias: "clip",
            src: "intro.mp4",
            data: { autoPlay: false, muted: true },
          },
        ],
      },
    ],
  },
});

Runtime configuration

Assets.init(options)

accepts, alongside

basePath

and

manifest

```
defaultSearchParams
```
— string or
```
Record<string, any>
```
appended to every resolved URL. Useful for cache busting.
```
skipDetections: boolean
```
— bypass browser format detection for faster init. Requires explicit
```
texturePreference.format
```
.
```
bundleIdentifier: BundleIdentifierOptions
```
— customize how bundle keys resolve so the same alias can live in multiple bundles.

loadOptions: Partial<LoadOptions>

— set the default

strategy

retryCount

retryDelay

, and callbacks for every subsequent

Assets.load

call.

preferences: Partial<AssetsPreferences>

—

crossOrigin

preferWorkers

preferCreateImageBitmap

parseAsGraphicsContext

After init, preferences can still be tuned:

Assets.setPreferences({
  crossOrigin: "anonymous",
  preferCreateImageBitmap: false,
});

for (const detection of Assets.detections) {
  console.log(detection.extension);
}

Assets.reset();

```
Assets.setPreferences(preferences)
```
— push new preferences to every parser that supports them.
```
Assets.detections
```
— getter exposing the registered
```
FormatDetectionParser
```
list; use when inspecting what formats the current environment advertises.
```
Assets.reset()
```
— internal full reset (resolver + loader + cache). Intended for tests so a fresh
```
Assets.init
```
can run.

Common Mistakes

[CRITICAL] Using

Texture.from(url)

to load

Wrong:

const texture = Texture.from("https://example.com/image.png");

Correct:

const texture = await Assets.load("https://example.com/image.png");

In v8,

Texture.from()

only reads the cache. It does not fetch from a URL. Use

Assets.load()

first; the return value is the texture itself.

[HIGH] Using positional

Assets.add

signature

Wrong:

Assets.add("bunny", "bunny.png");

Correct:

Assets.add({ alias: "bunny", src: "bunny.png" });

The positional

Assets.add(key, url)

form was removed in v8. Use the options object with

alias

and

src

properties.

[HIGH] Not unloading textures between levels

Assets.load()

caches textures indefinitely. For level-based games or screens with distinct asset sets, call

Assets.unloadBundle()

when transitioning to release GPU memory.

pixijs-assets

NPX Install

Tags

SKILL.md Content

Quick Start

Supported file types

Forcing a parser with
`parser`

When you need it

`loadParser`
is deprecated

Topics

Decision guide

Load options and error handling

LoadOptions (per call)

`data`
options (per asset)

Runtime configuration

Common Mistakes

[CRITICAL] Using
`Texture.from(url)`
to load

[HIGH] Using positional
`Assets.add`
signature

[HIGH] Not unloading textures between levels

API Reference