@safe-engine/pixi 8.10.0 → 8.10.2

package/dist/packages/pixijs/src/assets/resolver/Resolver.js

@@ -0,0 +1,591 @@
+import { warn } from '../../utils/logging/warn';
+import { path } from '../../utils/path';
+import { convertToList } from '../utils/convertToList';
+import { createStringVariations } from '../utils/createStringVariations';
+import { isSingleItem } from '../utils/isSingleItem';
+/**
+ * A class that is responsible for resolving mapping asset URLs to keys.
+ * At its most basic it can be used for Aliases:
+ *
+ * ```js
+ * resolver.add('foo', 'bar');
+ * resolver.resolveUrl('foo') // => 'bar'
+ * ```
+ *
+ * It can also be used to resolve the most appropriate asset for a given URL:
+ *
+ * ```js
+ * resolver.prefer({
+ *     params: {
+ *         format: 'webp',
+ *         resolution: 2,
+ *     }
+ * });
+ *
+ * resolver.add('foo', ['bar@2x.webp', 'bar@2x.png', 'bar.webp', 'bar.png']);
+ *
+ * resolver.resolveUrl('foo') // => 'bar@2x.webp'
+ * ```
+ * Other features include:
+ * - Ability to process a manifest file to get the correct understanding of how to resolve all assets
+ * - Ability to add custom parsers for specific file types
+ * - Ability to add custom prefer rules
+ *
+ * This class only cares about the URL, not the loading of the asset itself.
+ *
+ * It is not intended that this class is created by developers - its part of the Asset class
+ * This is the third major system of PixiJS' main Assets class
+ * @category assets
+ * @advanced
+ */
+export class Resolver {
+    constructor() {
+        this._defaultBundleIdentifierOptions = {
+            connector: '-',
+            createBundleAssetId: (bundleId, assetId) => `${bundleId}${this._bundleIdConnector}${assetId}`,
+            extractAssetIdFromBundle: (bundleId, assetBundleId) => assetBundleId.replace(`${bundleId}${this._bundleIdConnector}`, ''),
+        };
+        /** The character that is used to connect the bundleId and the assetId when generating a bundle asset id key */
+        this._bundleIdConnector = this._defaultBundleIdentifierOptions.connector;
+        /**
+         * A function that generates a bundle asset id key from a bundleId and an assetId
+         * @param bundleId - the bundleId
+         * @param assetId  - the assetId
+         * @returns the bundle asset id key
+         */
+        this._createBundleAssetId = this._defaultBundleIdentifierOptions.createBundleAssetId;
+        /**
+         * A function that generates an assetId from a bundle asset id key. This is the reverse of generateBundleAssetId
+         * @param bundleId - the bundleId
+         * @param assetBundleId - the bundle asset id key
+         * @returns the assetId
+         */
+        this._extractAssetIdFromBundle = this._defaultBundleIdentifierOptions.extractAssetIdFromBundle;
+        this._assetMap = {};
+        this._preferredOrder = [];
+        this._parsers = [];
+        this._resolverHash = {};
+        this._bundles = {};
+    }
+    /**
+     * Override how the resolver deals with generating bundle ids.
+     * must be called before any bundles are added
+     * @param bundleIdentifier - the bundle identifier options
+     */
+    setBundleIdentifier(bundleIdentifier) {
+        var _a, _b, _c;
+        this._bundleIdConnector = (_a = bundleIdentifier.connector) !== null && _a !== void 0 ? _a : this._bundleIdConnector;
+        this._createBundleAssetId = (_b = bundleIdentifier.createBundleAssetId) !== null && _b !== void 0 ? _b : this._createBundleAssetId;
+        this._extractAssetIdFromBundle = (_c = bundleIdentifier.extractAssetIdFromBundle) !== null && _c !== void 0 ? _c : this._extractAssetIdFromBundle;
+        if (this._extractAssetIdFromBundle('foo', this._createBundleAssetId('foo', 'bar')) !== 'bar') {
+            throw new Error('[Resolver] GenerateBundleAssetId are not working correctly');
+        }
+    }
+    /**
+     * Let the resolver know which assets you prefer to use when resolving assets.
+     * Multiple prefer user defined rules can be added.
+     * @example
+     * resolver.prefer({
+     *     // first look for something with the correct format, and then then correct resolution
+     *     priority: ['format', 'resolution'],
+     *     params:{
+     *         format:'webp', // prefer webp images
+     *         resolution: 2, // prefer a resolution of 2
+     *     }
+     * })
+     * resolver.add('foo', ['bar@2x.webp', 'bar@2x.png', 'bar.webp', 'bar.png']);
+     * resolver.resolveUrl('foo') // => 'bar@2x.webp'
+     * @param preferOrders - the prefer options
+     */
+    prefer(...preferOrders) {
+        preferOrders.forEach((prefer) => {
+            this._preferredOrder.push(prefer);
+            if (!prefer.priority) {
+                // generate the priority based on the order of the object
+                prefer.priority = Object.keys(prefer.params);
+            }
+        });
+        this._resolverHash = {};
+    }
+    /**
+     * Set the base path to prepend to all urls when resolving
+     * @example
+     * resolver.basePath = 'https://home.com/';
+     * resolver.add('foo', 'bar.ong');
+     * resolver.resolveUrl('foo', 'bar.png'); // => 'https://home.com/bar.png'
+     * @param basePath - the base path to use
+     */
+    set basePath(basePath) {
+        this._basePath = basePath;
+    }
+    get basePath() {
+        return this._basePath;
+    }
+    /**
+     * Set the root path for root-relative URLs. By default the `basePath`'s root is used. If no `basePath` is set, then the
+     * default value for browsers is `window.location.origin`
+     * @example
+     * // Application hosted on https://home.com/some-path/index.html
+     * resolver.basePath = 'https://home.com/some-path/';
+     * resolver.rootPath = 'https://home.com/';
+     * resolver.add('foo', '/bar.png');
+     * resolver.resolveUrl('foo', '/bar.png'); // => 'https://home.com/bar.png'
+     * @param rootPath - the root path to use
+     */
+    set rootPath(rootPath) {
+        this._rootPath = rootPath;
+    }
+    get rootPath() {
+        return this._rootPath;
+    }
+    /**
+     * All the active URL parsers that help the parser to extract information and create
+     * an asset object-based on parsing the URL itself.
+     *
+     * Can be added using the extensions API
+     * @example
+     * resolver.add('foo', [
+     *     {
+     *         resolution: 2,
+     *         format: 'png',
+     *         src: 'image@2x.png',
+     *     },
+     *     {
+     *         resolution:1,
+     *         format:'png',
+     *         src: 'image.png',
+     *     },
+     * ]);
+     *
+     * // With a url parser the information such as resolution and file format could extracted from the url itself:
+     * extensions.add({
+     *     extension: ExtensionType.ResolveParser,
+     *     test: loadTextures.test, // test if url ends in an image
+     *     parse: (value: string) =>
+     *     ({
+     *         resolution: parseFloat(Resolver.RETINA_PREFIX.exec(value)?.[1] ?? '1'),
+     *         format: value.split('.').pop(),
+     *         src: value,
+     *     }),
+     * });
+     *
+     * // Now resolution and format can be extracted from the url
+     * resolver.add('foo', [
+     *     'image@2x.png',
+     *     'image.png',
+     * ]);
+     */
+    get parsers() {
+        return this._parsers;
+    }
+    /** Used for testing, this resets the resolver to its initial state */
+    reset() {
+        this.setBundleIdentifier(this._defaultBundleIdentifierOptions);
+        this._assetMap = {};
+        this._preferredOrder = [];
+        // Do not reset this._parsers
+        this._resolverHash = {};
+        this._rootPath = null;
+        this._basePath = null;
+        this._manifest = null;
+        this._bundles = {};
+        this._defaultSearchParams = null;
+    }
+    /**
+     * Sets the default URL search parameters for the URL resolver. The urls can be specified as a string or an object.
+     * @param searchParams - the default url parameters to append when resolving urls
+     */
+    setDefaultSearchParams(searchParams) {
+        if (typeof searchParams === 'string') {
+            this._defaultSearchParams = searchParams;
+        }
+        else {
+            const queryValues = searchParams;
+            this._defaultSearchParams = Object.keys(queryValues)
+                .map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(queryValues[key])}`)
+                .join('&');
+        }
+    }
+    /**
+     * Returns the aliases for a given asset
+     * @param asset - the asset to get the aliases for
+     */
+    getAlias(asset) {
+        const { alias, src } = asset;
+        const aliasesToUse = convertToList(alias || src, (value) => {
+            if (typeof value === 'string')
+                return value;
+            if (Array.isArray(value))
+                return value.map((v) => { var _a; return (_a = v === null || v === void 0 ? void 0 : v.src) !== null && _a !== void 0 ? _a : v; });
+            if (value === null || value === void 0 ? void 0 : value.src)
+                return value.src;
+            return value;
+        }, true);
+        return aliasesToUse;
+    }
+    /**
+     * Add a manifest to the asset resolver. This is a nice way to add all the asset information in one go.
+     * generally a manifest would be built using a tool.
+     * @param manifest - the manifest to add to the resolver
+     */
+    addManifest(manifest) {
+        if (this._manifest) {
+            // #if _DEBUG
+            warn('[Resolver] Manifest already exists, this will be overwritten');
+            // #endif
+        }
+        this._manifest = manifest;
+        manifest.bundles.forEach((bundle) => {
+            this.addBundle(bundle.name, bundle.assets);
+        });
+    }
+    /**
+     * This adds a bundle of assets in one go so that you can resolve them as a group.
+     * For example you could add a bundle for each screen in you pixi app
+     * @example
+     * resolver.addBundle('animals', [
+     *  { alias: 'bunny', src: 'bunny.png' },
+     *  { alias: 'chicken', src: 'chicken.png' },
+     *  { alias: 'thumper', src: 'thumper.png' },
+     * ]);
+     * // or
+     * resolver.addBundle('animals', {
+     *     bunny: 'bunny.png',
+     *     chicken: 'chicken.png',
+     *     thumper: 'thumper.png',
+     * });
+     *
+     * const resolvedAssets = await resolver.resolveBundle('animals');
+     * @param bundleId - The id of the bundle to add
+     * @param assets - A record of the asset or assets that will be chosen from when loading via the specified key
+     */
+    addBundle(bundleId, assets) {
+        const assetNames = [];
+        let convertedAssets = assets;
+        if (!Array.isArray(assets)) {
+            // convert to array...
+            convertedAssets = Object.entries(assets).map(([alias, src]) => {
+                if (typeof src === 'string' || Array.isArray(src)) {
+                    return { alias, src };
+                }
+                return Object.assign({ alias }, src);
+            });
+        }
+        // when storing keys against a bundle we prepend the bundleId to each asset key
+        // and pass it through as an additional alias for the asset
+        // this keeps clashing ids separate on a per-bundle basis
+        // you can also resolve a file using the bundleId-assetId syntax
+        convertedAssets.forEach((asset) => {
+            const srcs = asset.src;
+            const aliases = asset.alias;
+            let ids;
+            if (typeof aliases === 'string') {
+                const bundleAssetId = this._createBundleAssetId(bundleId, aliases);
+                assetNames.push(bundleAssetId);
+                ids = [aliases, bundleAssetId];
+            }
+            else {
+                const bundleIds = aliases.map((name) => this._createBundleAssetId(bundleId, name));
+                assetNames.push(...bundleIds);
+                ids = [...aliases, ...bundleIds];
+            }
+            this.add(Object.assign(Object.assign({}, asset), {
+                alias: ids,
+                src: srcs,
+            }));
+        });
+        this._bundles[bundleId] = assetNames;
+    }
+    /**
+     * Tells the resolver what keys are associated with witch asset.
+     * The most important thing the resolver does
+     * @example
+     * // Single key, single asset:
+     * resolver.add({alias: 'foo', src: 'bar.png');
+     * resolver.resolveUrl('foo') // => 'bar.png'
+     *
+     * // Multiple keys, single asset:
+     * resolver.add({alias: ['foo', 'boo'], src: 'bar.png'});
+     * resolver.resolveUrl('foo') // => 'bar.png'
+     * resolver.resolveUrl('boo') // => 'bar.png'
+     *
+     * // Multiple keys, multiple assets:
+     * resolver.add({alias: ['foo', 'boo'], src: ['bar.png', 'bar.webp']});
+     * resolver.resolveUrl('foo') // => 'bar.png'
+     *
+     * // Add custom data attached to the resolver
+     * Resolver.add({
+     *     alias: 'bunnyBooBooSmooth',
+     *     src: 'bunny{png,webp}',
+     *     data: { scaleMode:SCALE_MODES.NEAREST }, // Base texture options
+     * });
+     *
+     * resolver.resolve('bunnyBooBooSmooth') // => { src: 'bunny.png', data: { scaleMode: SCALE_MODES.NEAREST } }
+     * @param aliases - the UnresolvedAsset or array of UnresolvedAssets to add to the resolver
+     */
+    add(aliases) {
+        const assets = [];
+        if (Array.isArray(aliases)) {
+            assets.push(...aliases);
+        }
+        else {
+            assets.push(aliases);
+        }
+        let keyCheck;
+        // #if _DEBUG
+        // eslint-disable-next-line prefer-const
+        keyCheck = (key) => {
+            if (this.hasKey(key)) {
+                // #if _DEBUG
+                warn(`[Resolver] already has key: ${key} overwriting`);
+                // #endif
+            }
+        };
+        // #endif
+        const assetArray = convertToList(assets);
+        // loop through all the assets and generate a resolve asset for each src
+        assetArray.forEach((asset) => {
+            const { src } = asset;
+            let { data, format, loadParser: userDefinedLoadParser, parser: userDefinedParser, } = asset;
+            // src can contain an unresolved asset itself
+            // so we need to merge that data with the current asset
+            // we dont need to create string variations for the src if it is a ResolvedAsset
+            const srcsToUse = convertToList(src).map((src) => {
+                if (typeof src === 'string') {
+                    return createStringVariations(src);
+                }
+                return Array.isArray(src) ? src : [src];
+            });
+            const aliasesToUse = this.getAlias(asset);
+            // #if _DEBUG
+            Array.isArray(aliasesToUse) ? aliasesToUse.forEach(keyCheck) : keyCheck(aliasesToUse);
+            // #endif
+            // loop through all the srcs and generate a resolve asset for each src
+            const resolvedAssets = [];
+            srcsToUse.forEach((srcs) => {
+                srcs.forEach((src) => {
+                    var _a, _b, _c, _d;
+                    let formattedAsset = {};
+                    if (typeof src !== 'object') {
+                        formattedAsset.src = src;
+                        // first see if it contains any {} tags...
+                        for (let i = 0; i < this._parsers.length; i++) {
+                            const parser = this._parsers[i];
+                            if (parser.test(src)) {
+                                formattedAsset = parser.parse(src);
+                                break;
+                            }
+                        }
+                    }
+                    else {
+                        data = (_a = src.data) !== null && _a !== void 0 ? _a : data;
+                        format = (_b = src.format) !== null && _b !== void 0 ? _b : format;
+                        if (src.loadParser || src.parser) {
+                            userDefinedLoadParser = (_c = src.loadParser) !== null && _c !== void 0 ? _c : userDefinedLoadParser;
+                            userDefinedParser = (_d = src.parser) !== null && _d !== void 0 ? _d : userDefinedParser;
+                        }
+                        formattedAsset = Object.assign(Object.assign({}, formattedAsset), src);
+                    }
+                    // check if aliases is undefined
+                    if (!aliasesToUse) {
+                        throw new Error(`[Resolver] alias is undefined for this asset: ${formattedAsset.src}`);
+                    }
+                    formattedAsset = this._buildResolvedAsset(formattedAsset, {
+                        aliases: aliasesToUse,
+                        data,
+                        format,
+                        loadParser: userDefinedLoadParser,
+                        parser: userDefinedParser,
+                        progressSize: asset.progressSize,
+                    });
+                    resolvedAssets.push(formattedAsset);
+                });
+            });
+            aliasesToUse.forEach((alias) => {
+                this._assetMap[alias] = resolvedAssets;
+            });
+        });
+    }
+    // TODO: this needs an overload like load did in Assets
+    /**
+     * If the resolver has had a manifest set via setManifest, this will return the assets urls for
+     * a given bundleId or bundleIds.
+     * @example
+     * // 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',
+     *                 },
+     *             ],
+     *         },
+     *     ]
+     * };
+     *
+     * resolver.setManifest(manifest);
+     * const resolved = resolver.resolveBundle('load-screen');
+     * @param bundleIds - The bundle ids to resolve
+     * @returns All the bundles assets or a hash of assets for each bundle specified
+     */
+    resolveBundle(bundleIds) {
+        const singleAsset = isSingleItem(bundleIds);
+        bundleIds = convertToList(bundleIds);
+        const out = {};
+        bundleIds.forEach((bundleId) => {
+            const assetNames = this._bundles[bundleId];
+            if (assetNames) {
+                const results = this.resolve(assetNames);
+                const assets = {};
+                for (const key in results) {
+                    const asset = results[key];
+                    assets[this._extractAssetIdFromBundle(bundleId, key)] = asset;
+                }
+                out[bundleId] = assets;
+            }
+        });
+        return singleAsset ? out[bundleIds[0]] : out;
+    }
+    /**
+     * Does exactly what resolve does, but returns just the URL rather than the whole asset object
+     * @param key - The key or keys to resolve
+     * @returns - The URLs associated with the key(s)
+     */
+    resolveUrl(key) {
+        const result = this.resolve(key);
+        if (typeof key !== 'string') {
+            const out = {};
+            for (const i in result) {
+                out[i] = result[i].src;
+            }
+            return out;
+        }
+        return result.src;
+    }
+    resolve(keys) {
+        const singleAsset = isSingleItem(keys);
+        keys = convertToList(keys);
+        const result = {};
+        keys.forEach((key) => {
+            if (!this._resolverHash[key]) {
+                if (this._assetMap[key]) {
+                    let assets = this._assetMap[key];
+                    const preferredOrder = this._getPreferredOrder(assets);
+                    preferredOrder === null || preferredOrder === void 0 ? void 0 : preferredOrder.priority.forEach((priorityKey) => {
+                        preferredOrder.params[priorityKey].forEach((value) => {
+                            const filteredAssets = assets.filter((asset) => {
+                                if (asset[priorityKey]) {
+                                    return asset[priorityKey] === value;
+                                }
+                                return false;
+                            });
+                            if (filteredAssets.length) {
+                                assets = filteredAssets;
+                            }
+                        });
+                    });
+                    this._resolverHash[key] = assets[0];
+                }
+                else {
+                    this._resolverHash[key] = this._buildResolvedAsset({
+                        alias: [key],
+                        src: key,
+                    }, {});
+                }
+            }
+            result[key] = this._resolverHash[key];
+        });
+        return singleAsset ? result[keys[0]] : result;
+    }
+    /**
+     * Checks if an asset with a given key exists in the resolver
+     * @param key - The key of the asset
+     */
+    hasKey(key) {
+        return !!this._assetMap[key];
+    }
+    /**
+     * Checks if a bundle with the given key exists in the resolver
+     * @param key - The key of the bundle
+     */
+    hasBundle(key) {
+        return !!this._bundles[key];
+    }
+    /**
+     * Internal function for figuring out what prefer criteria an asset should use.
+     * @param assets
+     */
+    _getPreferredOrder(assets) {
+        for (let i = 0; i < assets.length; i++) {
+            const asset = assets[i];
+            const preferred = this._preferredOrder.find((preference) => preference.params.format.includes(asset.format));
+            if (preferred) {
+                return preferred;
+            }
+        }
+        return this._preferredOrder[0];
+    }
+    /**
+     * Appends the default url parameters to the url
+     * @param url - The url to append the default parameters to
+     * @returns - The url with the default parameters appended
+     */
+    _appendDefaultSearchParams(url) {
+        if (!this._defaultSearchParams)
+            return url;
+        const paramConnector = (/\?/).test(url) ? '&' : '?';
+        return `${url}${paramConnector}${this._defaultSearchParams}`;
+    }
+    _buildResolvedAsset(formattedAsset, data) {
+        var _a, _b;
+        const { aliases, data: assetData, loadParser, parser, format, progressSize } = data;
+        if (this._basePath || this._rootPath) {
+            formattedAsset.src = path.toAbsolute(formattedAsset.src, this._basePath, this._rootPath);
+        }
+        formattedAsset.alias = (_a = aliases !== null && aliases !== void 0 ? aliases : formattedAsset.alias) !== null && _a !== void 0 ? _a : [formattedAsset.src];
+        formattedAsset.src = this._appendDefaultSearchParams(formattedAsset.src);
+        formattedAsset.data = Object.assign(Object.assign({}, assetData || {}), formattedAsset.data);
+        formattedAsset.loadParser = loadParser !== null && loadParser !== void 0 ? loadParser : formattedAsset.loadParser;
+        formattedAsset.parser = parser !== null && parser !== void 0 ? parser : formattedAsset.parser;
+        formattedAsset.format = (_b = format !== null && format !== void 0 ? format : formattedAsset.format) !== null && _b !== void 0 ? _b : getUrlExtension(formattedAsset.src);
+        if (progressSize !== undefined) {
+            formattedAsset.progressSize = progressSize;
+        }
+        return formattedAsset;
+    }
+}
+/**
+ * The prefix that denotes a URL is for a retina asset.
+ * @default /@([0-9\.]+)x/
+ * @example `@2x`
+ */
+Resolver.RETINA_PREFIX = /@([0-9\.]+)x/;
+/**
+ * @param url
+ * @internal
+ */
+export function getUrlExtension(url) {
+    return url.split('.').pop().split('?').shift()
+        .split('#')
+        .shift();
+}

package/dist/packages/pixijs/src/assets/resolver/__tests__/Resolver.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Resolver.test.d.ts.map

package/dist/packages/pixijs/src/assets/resolver/__tests__/Resolver.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Resolver.test.d.ts","sourceRoot":"","sources":["../../../../../../../packages/pixijs/src/assets/resolver/__tests__/Resolver.test.ts"],"names":[],"mappings":""}