Download the exact captured file
---
name: pixi-vn-ink-assets
description: "Use when an ink script needs to load or lazy-load images, audio, video, or an asset bundle before/while a knot runs, via # load and # lazyload. Part of the pixi-vn-ink skill set — install alongside pixi-vn-ink."
---
# Assets from ink
Official docs: [pixi-vn.com/ink/assets](https://pixi-vn.com/ink/assets). Requires
`addBaseHashtagCommands()` to have run (its `assets` section, on by default) — see
**pixi-vn-ink**. Assumes the [asset
manifest](https://pixi-vn.com/start/assets-management#initialize-the-asset-matrix-at-project-start) is
already initialized in JS/TS — this only covers triggering a load from ink.
## When to use this skill
Use whenever a knot needs to guarantee an image/video/audio asset (or a whole bundle) is loaded before
showing it, or wants to start loading something in the background without blocking the current step
(e.g. pre-warming the next scene's assets while the current one plays).
## Load (blocking)
```ink
# load assets eggHead flowerTop
# load bundle main_menu
```
`# load <assets|bundle> <alias...>` — awaited before the label continues to its next step.
`assets` loads with `Assets.load`; `bundle` loads with `Assets.loadBundle`. The alias list is
space-separated; each entry is either an asset alias/URL (`assets`) or a bundle name (`bundle`), from
the manifest initialized in JS/TS.
## Lazyload (background)
```ink
# lazyload bundle main_menu
# lazyload assets my_video
```
Same syntax, but `assets`/`bundle` load in the background (`Assets.backgroundLoad` /
`Assets.backgroundLoadBundle`) — the current step does **not** wait for it. Use this to start loading
what a *later* scene will need while the player is still reading the current one.
## Restricting to known ids
`addBaseHashtagCommands({ bundleIds, assetAliasIds })` — passing `bundleIds`/`assetAliasIds` (typically
the arrays [`vitePluginPixivn`'s `typeFilePath` generates](https://pixi-vn.com/start#the-vite-plugin-drincspixi-vnvite))
makes `# load`/`# lazyload` validate the alias against that known list at parse time instead of
accepting any string — a typo'd alias then surfaces as an "unknown hashtag command" warning in the Vite
dev-server log (see **pixi-vn-ink**) instead of failing silently or only at runtime.
```ts title="content/ink/hashtag-commands.ts"
import { assetAliasIds, bundleIds } from "@/pixi-vn.keys.gen";
import { addBaseHashtagCommands } from "@drincs/pixi-vn-ink";
addBaseHashtagCommands({ bundleIds, assetAliasIds });
```
## Escaping URLs
`//` starts a comment in ink, so a literal `https://` inside a hashtag command must be escaped as
`https:\/\/` — otherwise everything after `//` on that line is silently dropped:
```ink
# load assets https:\/\/raw.githubusercontent.com\/example\/repo\/refs\/heads\/main\/bg.png
```
Prefer registering the asset under an alias in the manifest and referencing that alias from ink instead
of inlining a raw URL — it sidesteps the escaping entirely and matches every official template.
## Complete example
```ink title="ink/start.ink"
=== start ===
# lazyload bundle main_menu start
# load assets eggHead flowerTop my_video
# show image eggHead
# show image flowerTop
# show video my_video
# pause
-> start
```
```ts title="src/assets/index.ts"
import generatedManifestJson from "@/assets/manifest.gen.json";
import type { AssetsManifest } from "@drincs/pixi-vn";
export const manifest: AssetsManifest = {
bundles: [
...generatedManifestJson.bundles,
{ name: "main_menu", assets: [{ alias: "background_main_menu", src: "..." }] },
{ name: "start", assets: [{ alias: "bg01-hallway", src: "..." }] },
{
name: "images",
assets: [
{ alias: "eggHead", src: "..." },
{ alias: "flowerTop", src: "..." },
],
},
],
};
```
## Related
- **pixi-vn-ink-canvas** and **pixi-vn-ink-sound** — showing/playing the assets loaded here.
- [pixi-vn.com/start/assets-management](https://pixi-vn.com/start/assets-management) — initializing the
manifest in JS/TS, bundles vs. individual assets, and the full loading-strategy discussion.