Loading assets

Especially for games with online assets, following good loading practices is essential to avoid long wait times and keep the experience smooth for the player.

To load and manipulate assets (images, gifs, videos, etc.) you will need to use Assets. Assets is a class with many features and comes from the PixiJS library. For more information, read here.

Use aliases to load assets

To load an asset, always use its alias — the unique identifier defined in the manifest or when registering the asset. Using the src path directly is strongly discouraged: it couples your code to the file location, making it fragile when paths or hosting change.

import { Assets } from "@drincs/pixi-vn";

const texture = await Assets.load("eggHead");

{
    "bundles": [
        {
            "name": "default",
            "assets": [
                {
                    "alias": "eggHead",
                    "src": "./assets/eggHead.png"
                }
            ]
        }
    ]
}

Organize assets into bundles

A best practice is to group assets into bundles rather than registering them individually. Bundles allow you to load a whole set of assets with a single call, and to defer loading until the assets are actually needed.

It is recommended to name each bundle based on where it will be used. For example:

• use the label's id (e.g. startLabel.id) as the bundle name for assets used in that specific label
• use the route path (e.g. "/") as the bundle name for assets used in the corresponding screen, such as the main menu

This way, you can load exactly the right assets at the right moment, without loading more than necessary.

import { startLabel } from "@/content/labels/start.label";
import type { FileRouteTypes } from "@/routeTree.gen";
import type { AssetsManifest } from "@drincs/pixi-vn";

export const manifest: AssetsManifest = {
    bundles: [
        // screens
        {
            // main menu
            name: "/" as FileRouteTypes["fullPaths"],
            assets: [
                {
                    alias: "background_main_menu",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/main-menu.png",
                },
            ],
        },
        // labels
        {
            name: startLabel.id,
            assets: [
                {
                    alias: "bg01-hallway",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/breakdown/bg01-hallway.webp",
                },
            ],
        },
    ],
};

When to load assets

By default, assets are loaded on demand — only when they are actually needed. However, loading at the last moment can cause noticeable pauses during gameplay.

Here are the most common and recommended moments to load assets in advance: