资源

¥Assets

PixiJS 拥有 Assets 单例，用于简化资源加载。它采用现代设计，基于 Promise，支持缓存感知，并且高度可扩展 - 使其成为所有 PixiJS 资源管理的一站式解决方案！

¥PixiJS has the Assets singleton which is used to streamline resource loading. It’s modern, Promise-based, cache-aware, and highly extensible—making it the one stop shop for all PixiJS resource management!

import { Assets } from 'pixi.js';

await Assets.init({ ... });

const texture = await Assets.load('path/to/hero.png');

主要功能

¥Key Capabilities

• 通过 Promises 或 async/await 异步加载资源。

  ¥Asynchronous loading of assets via Promises or async/await.

• 缓存可防止冗余网络请求。

  ¥Caching prevents redundant network requests.

• 内置对常见媒体格式（图片、视频、字体）的支持。

  ¥Built-in support for common media formats (images, video, fonts).

• 自定义解析器和解析器，提高灵活性。

  ¥Custom parsers and resolvers for flexibility.

• 后台加载、基于清单的包和智能回退。

  ¥Background loading, manifest-based bundles, and smart fallbacks.

支持的文件类型

¥Supported File Types

类型	扩展	加载器
纹理	.png, .jpg, .gif, .webp, .avif, .svg	loadTextures, loadSvg
视频纹理	.mp4, .m4v, .webm, .ogg, .ogv, .h264, .avi, .mov	loadVideoTextures
精灵表	.json	spritesheetAsset
位图字体	.fnt, .xml, .txt	loadBitmapFont
Web 字体	.ttf, .otf, .woff, .woff2	loadWebFont
JSON	.json	loadJson
文本	.txt	loadTxt
压缩纹理	.basis, .dds, .ktx, .ktx2	loadBasis, loadDDS, loadKTX

需要更多功能？添加自定义解析器！

¥Need more? Add custom parsers!

---

入门

¥Getting started

加载资源

¥Loading Assets

使用 PixiJS 加载资源非常简单，只需调用 Assets.load() 并传入资源的 URL 即可。此函数返回一个 Promise，该 Promise 解析为已加载的资源 - 无论是纹理、字体、JSON 还是其他受支持的格式。

¥Loading an asset with PixiJS is as simple as calling Assets.load() and passing in the asset’s URL. This function returns a Promise that resolves to the loaded resource—whether that’s a texture, font, JSON, or another supported format.

你可以提供绝对 URL（例如来自 CDN）：

¥You can provide either an absolute URL (e.g. from a CDN):

const texture = await Assets.load('https://example.com/assets/hero.png');

或者在项目中使用相对路径：

¥Or a relative path within your project:

const texture = await Assets.load('assets/hero.png');

PixiJS 通常会根据文件扩展名自动确定如何加载资源，并缓存结果以避免重复下载。

¥PixiJS will typically automatically determine how to load the asset based on its file extension and will cache the result to avoid redundant downloads.

import { Application, Assets, Texture } from 'pixi.js';

const app = new Application();
// Application must be initialized before loading assets
await app.init({ backgroundColor: 0x1099bb });

// Load a single asset
const bunnyTexture = await Assets.load<Texture>('path/to/bunny.png');
const sprite = new Sprite(bunnyTexture);

// Load multiple assets at once
const textures = await Assets.load<Texture>(['path/to/bunny.png', 'path/to/cat.png']);
const bunnySprite = new Sprite(textures['path/to/bunny.png']);
const catSprite = new Sprite(textures['path/to/cat.png']);

重复加载是安全的

¥Repeated Loads Are Safe

Assets 通过 URL 或别名进行缓存。对相同资源的请求返回相同的纹理。

¥Assets caches by URL or alias. Requests for the same resource return the same texture.

const p1 = await Assets.load('bunny.png');
const p2 = await Assets.load('bunny.png');
console.log(p1 === p2); // true

资源别名

¥Asset Aliases

你还可以使用别名来引用资源，而不是使用其完整的 URL。这提供了一种更便捷的资源管理方式，尤其是在 URL 较长或复杂的情况下。

¥You can also use aliases to refer to assets instead of their full URLs. This provides a more convenient way to manage assets, especially when you have long or complex URLs.

await Assets.load<Texture>({ alias: 'bunny', src: 'path/to/bunny.png' });
const bunnyTexture = Assets.get('bunny');

所有 Asset API 都支持别名，包括 Assets.load()、Assets.get() 和 Assets.unload()。

¥All Asset APIs support aliases, including Assets.load(), Assets.get(), and Assets.unload().

定义资源有更复杂的方法，你可以在 解析器 部分阅读相关内容。

¥There is more complex ways of defining assets and you can read about them in the Resolver section.

检索已加载的资源

¥Retrieving Loaded Assets

你还可以使用 Assets.get() 检索已加载的资源：

¥You can also retrieve assets that have already been loaded using Assets.get():

await Assets.load<Texture>('path/to/bunny.png');
const bunnyTexture = Assets.get('path/to/bunny.png');
const sprite = new Sprite(bunnyTexture);

当你在代码的其他位置预加载了资源，并希望稍后访问它们而不必从初始加载传递引用时，这很有用。

¥This is useful for when you have preloaded your assets elsewhere in your code and want to access them later without having to pass round references from the initial load.

卸载资源

¥Unloading Assets

要卸载资源，你可以使用 Assets.unload()。这将从缓存中移除资源并释放内存。请注意，如果你在卸载资源后尝试访问它，则需要重新加载。

¥To unload an asset, you can use Assets.unload(). This will remove the asset from the cache and free up memory. Note that if you try to access the asset after unloading it, you will need to load it again.

await Assets.load<Texture>('path/to/bunny.png');
const bunnyTexture = Assets.get('path/to/bunny.png');
const sprite = new Sprite(bunnyTexture);
// Unload the asset
await Assets.unload('path/to/bunny.png');

自定义资源加载

¥Customizing Asset Loading

你可以通过向 Assets.init() 方法提供选项来自定义资源加载过程。这允许你设置资源加载方式的首选项，指定资源的基本路径等等。

¥You can customize the asset loading process by providing options to the Assets.init() method. This allows you to set preferences for how assets are loaded, specify a base path for assets, and more.

import { Assets } from 'pixi.js';

await Assets.init({...});

选项	类型	描述
basePath	string	前缀应用于所有相对资源路径（例如 CDN）。
defaultSearchParams	string	一个默认 URL 参数字符串，用于附加到所有已加载的资源。
skipDetections	boolean	跳过资源的环境检测解析器。
manifest	Manifest	一个命名资源包及其内容的描述符。
preferences	AssetPreferences	指定每个加载器的首选项
bundleIdentifier	BundleIdentifierOptions	高级 - 覆盖 bundlesId 的生成方式。

---

高级用法

¥Advanced Usage

Assets API 中提供了一些高级功能，可以帮助你更有效地管理资源。你可以在其余文档中阅读有关这些功能的更多信息：

¥There are several advanced features available in the Assets API that can help you manage your assets more effectively. You can read more about these features in the rest of the documentation:

• 解析资源

  ¥Resolving Assets

• Manifests & Bundles（推荐）

  ¥Manifests & Bundles (Recommended)

• 背景加载

  ¥Background Loading

• 压缩纹理

  ¥Compressed Textures

---

API 参考

¥API Reference

• 概述

  ¥Overview

• 资源

  ¥Assets