Assets

Assets can be stored locally inside the project or hosted online. Frequently used assets — such as character sprites, backgrounds, and background music — are best kept local. Assets used only once or large optional files are better hosted online. Each approach has trade-offs:

Local assets

To save and use assets locally, you can use any folder—there are no restrictions. However, it is recommended to use the src/assets folder. Inside this folder, you can create subfolders to better organize your assets.

PixiJS AssetPack is already pre-configured in the Pixi’VN project templates through the Vite.js integration — automating the processing and optimization of your assets so you can focus on building your project.

During development (vite dev) it watches the src/assets folder for changes and processes them on the fly. During the production build (vite build) it runs a full optimization pass before bundling.

The optimizations it applies include:

• Compression — reduces file sizes for faster loading.
• Format conversion — converts images to modern formats (e.g. WebP, AVIF) when supported.
• Texture atlases — combines multiple small images into a single sprite sheet to reduce draw calls.

Once processing is complete, it generates optimized files in public/assets and the src/assets/manifest.gen.json file, which contains the list of all asset bundles and their paths. These outputs are then used by PixiJS to load assets efficiently.

{
    "bundles": [
        {
            "name": "audio",
            "assets": [
                {
                    "alias": "bgm_cheerful",
                    "src": "./assets/audio/bgm_cheerful.wav"
                },
                {
                    "alias": "sfx_whoosh",
                    "src": "./assets/audio/sfx_whoosh.wav"
                }
            ]
        },
        {
            "name": "mainmenu",
            "assets": [
                {
                    "alias": "background_main_menu",
                    "src": "./assets/mainmenu/background_main_menu.png"
                }
            ]
        },
        {
            "name": "start",
            "assets": [
                {
                    "alias": "bg01-hallway",
                    "src": "./assets/start/bg01-hallway.webp"
                }
            ]
        },
        {
            "name": "mc",
            "assets": [
                {
                    "alias": "mc-neutral",
                    "src": "./assets/mc/mc-neutral.png"
                }
            ]
        }
    ]
}

Assets hosting

You can save your assets online. This is a good option if you want to save space in your project or if you want create a game playable online without the need to download it first. You can use any cloud service that allows you to upload files and generate a public URL (you need to make sure that the cloud service you are using allows CORS requests).

Here are some popular options for hosting your assets online:

Once you have your assets ready, you need to manually define which ones your game can use and how they are grouped into bundles.

All Pixi’VN templates include a src/assets/index.ts file that you can edit to register your assets:

import generatedManifestJson from "@/assets/manifest.gen.json";
import { AUDIO_BUNDLE_NAME } from "@/constants";
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: [
        ...generatedManifestJson.bundles,
        {
            name: AUDIO_BUNDLE_NAME,
            assets: [
                {
                    alias: "bgm_cheerful",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/audio/bgm_cheerful.wav",
                },
                {
                    alias: "sfx_whoosh",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/audio/sfx_whoosh.wav",
                },
            ],
        },
        // 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",
                },
            ],
        },
        // characters
        {
            name: "mc",
            assets: [
                {
                    alias: "mc-neutral",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/characters/mc-neutral.png",
                },
            ],
        },
    ],
};

Other features