Example
import { Assets } from 'pixi.js';
const bunny = await Assets.load('bunny.png');
Members
cache Cache
The global cache of all assets within PixiJS
detections FormatDetectionParser[]
All the detection parsers currently added to the Assets class.
loader Loader
The loader, loads stuff!
resolver Resolver
the resolver to map various urls
Methods
Allows you to specify how to resolve any assets load requests. There are a few ways to add things here as shown below:
Name | Type | Description |
---|---|---|
assets |
(ArrayOr<UnresolvedAsset>) |
the unresolved assets to add to the resolver |
Example
import { Assets } from 'pixi.js';
// Simple
Assets.add({alias: 'bunnyBooBoo', src: 'bunny.png'});
const bunny = await Assets.load('bunnyBooBoo');
// Multiple keys:
Assets.add({alias: ['burger', 'chicken'], src: 'bunny.png'});
const bunny = await Assets.load('burger');
const bunny2 = await Assets.load('chicken');
// passing options to to the object
Assets.add({
alias: 'bunnyBooBooSmooth',
src: 'bunny{png,webp}',
data: { scaleMode: SCALE_MODES.NEAREST }, // Base texture options
});
// Multiple assets
// The following all do the same thing:
Assets.add({alias: 'bunnyBooBoo', src: 'bunny{png,webp}'});
Assets.add({
alias: 'bunnyBooBoo',
src: [
'bunny.png',
'bunny.webp',
],
});
const bunny = await Assets.load('bunnyBooBoo'); // Will try to load WebP if available
This adds a bundle of assets in one go so that you can load them as a group. For example you could add a bundle for each screen in you pixi app
Name | Type | Description |
---|---|---|
bundleId |
string |
the id of the bundle to add |
assets |
AssetsBundle["assets"] |
a record of the asset or assets that will be chosen from when loading via the specified key |
Example
import { Assets } from 'pixi.js';
Assets.addBundle('animals', [
{ alias: 'bunny', src: 'bunny.png' },
{ alias: 'chicken', src: 'chicken.png' },
{ alias: 'thumper', src: 'thumper.png' },
]);
// or
Assets.addBundle('animals', {
bunny: 'bunny.png',
chicken: 'chicken.png',
thumper: 'thumper.png',
});
const assets = await Assets.loadBundle('animals');
Initiate a background load of some assets. It will passively begin to load these assets in the background. So when you actually come to loading them you will get a promise that resolves to the loaded assets immediately
An example of this might be that you would background load game assets after your inital load. then when you got to actually load your game screen assets when a player goes to the game - the loading would already have stared or may even be complete, saving you having to show an interim load bar.
Name | Type | Description |
---|---|---|
urls |
ArrayOr<string> |
the url / urls you want to background load |
Returns:
Type | Description |
---|---|
Promise<void> |
Example
import { Assets } from 'pixi.js';
Assets.backgroundLoad('bunny.png');
// later on in your app...
await Assets.loadBundle('bunny.png'); // Will resolve quicker as loading may have completed!
Initiate a background of a bundle, works exactly like backgroundLoad but for bundles. this can only be used if the loader has been initiated with a manifest
Name | Type | Description |
---|---|---|
bundleIds |
ArrayOr<string> |
the bundleId / bundleIds you want to background load |
Returns:
Type | Description |
---|---|
Promise<void> |
Example
import { Assets } from 'pixi.js';
await Assets.init({
manifest: {
bundles: [
{
name: 'load-screen',
assets: [...],
},
...
],
},
});
Assets.backgroundLoadBundle('load-screen');
// Later on in your app...
await Assets.loadBundle('load-screen'); // Will resolve quicker as loading may have completed!
Instantly gets an asset already loaded from the cache. If the asset has not yet been loaded,
it will return undefined. So it's on you! When in doubt just use Assets.load
instead.
(Remember, the loader will never load things more than once!)
Name | Type | Description |
---|---|---|
keys |
ArrayOr<string> |
The key or keys for the assets that you want to access |
Returns:
Type | Description |
---|---|
T | T<string, Record> |
|
Best practice is to call this function before any loading commences Initiating is the best time to add any customization to the way things are loaded.
you do not need to call this for the Assets class to work, only if you want to set any initial properties
Name | Type | Description |
---|---|---|
options |
AssetInitOptions |
options to initialize the Assets manager with |
Returns:
Type | Description |
---|---|
Promise<void> |
Loads your assets! You pass in a key or URL and it will return a promise that resolves to the loaded asset. If multiple assets a requested, it will return a hash of assets.
Don't worry about loading things multiple times, behind the scenes assets are only ever loaded once and the same promise reused behind the scenes so you can safely call this function multiple times with the same key and it will always return the same asset.
Name | Type | Attributes | Description |
---|---|---|---|
urls |
ArrayOr<string> | UnresolvedAsset<ArrayOr> |
the urls to load |
|
onProgress |
ProgressCallback |
<optional> |
optional function that is called when progress on asset loading is made.
The function is passed a single parameter, |
Returns:
Type | Description |
---|---|
Promise<T | Record<string, T>> |
|
Example
import { Assets } from 'pixi.js';
// Load a URL:
const myImageTexture = await Assets.load('http://some.url.com/image.png'); // => returns a texture
Assets.add('thumper', 'bunny.png');
Assets.add('chicko', 'chicken.png');
// Load multiple assets:
const textures = await Assets.load(['thumper', 'chicko']); // => {thumper: Texture, chicko: Texture}
Bundles are a way to load multiple assets at once.
If a manifest has been provided to the init function then you can load a bundle, or bundles.
you can also add bundles via addBundle
Name | Type | Attributes | Description |
---|---|---|---|
bundleIds |
ArrayOr<string> |
the bundle id or ids to load |
|
onProgress |
ProgressCallback |
<optional> |
Optional function that is called when progress on asset loading is made.
The function is passed a single parameter, |
Returns:
Type | Description |
---|---|
Promise<any> | all the bundles assets or a hash of assets for each bundle specified |
Example
import { Assets } from 'pixi.js';
// Manifest Example
const manifest = {
bundles: [
{
name: 'load-screen',
assets: [
{
alias: 'background',
src: 'sunset.png',
},
{
alias: 'bar',
src: 'load-bar.{png,webp}',
},
],
},
{
name: 'game-screen',
assets: [
{
alias: 'character',
src: 'robot.png',
},
{
alias: 'enemy',
src: 'bad-guy.png',
},
],
},
]
};
await Assets.init({ manifest });
// Load a bundle...
loadScreenAssets = await Assets.loadBundle('load-screen');
// Load another bundle...
gameScreenAssets = await Assets.loadBundle('game-screen');
Only intended for development purposes. This will wipe the resolver and caches. You will need to reinitialize the Asset
General setter for preferences. This is a helper function to set preferences on all parsers.
Name | Type | Description |
---|---|---|
preferences |
Partial<AssetsPreferences> |
the preferences to set |
Unload an asset or assets. As the Assets class is responsible for creating the assets via the load
function
this will make sure to destroy any assets and release them from memory.
Once unloaded, you will need to load the asset again.
Use this to help manage assets if you find that you have a large app and you want to free up memory.
- it's up to you as the developer to make sure that textures are not actively being used when you unload them, Pixi won't break but you will end up with missing assets. Not a good look for the user!
Name | Type | Description |
---|---|---|
urls |
ArrayOr<string> | ResolvedAsset | ResolvedAsset[] |
the urls to unload |
Returns:
Type | Description |
---|---|
Promise<void> |
Example
import { Assets } from 'pixi.js';
// Load a URL:
const myImageTexture = await Assets.load('http://some.url.com/image.png'); // => returns a texture
await Assets.unload('http://some.url.com/image.png')
// myImageTexture will be destroyed now.
// Unload multiple assets:
const textures = await Assets.unload(['thumper', 'chicko']);
Bundles are a way to manage multiple assets at once. this will unload all files in a bundle.
once a bundle has been unloaded, you need to load it again to have access to the assets.
Name | Type | Description |
---|---|---|
bundleIds |
ArrayOr<string> |
the bundle id or ids to unload |
Returns:
Type | Description |
---|---|
Promise<void> |
Example
import { Assets } from 'pixi.js';
Assets.addBundle({
'thumper': 'http://some.url.com/thumper.png',
})
const assets = await Assets.loadBundle('thumper');
// Now to unload...
await Assets.unloadBundle('thumper');
// All assets in the assets object will now have been destroyed and purged from the cache