Skip to main content

清单和 Bundle

¥Manifests & Bundles

PixiJS 通过 Manifest 和 Bundles 提供结构化且可扩展的资源管理方法。这是在 PixiJS 应用中管理资源的推荐方法，尤其是对于大型项目或需要根据上下文或用户交互动态加载资源的项目。本指南解释了它们是什么、如何使用它们，以及如何使用 AssetPack（一个旨在自动化清单和包创建的工具）高效地生成它们。

¥PixiJS has a structured and scalable approach to asset management through Manifests and Bundles. This is the recommended way to manage assets in your PixiJS applications, especially for larger projects or those that require dynamic loading of assets based on context or user interaction. This guide explains what they are, how to use them, and how to generate them efficiently using AssetPack — a tool designed to automate manifest and bundle creation.

什么是清单？​

¥What Is a Manifest?

Manifest 是一个描述符对象，用于定义你的资源加载策略。它列出了所有 bundles，每个 bundles 都包含按名称和别名分组的资源。此结构允许基于应用上下文（例如加载屏幕资源、特定于关卡的内容等）延迟加载资源。

¥A Manifest is a descriptor object that defines your asset loading strategy. It lists all bundles, each of which contains grouped assets by name and alias. This structure allows for lazy-loading assets based on application context (e.g. load screen assets, level-specific content, etc.).

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' },
            ],
        },
    ],
};

使用清单文件初始化​

¥Initializing With a Manifest

要使用清单初始化 PixiJS 资源处理：

¥To initialize PixiJS asset handling with a manifest:

import { Assets } from 'pixi.js';

await Assets.init({ manifest });

初始化完成后，你可以按名称加载资源包：

¥Once initialized, you can load bundles by name:

const loadScreenAssets = await Assets.loadBundle('load-screen');
const gameScreenAssets = await Assets.loadBundle('game-screen');

需要注意的是，你仍然可以通过资源别名直接加载资源，而无需加载整个资源包：

¥It should be noted that you can still load assets directly without loading an entire bundle via their alias:

await Assets.init({ manifest });
const background = await Assets.load('background');
const bar = await Assets.load('bar');

什么是 Bundle？​

¥What Is a Bundle?

Bundle 是一组由共享名称标识的资源。Bundles 可以在清单文件中预定义，也可以在运行时动态注册。

¥A Bundle is a group of assets that are identified by a shared name. While bundles can be pre-defined in a manifest, they can also be dynamically registered at runtime.

动态添加 Bundle​

¥Adding a Bundle Dynamically

此方法对于需要动态定义 bundle 的场景非常有用：

¥This approach is helpful for scenarios where you want to define bundles on the fly:

import { Assets } from 'pixi.js';

Assets.addBundle('animals', [
    { alias: 'bunny', src: 'bunny.png' },
    { alias: 'chicken', src: 'chicken.png' },
    { alias: 'thumper', src: 'thumper.png' },
]);

const assets = await Assets.loadBundle('animals');

// or load a specific asset from the bundle
const bunny = await Assets.load('bunny');

¥Recommended Tool: AssetPack

手动管理清单和包很容易出错。AssetPack 是一个命令行工具，可以扫描你的资源文件夹并自动生成优化的清单和包。

¥Managing manifests and bundles manually can be error-prone. AssetPack is a CLI tool that scans your assets folder and generates optimized manifests and bundles automatically.

主要优势​

¥Key Benefits

  • 按目录或模式组织资源

    ¥Organizes assets by directory or pattern

  • 支持 PixiJS 清单格式的输出

    ¥Supports output in PixiJS manifest format

  • 减少样板代码和手动错误的风险

    ¥Reduces boilerplate and risk of manual mistakes

你可以将 AssetPack 集成到构建管道中，以生成清单文件并使用 Assets.init({ manifest }) 加载它。

¥You can integrate AssetPack into your build pipeline to generate the manifest file and load it using Assets.init({ manifest }).