pixi-vn-ink-assets

用途

pixi-vn-ink-assets 用于在 ink 剧本的 knot 运行之前或运行期间，加载或延迟加载图片、音频、视频等资源或整个资源包。它只负责从 ink 中触发加载，前提是资源清单（manifest）已经在 JS/TS 中初始化。

官方文档：pixi-vn.com/ink/assets。该技能要求 addBaseHashtagCommands() 已运行（其 assets 部分默认开启），参见 pixi-vn-ink。

适用时机

当某个 knot 需要确保图片、视频、音频资源（或整个 bundle）在显示前已加载，或者希望在不阻塞当前步骤的情况下在后台开始加载（例如在当前场景播放时预热下一场景的资源）时使用。

阻塞式加载

# load assets eggHead flowerTop
# load bundle main_menu

语法为 # load <assets|bundle> <alias...>，会在标签继续进入下一步之前等待加载完成。assets 使用 Assets.load 加载；bundle 使用 Assets.loadBundle 加载。别名列表以空格分隔，每一项要么是资源别名或 URL（assets），要么是 bundle 名称（bundle），它们都来自在 JS/TS 中初始化的清单。

后台延迟加载

# lazyload bundle main_menu
# lazyload assets my_video

语法相同，但资源或 bundle 会在后台加载（Assets.backgroundLoad / Assets.backgroundLoadBundle），当前步骤不等待它完成。可用于在玩家阅读当前场景时，预先加载后续场景所需的内容。

限制为已知 ID

addBaseHashtagCommands({ bundleIds, assetAliasIds })：传入 bundleIds/assetAliasIds（通常由 vitePluginPixivn 的 typeFilePath 生成）后，# load/# lazyload 会在解析时对照该已知列表校验别名，而不再接受任意字符串。这样拼错的别名会在 Vite 开发服务器日志中以“unknown hashtag command”警告的形式出现（参见 pixi-vn-ink），而不会静默失败或仅在运行时失败。

import { assetAliasIds, bundleIds } from "@/pixi-vn.keys.gen";
import { addBaseHashtagCommands } from "@drincs/pixi-vn-ink";

addBaseHashtagCommands({ bundleIds, assetAliasIds });

URL 转义

// 在 ink 中会开始注释，因此 hashtag 指令中的字面 https:// 必须转义为
https:\/\/ —— 否则该行 // 之后的内容会被静默丢弃：

# load assets https:\/\/raw.githubusercontent.com\/example\/repo\/refs\/heads\/main\/bg.png

建议在清单中为资源注册别名，并从 ink 中引用该别名，而不是内联原始 URL。这样可以完全避免转义问题，并与所有官方模板保持一致。

完整示例

=== start ===
# lazyload bundle main_menu start
# load assets eggHead flowerTop my_video
# show image eggHead
# show image flowerTop
# show video my_video
# pause
-> start

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: "..." },
      ],
    },
  ],
};

技能介绍

用途