pixi-vn-getting-started

Pixi'VN 项目初始化与 Game API

官方文档：pixi-vn.com/start。若任务需要比本技能更完整的机器可读文档索引，可查看 pixi-vn.com/llms.txt。

适用场景

在从头搭建 Pixi'VN 项目、编写 src/main.ts、或需要理解 Game.init/Game.start 的作用（再接旁白、画布、声音、存储、历史）时使用。其它 Pixi'VN 技能都假定 Game.init 已执行。

安装

新项目（推荐）：npm create pixi-vn@latest。该命令生成可运行项目（index.html、入口点、打包配置），已接入 Game.init，并含预置菜单/旁白界面、VS Code 启动配置，模板 v2.0.0 起使用 TanStack Router 导航。向导会询问叙事语言，默认推荐 Ink + TypeScript，也可选纯 TypeScript 叙事。模板结构详见 pixi-vn.com/start/templates。

已有 JS/TS 项目：npm install @drincs/pixi-vn。

必需 peer 依赖（package.json 声明）：pixi.js >=8.17.0；pixi-filters >=6.1.0；tone >=15.1.0（声音模块音频引擎）；motion >=12.38.0（画布动画）；@pixi/devtools >=2.0.0；vite >=5.0.0（可选，仅在用 Vite 时）。npm 7+ 会自动安装 peer 依赖；pnpm、严格模式 yarn 或旧版 npm 需显式安装。若报 pixi.js、tone、motion 缺失，先检查包管理器与 peer 依赖是否装上。

导入路径

所有模块既可从包根导入，也可从子路径导入。默认从根导入：import { canvas, Game, narration, sound, storage } from "@drincs/pixi-vn";。仅在有明确理由（无头/服务端环境、体积受限、只用单一模块）时才用子路径（/canvas、/sound、/characters、/storage、/narration、/core、/pixi.js、/motion）。

初始化：Game.init

必须在调用任何其它 Pixi'VN 函数前调用。两种形式：

完整初始化——创建内部 GameUnifier 状态管理器、PixiJS Application 与画布 interface <div>，挂载到 HTML 元素：

export async function init( element: HTMLElement, options: Partial<ApplicationOptions> & { id?: string; // default: "pixi-vn-canvas" navigate?: (path: string) => void | Promise<void>; resizeMode?: "contain" | "none"; // default: "contain" }, devtoolsOptions?: Devtools, ): Promise<void>;

options 支持全部 PixiJS Application 选项（width、height、backgroundColor、antialias 等），外加 id、navigate（也可之后用 Game.onNavigate 设置）、resizeMode（默认 "contain"）。devtoolsOptions 配置 PixiJS Devtools 集成。

无头初始化——Game.init() 无参调用，只初始化 GameUnifier（存储、旁白、历史），不创建 Application 与画布，适合只需存/读档与旁白逻辑、不需渲染的场景。

完整示例（src/main.ts）：

import { Game } from "@drincs/pixi-vn";

const body = document.body; if (!body) { throw new Error("body element not found"); }

await Game.init(body, { width: 1920, height: 1080, backgroundColor: "#303030", resizeMode: "contain", navigate: (path) => { // e.g. window.history.pushState({}, "", path) }, });

Game.onEnd(async (props) => { Game.clear(); props.navigate("/end"); });

Game.addOnError((error, props) => { console.error("Error occurred", error); });

await Game.start("start", {});

Game.start 内部先调用 Game.clear()，无需自行调用。props.navigate 非内置，需通过声明合并扩展 StepLabelProps（通常在 pixi-vn.d.ts）：

declare module "@drincs/pixi-vn" { interface StepLabelProps { navigate: (route: string) => void; } }

同一 StepLabelProps 用于 Game.onEnd、Game.addOnError 与各旁白步骤的 props。导航完整模式见 pixi-vn.com/start/interface-navigate。

Game.* 函数

Game.init(element?, options?, devtoolsOptions?)：须首先调用，返回 Promise<void>。
Game.start<T>(label, props)：先清空数据（Game.clear()），从指定标签开始旁白；标签不存在则抛错。
Game.clear()：重置存储、画布（若已初始化）、声音、旁白与历史。
Game.onEnd(value)：注册所有标签步骤执行完毕时运行的回调。常见策略：直接结束；无真实结局则循环回起点；或在特定点（如游戏结束）自行结束。
Game.addOnError(handler)：注册错误处理，可多个，按注册顺序同步或异步执行，返回移除函数；可用 error instanceof PixiError（来自 @drincs/pixi-vn/core）区分 Pixi'VN 自身错误；drawCanvasErrorHandler()（来自 @drincs/pixi-vn/canvas）可在画布上绘制红色占位框，便于开发期定位坏元素。
Game.removeOnError(handler)：注销处理器。
Game.onNavigate(value)：注册或替换路由函数，等价于在 Game.init 中传 navigate。
Game.exportGameState() / Game.restoreGameState(data) / Game.jsonToGameState(json)：存/读档三件套，详见 pixi-vn-saves。
旁白生命周期钩子：Game.onStepStart、onStepEnd、onLoadingLabel（步骤 0 与读档时触发，用于加载标签资源包）、onLabelStarting、onLabelClosing，可拦截/延迟标签切换；多数项目只需 onEnd。
Game.addOnPreContinue(handler) / Game.removeOnPreContinue(handler)：注册每次旁白"继续"前运行的处理器（如自动存档）。

项目结构

典型结构：index.html 以 ES 模块加载 /src/main.ts；src/main.ts 调用 Game.init()、Game.onEnd()、Game.addOnError()、Game.onNavigate()、Game.start()；styles.css 让画布全屏、无滚动条、带深色背景。

最小 index.html 含挂载点 <div id="root"></div> 并以 <script type="module" src="/src/main.ts"></script> 加载入口。styles.css 示例：html, body { background-color: #242424; height: 100%; } body { margin: 0; min-height: 100vh; display: flex; overflow: hidden; }

官方模板更完整：叙事内容位于 ink/（.ink 脚本）与 src/content/（labels/*.label.ts、characters.ts），UI 位于 src/components/、src/routes/（TanStack Router），src/pixi-vn.d.ts 即 StepLabelProps 扩展位置。

注意：Pixi'VN 不内置 UI 组件，按钮、菜单、HUD 需用普通 JS 框架（React/Vue/PixiJS）通过 canvas.htmlLayers.add / canvas.layers.add 叠加于画布；画布状态会进存档，UI 状态不会，需自行持久化。

常量：PIXIVN_VERSION（已安装版本，写入 GameState.pixivn_version 用于存档兼容检查）、CANVAS_APP_GAME_LAYER_ALIAS（根画布层别名）；SYSTEM_RESERVED_STORAGE_KEYS 列出内部保留存储键（dialogue、choices、input、characters 等），自定义存储变量避免重名。

Vite 插件：@drincs/pixi-vn/vite

官方模板均在 vite.config.ts 接入 vitePluginPixivn。作用：启动时经 Vite SSR 在服务端加载 content/characters/labels，确保 RegisteredCharacters/RegisteredLabels 在使用前已注册；生成类型安全 ID 联合（CharacterIdType、LabelIdType、BundleIdType、AssetAliasIdType），使 narration.call("typo_label") 编译报错，并导出 as const 数组/枚举供运行时校验；桥接 PixiJS 资源清单（assetsManifest），向生成的类型文件提供 bundle/资源别名 ID，并提供开发端点 GET /__pixi-vn/assets/manifest。当标签 ID 无自动补全/类型检查，或询问角色/标签如何免手动导入即生效时，应使用该插件。

技能介绍