drincs-productions/pixi-vn/getting-started

Pixi'VN skill index, 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. For the exact signature, parameters and types of any exported class, function or interface, use the generated JSDoc API reference: jsdocs.pixi-vn.com/pixi-vn.

Skill map: which skill to load

This is the index of the Pixi'VN skill set. Find the task below, then load the matching skill before writing code. Several tasks usually need more than one skill (e.g. a new scene: pixi-vn-narration + pixi-vn-characters + pixi-vn-canvas).

If none fits, or a task needs more detail than the skills cover, consult pixi-vn.com/llms.txt for the docs and the JSDoc API reference for exact signatures and types.

Companion packages

These are separate npm packages built on @drincs/pixi-vn; they are not covered by the skills above:

When a project uses one of these, load its skills (if any) in addition to the matching skill from the map; the plain-TypeScript skills in this set still apply to everything outside the ink/nqtr-specific parts.

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):

``bash 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 skill set (pixi-vn-ink, see Companion packages); 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. The "Point & Click Adventure" type is built on @drincs/nqtr, which has its own skill set (entry point nqtr, see Companion packages).

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

``bash 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:

``ts 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.

1. 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: