import { convertToList, isSingleItem, makeAbsoluteUrl } from '../utils';
import type { LoaderParser } from './parsers/LoaderParser';
import type { PromiseAndParser, LoadAsset } from './types';
/**
* The Loader is responsible for loading all assets, such as images, spritesheets, audio files, etc.
* It does not do anything clever with URLs - it just loads stuff!
* Behind the scenes all things are cached using promises. This means it's impossible to load an asset more than once.
* Through the use of LoaderParsers, the loader can understand how to load any kind of file!
*
* It is not intended that this class is created by developers - its part of the Asset class
* This is the second major system of PixiJS' main Assets class
* @memberof PIXI
* @class AssetLoader
*/
export class Loader
{
private _parsers: LoaderParser[] = [];
/** Cache loading promises that ae currently active */
public promiseCache: Record<string, PromiseAndParser> = {};
/** function used for testing */
public reset(): void
{
this.promiseCache = {};
}
/**
* Used internally to generate a promise for the asset to be loaded.
* @param url - The URL to be loaded
* @param data - any custom additional information relevant to the asset being loaded
* @returns - a promise that will resolve to an Asset for example a Texture of a JSON object
*/
private _getLoadPromiseAndParser(url: string, data?: LoadAsset): PromiseAndParser
{
const result: PromiseAndParser = {
promise: null,
parser: null
};
result.promise = (async () =>
{
let asset = null;
for (let i = 0; i < this.parsers.length; i++)
{
const parser = this.parsers[i];
if (parser.load && parser.test?.(url, data, this))
{
asset = await parser.load(url, data, this);
result.parser = parser;
break;
}
}
if (!result.parser)
{
// #if _DEBUG
// eslint-disable-next-line max-len
console.warn(`[Assets] ${url} could not be loaded as we don't know how to parse it, ensure the correct parser has being added`);
// #endif
return null;
}
for (let i = 0; i < this.parsers.length; i++)
{
const parser = this.parsers[i];
if (parser.parse)
{
if (parser.parse && await parser.testParse?.(asset, data, this))
{
// transform the asset..
asset = await parser.parse(asset, data, this) || asset;
result.parser = parser;
}
}
}
return asset;
})();
return result;
}
/**
* Loads an asset(s) using the parsers added to the Loader.
* @example
* // single asset:
* const asset = await Loader.load('cool.png');
* console.log(asset);
* @example
* // multiple assets:
* const assets = await Loader.load(['cool.png', 'cooler.png']);
* console.log(assets);
* @param assetsToLoadIn - urls that you want to load, or a single one!
* @param onProgress - a function that gets called when the progress changes
*/
public async load(
assetsToLoadIn: string | string[] | LoadAsset | LoadAsset[],
onProgress?: (progress: number) => void,
): Promise<{[key: string]: any} | any>
{
let count = 0;
const assets: Record<string, Promise<any>> = {};
const singleAsset = isSingleItem(assetsToLoadIn);
const assetsToLoad = convertToList<LoadAsset>(assetsToLoadIn, (item) => ({
src: item,
}));
const total = assetsToLoad.length;
const promises: Promise<void>[] = assetsToLoad.map(async (asset: LoadAsset) =>
{
const url = makeAbsoluteUrl(asset.src);
if (!assets[asset.src])
{
try
{
if (!this.promiseCache[url])
{
this.promiseCache[url] = this._getLoadPromiseAndParser(url, asset);
}
assets[asset.src] = await this.promiseCache[url].promise;
// Only progress if nothing goes wrong
if (onProgress) onProgress(++count / total);
}
catch (e)
{
// Delete eventually registered file and promises from internal cache
// so they can be eligible for another loading attempt
delete this.promiseCache[url];
delete assets[asset.src];
// Stop further execution
throw new Error(`[Loader.load] Failed to load ${url}.\n${e}`);
}
}
});
await Promise.all(promises);
return singleAsset ? assets[assetsToLoad[0].src] : assets;
}
/**
* Unloads an asset(s). Any unloaded assets will be destroyed, freeing up memory for your app.
* The parser that created the asset, will be the one that unloads it.
* @example
* // single asset:
* const asset = await Loader.load('cool.png');
*
* await Loader.unload('cool.png');
*
* console.log(asset.destroyed); // true
* @param assetsToUnloadIn - urls that you want to unload, or a single one!
*/
public async unload(
assetsToUnloadIn: string | string[] | LoadAsset | LoadAsset[],
): Promise<void>
{
const assetsToUnload = convertToList<LoadAsset>(assetsToUnloadIn, (item) => ({
src: item,
}));
const promises: Promise<void>[] = assetsToUnload.map(async (asset: LoadAsset) =>
{
const url = makeAbsoluteUrl(asset.src);
const loadPromise = this.promiseCache[url];
if (loadPromise)
{
const loadedAsset = await loadPromise.promise;
loadPromise.parser?.unload?.(loadedAsset, asset, this);
delete this.promiseCache[url];
}
});
await Promise.all(promises);
}
/** All loader parsers registered */
public get parsers(): LoaderParser[]
{
return this._parsers;
}
}