/assets

name: pixi-vn-assets
description: Use when adding, organizing, registering, or loading non-code files (images, audio, video) in a Pixi'VN project — local assets processed by PixiJS AssetPack vs. online/remote-hosted assets, the AssetsManifest/bundle/alias system, where to edit the manifest for each case, and when to load bundles (at startup, in the background, per-label, per-route). Load this before writing any code that references an image/sound/video path directly, or before adding entries to a manifest.

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

Official docs: [pixi-vn.com/start/assets](https://pixi-vn.com/start/assets) (storage options) and [pixi-vn.com/start/assets-management](https://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 | Online | | -------------------- | --------------------------------------------------------- | ------------------------------------- | | Bundled into the app | Yes — ships in `public/assets` | No — fetched at runtime from a URL | | Best for | Frequently used assets (backgrounds, sprites, core music) | Large/optional/rarely-used assets | | Requires | PixiJS AssetPack (pre-configured in official templates) | A CORS-enabled host with a public URL |

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](https://pixi-vn.com/start/assets#assets-hosting) for the full comparison of price/limits/editability): GitHub raw URLs (`https://raw.githubusercontent.com/[repo]/re