Function: vitePluginPixivn()

> vitePluginPixivn(options?): Plugin

Defined in: src/vite/plugins.ts:420

Creates a Vite plugin for Pixi'VN integration.

Static content loading

When VitePluginPixivnOptions.content, VitePluginPixivnOptions.characters, or VitePluginPixivnOptions.labels are provided, the matched files are executed server-side via Vite SSR at startup, populating RegisteredCharacters, RegisteredLabels, and any other singletons before downstream plugins (such as vitePluginInk) run — including during vite build.

Auto-generated type file

When VitePluginPixivnOptions.typeFilePath is provided, the plugin writes a TypeScript declaration file that augments PixivnCharacterIds in @drincs/pixi-vn/characters and PixivnLabelIds in @drincs/pixi-vn/narration with all currently known IDs. This narrows CharacterIdType and LabelIdType from string to unions of known literals, giving compile-time safety for character lookups, narration.call, narration.jump, etc.

The file is regenerated whenever the character or label set changes (content reload or external-label updates). It is excluded from HMR so regenerating it never triggers a page reload.

Auto-generated worker file

When VitePluginPixivnOptions.workerFilePath is provided, the plugin writes a Worker entry file wired to handleGameWorkerMessage from @drincs/pixi-vn/worker - see that option's doc comment for what it's for (Game.worker.register(...)) and how to import it. Written once (its content never changes), not regenerated on the triggers above. Add VitePluginPixivnOptions.autoRegisterWorker to also skip the manual Game.worker.register(...) call - the plugin creates and registers the worker itself.

Auto-generated list file

When VitePluginPixivnOptions.listFilePath is provided, the plugin writes a TypeScript file that exports runtime as const arrays of all currently known IDs: characterIds and labelIds. These arrays can be used for runtime validation (e.g. z.enum(characterIds)) and are regenerated on the same triggers as the type file.

Asset bundles / aliases

When a PIXI.js AssetsManifest is registered — via VitePluginPixivnOptions.assetsManifest or, for manifests produced by an async asset pipeline, api.setAssetsManifest(manifest) — the same VitePluginPixivnOptions.typeFilePath also gets export const bundleIds / export const assetAliasIds (as const arrays) plus declare module augmentations for PixivnBundleIds / PixivnAssetAliasIds in @drincs/pixi-vn/canvas — narrowing that module's BundleIdType / AssetAliasIdType from string to unions of known literals, exactly like PixivnCharacterIds / PixivnLabelIds narrow CharacterIdType / LabelIdType above. The manifest also immediately backs the GET /__pixi-vn/assets/manifest endpoint below.

External label providers

Other Vite plugins can inject label IDs via the plugin API without needing to register them through SSR-loaded modules:

• api.setExternalLabels(providerId, labels) — registers (or replaces) the label list for the given provider and regenerates the type file.
• api.clearExternalLabels(providerId) — removes all labels for the given provider and regenerates the type file.

Dev-server HTTP endpoints

• GET /__pixi-vn/characters — retrieve registered characters
• POST /__pixi-vn/characters — (deprecated) update from client; use the characters option instead
• GET /__pixi-vn/labels — retrieve narration labels
• POST /__pixi-vn/labels — (deprecated) update from client; use the labels / content option instead
• GET /__pixi-vn/assets/manifest — retrieve PIXI assets manifest (immediately available when the assetsManifest option is set or api.setAssetsManifest has been called; otherwise 404 until a client POST)
• POST /__pixi-vn/assets/manifest — (deprecated) update from client; use the assetsManifest option instead
• GET /__pixi-vn/canvas-options — retrieve canvas rendering options
• POST /__pixi-vn/canvas-options — update canvas options from client

Plugin API (consumed by vitePluginInk):

• api.contentLoaded — Promise<void> that resolves once all content modules have finished loading. Await this before generating JSON files.
• api.characters — the list of registered characters (populated after contentLoaded).
• api.onReload(cb) — register a callback that fires after every hot-content-reload.
• api.setExternalLabels(providerId, labels) — add/replace labels from an external provider.
• api.clearExternalLabels(providerId) — remove labels previously set for a provider.
• api.setAssetsManifest(manifest) — register/replace the assets manifest after plugin-creation time (e.g. once an async asset pipeline finishes); see VitePluginPixivnOptions.assetsManifest.

Parameters

options?

VitePluginPixivnOptions

Optional plugin configuration.

Returns

Plugin

A Vite plugin.

Example

// vite.config.ts
import { defineConfig } from "vite";
import { vitePluginPixivn } from "@drincs/pixi-vn/vite";

export default defineConfig({
  plugins: [
    vitePluginPixivn({
      content: "./src/content/index.ts",
      typeFilePath: "./src/pixi-vn.gen.d.ts",
    }),
  ],
});