Pixi Vn Assets

Pixi'VN Assets: local vs. online, manifests, bundles, and loading strategy

Official docs: pixi-vn.com/start/assets (storage options) and pixi-vn.com/start/assets-management (loading strategy).

When to use this skill

Use this skill whenever a task involves adding a new image/audio/video file to a project, deciding whether an asset should live locally or be hosted online, editing the assets manifest, or choosing when a bundle of assets should load (blocking at startup, in the background, per-label, per-route). This skill does not cover how an image/sound is displayed/played once loaded — that's pixi-vn-canvas / pixi-vn-sound — only how it gets registered and made available by alias.

The one rule that matters most: always reference assets by their manifest alias, never by raw src path/URL, in game code. Loading by path directly is strongly discouraged — it couples code to a specific file location/host, so moving a file or switching hosting providers silently breaks every reference. Assets.load("bg01-hallway"), not Assets.load("https://.../bg01-hallway.webp").

Local vs. online assets

Assets can be stored locally in the project or hosted online (a CDN, GitHub raw, cloud storage). Frequently used assets (character sprites, backgrounds, background music) are best kept local; assets used once, or large optional files, are better hosted online to keep the project small and the initial download fast.

Local assets: the src/assets folder + PixiJS AssetPack

Local assets go under src/assets (any folder works, but this is the convention every official template uses), organized into subfolders however makes sense for the project. PixiJS AssetPack — pre-wired into the Vite config of every official template — watches this folder and, on every change (vite dev) or once before a production build (vite build), optimizes the files (compression, WebP/AVIF conversion, texture-atlas packing) into public/assets, and auto-generates src/assets/manifest.gen.json describing every resulting bundle/alias.

// vite.config.ts (already present in official templates — no changes usually needed)
import { AssetPack } from "@assetpack/core";
import assetPackConfig from "./.assetpack.ts";
// a Vite plugin runs `new AssetPack(assetPackConfig).watch()` in dev,
// `.run()` once during `vite build`

// .assetpack.ts (already present in official templates)
import { pixiPipes } from "@assetpack/core/pixi";

export default {
  entry: "./src/assets",
  output: "./public/assets",
  ignore: ["**/*.ts", "**/*.js", "**/*.gen.*"],
  pipes: [
    pixiPipes({ manifest: { output: "src/assets/manifest.gen.json" } }),
    // official templates add two extra pipes here: one bundle per top-level
    // folder (instead of everything in a single "default" bundle), and
    // stripping file extensions from generated aliases
  ],
};

src/assets/manifest.gen.json is generated — never hand-edit it. Any manual change is overwritten the next time AssetPack runs. If a local asset isn't showing up with the alias you expect, check the actual file's path/name under src/assets and let AssetPack regenerate the file, rather than editing the JSON directly.

// src/assets/manifest.gen.json (excerpt — auto-generated, read-only)
{
  "bundles": [
    {
      "name": "mc",
      "assets": [{ "alias": "mc-neutral", "src": "./assets/mc/mc-neutral.png" }]
    }
  ]
}

Online assets: the exact place to register them — src/assets/index.ts

For assets you host online (or any manifest entries beyond what AssetPack generates), the one place to add/edit them is src/assets/index.ts, present in every official template. It imports the auto-generated local manifest and appends hand-written bundles for remote URLs:

// src/assets/index.ts — the exact, single point to add/modify online assets
import generatedManifestJson from "@/assets/manifest.gen.json";
import type { AssetsManifest } from "@drincs/pixi-vn";

export const manifest: AssetsManifest = {
  bundles: [
    ...generatedManifestJson.bundles, // everything AssetPack generated locally
    {
      name: "audio", // pick a bundle name (see "Organizing into bundles" below)
      assets: [
        {
          alias: "bgm_cheerful",
          src: "https://your-cdn.example.com/audio/bgm_cheerful.wav",
        },
        {
          alias: "sfx_whoosh",
          src: "https://your-cdn.example.com/audio/sfx_whoosh.wav",
        },
      ],
    },
  ],
};

Popular CORS-friendly hosting options (see pixi-vn.com/start/assets#assets-hosting for the full comparison of price/limits/editability): GitHub raw URLs (https://raw.githubusercontent.com/[repo]/refs/heads/main/[path], free, 100MB/file limit), image-hosting services (imgbb/imgur, images only), or cloud storage (Cloudflare R2, Firebase Storage, S3, Supabase) for anything larger or non-image. Whichever host is used, it must allow CORS requests or the browser will block loading the asset.

Organizing assets into bundles

Group related assets into bundles instead of registering each one loosely — a bundle loads (or defers loading) as a single unit. Name each bundle after where it's used:

• a label's id (e.g. startLabel.id) for assets only that label needs
• a route's path (e.g. "/", "/game/narration") for assets a specific screen needs
• a character's id for that character's sprite/expression assets

This convention matters most for online assets, where it directly controls what the player waits for; for local assets (which load near-instantly) precise bundle boundaries matter far less.

// src/assets/index.ts
import { startLabel } from "@/content/labels/start.label";

export const manifest: AssetsManifest = {
  bundles: [
    { name: "/", assets: [{ alias: "background_main_menu", src: "..." }] }, // main menu route
    { name: startLabel.id, assets: [{ alias: "bg01-hallway", src: "..." }] }, // one label
    { name: "mc", assets: [{ alias: "mc-neutral", src: "..." }] }, // one character
  ],
};