Pixi Vn Getting Started

Pixi'VN project initialization and the Game API

Official docs: pixi-vn.com/start. For a full machine-readable index of every Pixi'VN doc page — useful whenever a task needs more detail than this skill set covers — see pixi-vn.com/llms.txt.

When to use this skill

Use this skill whenever you are bootstrapping a Pixi'VN project from scratch, wiring up src/main.ts, or need to understand what Game.init/Game.start actually do before wiring narration, canvas, sound, storage, or history features. Every other Pixi'VN skill assumes Game.init has already run.

Installing the library

Two paths, depending on whether a project already exists:

• New project — scaffold from an official template (recommended for anything from scratch):

  npm create pixi-vn@latest

  This generates a working project (index.html, entry point, bundler config) already wired to call Game.init, with pre-built menu/narration screens, VS Code launch configs, and (since template v2.0.0) TanStack Router for navigation. See pixi-vn.com/start/templates for the full generated project structure, available templates/demos, and how to run/customize one.

  The wizard asks for a narrative language and defaults/suggests Ink + TypeScript (it's listed first and pre-selected in the prompt for the Visual Novel, Text-based Story, and Point & Click Adventure project types) — plain TypeScript narration (what every skill in this set documents) is the other option, selectable in the same prompt. Ink support is a separate narrative language with its own syntax and its own future skill; nothing in this skill set requires it.

  The wizard's first question is the project/game type; the docs have a dedicated getting-started walkthrough for some of them — pixi-vn.com/start/make-visual-novel for "Visual Novel", pixi-vn.com/nqtr/make-point-and-click for "Point & Click Adventure" — worth pointing a developer to the matching one for their project type, in addition to the general pixi-vn.com/start/templates page above.

• Existing JS/TS project — add the package directly:

  npm install @drincs/pixi-vn

Required peer dependencies

@drincs/pixi-vn does not bundle its own PixiJS/audio/animation stack — it declares compatible versions as peer dependencies (per package.json):

With npm 7+, npm install @drincs/pixi-vn auto-installs these peer dependencies too — no separate install step is needed in the common case. If a developer is on an older npm, or uses a package manager that doesn't auto-install peers (e.g. pnpm, or yarn in strict mode), they'll need to install them explicitly (npm install pixi.js pixi-filters tone motion @pixi/devtools). If a developer reports errors about missing modules like pixi.js, tone, or motion, check their package manager/version and whether these ended up installed before looking elsewhere.

Import paths: @drincs/pixi-vn vs subpaths

Every module (canvas, characters, history, narration, sound, storage, ...) is available both from the package root and from its own subpath, e.g. Game/canvas/sound all from @drincs/pixi-vn, or canvas alone from @drincs/pixi-vn/canvas. Default to importing from the root @drincs/pixi-vn — that's what every official doc example and template does:

import { canvas, Game, narration, sound, storage } from "@drincs/pixi-vn";

Reach for a narrower subpath (@drincs/pixi-vn/canvas, /sound, /characters, /storage, /narration, /core, /pixi.js, /motion) only when there's a concrete reason to avoid pulling in the whole package surface — e.g. a headless/server-side environment where canvas or sound isn't available or permitted, a size-constrained bundle target, or code that genuinely only ever touches one module. This applies to every skill in this set; it isn't repeated per-module.

Initializing the game: Game.init

Game.init must be called before any other Pixi'VN function (narration, canvas, sound, storage, history). It has two forms:

1. Full initialization — sets up the internal GameUnifier state manager and creates the PixiJS Application plus the canvas' interface <div>, attached to an HTML element:

   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 is Partial<ApplicationOptions> — i.e. every option accepted by a PixiJS Application (width, height, backgroundColor, antialias, ...) — plus three Pixi'VN-specific extras:
     • id: id of the generated canvas element.
     • navigate: the app's router navigation function (can also be set later with Game.onNavigate).
     • resizeMode: "contain" (fit within the parent, keep aspect ratio — default) or "none".
   • devtoolsOptions configures the PixiJS Devtools integration.

2. Headless initialization — Game.init() with no arguments. This initializes only the internal GameUnifier (storage, narration, history bookkeeping) without creating a PixiJS Application or canvas. Useful if you only need save/load, storage, or narration logic without rendering. If you call the 3-argument form but omit element/options, Game.init logs a warning and skips canvas setup the same way.

Complete example

The official docs' inline example calls .then() and wires Game.onNavigate as a separate statement (see pixi-vn.com/start); both that style and await are valid, and the navigate option can be passed inline instead of via a separate Game.onNavigate call. Here is the shape matching the current signature in src/index.ts:

// 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 internally calls Game.clear() first, so there is no need to call Game.clear() before it yourself.

props.navigate above is not a built-in Pixi'VN prop — it exists only because the project augmented StepLabelProps via declaration merging (typically in a pixi-vn.d.ts file, as every official template does). The same StepLabelProps type is used for the props passed to Game.onEnd, Game.addOnError, and every narration step, so whatever you add there (a navigate function, or any other custom prop) becomes available in all of them:

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

See also: pixi-vn.com/start/interface-navigate for the full navigation pattern (including the # navigate ink hashtag command and blocking the browser back/forward buttons). For the full set of fields the official React template actually adds this way (router navigate, i18n, toast, interface invalidation), see "Real-world project layout" below.

The Game.* functions

• Game.init(element?, options?, devtoolsOptions?) — must be called first; see above. Returns a Promise<void>.

• Game.start<T>(label, props) — clears all game data (Game.clear()) and begins narration from the given label (a LabelIdType string, or a LabelAbstract instance). Throws if the label isn't found.

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

• Game.clear() — resets everything: storage, canvas (if initialized), sound, narration, and history. Used to reset the game (e.g. returning to the main menu).

• Game.onEnd(value: StepLabelType) — registers the function run when all steps of all labels have been executed (no more steps/labels to continue into). Set it once during initialization. The docs note three common ending strategies: the game simply ends here; the game has no real end and this handler restarts/loops back into a label; or the game ends earlier at a specific point (e.g. game over) without ever relying on this handler.

  // end the game and navigate to an end screen
  Game.onEnd(async (props) => {
    props.navigate("/end");
  });

  // no real end: loop back into the start label instead
  Game.onEnd(async (props) => {
    narration.call(startLabel, props);
  });

  See also: pixi-vn.com/start/other-narrative-features#managing-the-end-of-the-game.

• Game.addOnError(handler: OnErrorHandler) — registers an error handler; multiple handlers can be added and run in registration order (sync or async). Returns a function that removes the handler. Check error instanceof PixiError (from @drincs/pixi-vn/core) to special-case Pixi'VN's own errors (e.g. missing assets). A companion helper, drawCanvasErrorHandler() (from @drincs/pixi-vn/canvas), returns a ready-made handler that draws a red placeholder box on the canvas when a PixiError carries canvas element info — useful during development to visualize broken canvas elements instead of silently failing.

  Game.addOnError((error, props) => {
    if (error instanceof PixiError) {
      // Pixi'VN-specific error (has error.code, maybe error.canvasElementInfo)
    }
    // any extra field on `props` (e.g. a `toast` helper for showing an error
    // notification) is only available if you added it to `StepLabelProps`
    // yourself — see the `navigate` example above, and the fuller
    // `toast`/`invalidateInterfaceData` example later in this skill.
  });

  Game.removeOnError(handler) unregisters a previously added handler.

• Game.onNavigate(value: (path: string) => void | Promise<void>) — registers (or replaces) the app's routing function, used whenever Pixi'VN needs to navigate (e.g. on Game.onEnd, or restoring a save). Equivalent to passing navigate inline to Game.init.

  Game.onNavigate((path) => router.push(path));

• Game.exportGameState() / Game.restoreGameState(data) / Game.jsonToGameState(json) — the save/load trio. Full detail, including the official template's save-slot/quick-save/IndexedDB convention, is covered by pixi-vn-saves.

• Narration lifecycle hooks — Game.onStepStart, Game.onStepEnd, Game.onLoadingLabel (fires on step 0 and on save-load — the hook a label uses to load/background-load its own asset bundle, see pixi-vn-assets), Game.onLabelStarting, and Game.onLabelClosing let you intercept/defer label transitions (e.g. to run a UI transition before the next label actually starts). These are advanced hooks — most projects only need onEnd.

• Game.addOnPreContinue(handler) / Game.removeOnPreContinue(handler) — register handlers that run immediately before every narration "continue" step (e.g. auto-save on each step).

Project structure

A typical Pixi'VN project (as generated by npm create pixi-vn@latest, or as set up manually):

index.html          # loads /src/main.ts as an ES module
src/main.ts          # calls Game.init(), Game.onEnd(), Game.addOnError(), Game.onNavigate(), Game.start()
styles.css           # full-viewport, no scroll/margin, dark background behind the canvas

The canonical minimal index.html mounts a root <div id="root"> that becomes (or contains) the element passed to Game.init, and loads the entry point as an ES module:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Game</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Paired with a styles.css that makes the canvas fill the viewport with no scrollbars or margin:

html,
body {
  background-color: #242424;
  height: 100%;
}

body {
  margin: 0;
  min-height: 100vh;
  display: flex;
  overflow: hidden;
}

Real templates generated by npm create pixi-vn@latest are richer than this minimal sketch: narrative content lives under ink/ (.ink scripts) and src/content/ (labels/*.label.ts, characters.ts), UI screens under src/components//src/routes/ (TanStack Router), and src/pixi-vn.d.ts is exactly where the StepLabelProps augmentation shown above lives. Full breakdown: pixi-vn.com/start/templates#project-structure.

Note also that Pixi'VN deliberately has no built-in UI components — buttons, menus, and HUD are built with a regular JS framework (React/Vue/PixiJS) layered over the canvas via canvas.htmlLayers.add/canvas.layers.add. Canvas state is included in saves; UI state is not, so persist any UI-only state yourself. See pixi-vn.com/start/interface.

A few constants worth knowing about (exported from @drincs/pixi-vn, defined in src/constants.ts): PIXIVN_VERSION (the installed library version, embedded in GameState.pixivn_version for save-file compatibility checks) and CANVAS_APP_GAME_LAYER_ALIAS (the alias of the root canvas layer). SYSTEM_RESERVED_STORAGE_KEYS lists storage keys Pixi'VN reserves internally (dialogue, choices, input, characters, etc.) — avoid reusing these names for custom storage variables.