pixi-vn-cover

Pixi’VN is a very versatile and powerful story-driven engine. It is based on JavaScript/TypeScript and PixiJS.

It provides the following features:

narrative management
provides a 2D canvas
providing functionality to play sounds and music
storage to set and get game variables.
saves the current state of the entire game at each "story step" giving the possibility to go back
functionality to save and load the current state of the game.

For a quick start, various project templates are available. Less experienced developers can use these templates without much knowledge of JavaScript/TypeScript.

You have the option to use various types of narrative languages (in addition to JavaScript/TypeScript). Currently you can use the following:

ink

Pixi’VN does not provide built-in components to create the game UI. Instead, you should use external JavaScript frameworks to build your UI. This allows you to leverage systems such as React, Vue, etc., to create complex and high-performance UI screens.

Wiki

Prerequisites

Before starting, you must have the following tools installed:

Node.js version 18 or higher.
Text editor with TypeScript support, such as:

Project Initialization

If you want to start from a new project, you can use the following command to initialize a new project with the Pixi’VN templates:

npm create pixi-vn@latest

You can see the list of available templates and interactive demos <DynamicLink href="/start/templates">here.

After the project is initialized, open the project directory with your text editor (VSCode is recommended) and start developing your project.

Installation

To install the Pixi’VN package in an existing JavaScript project, use one of the following commands:

npm install @drincs/pixi-vn

Initialize

Before using the Pixi’VN engine, you must initialize the game. You can do this by calling the Game.init method.

src/main.tsx

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

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

Game.init(body, {
  height: 1080,
  width: 1920,
  backgroundColor: "#303030",
}).then(() => {
  // ...
  Game.start("start", {});
});

// read more here: https://pixi-vn.com/start/other-narrative-features.html#how-manage-the-end-of-the-game
Game.onEnd(async (props) => {
  Game.clear();
  // navigate to main menu
});

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

Game.onNavigate((path) => navigateTo(path));

index.html

<!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>

styles.css

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

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

Agent Skills

Pixi'VN ships a set of Agent Skills that teach AI coding assistants (like Claude Code) how to correctly use each part of the engine. If you use Claude Code, you can install all of them into your project with:

npx skills add DRincs-Productions/pixi-vn

This installs every skill below and prompts you to pick which ones to keep. To install only specific ones, add --skill <name> (repeat the flag to install several, e.g. --skill canvas --skill sound). Use --list instead of installing to just see what's available. Available skills:

getting-started — installing the package and initializing the Game
assets — local vs. online assets, the manifest/bundle/alias system, and loading strategy
canvas — images, sprites, text, video, transitions and effects
characters — defining and registering characters
history — going back/rewinding and reading the narration backlog
narration — labels, dialogue and choices
saves — exporting/restoring game state and persisting save files
sound — music, sound effects and audio channels
storage — game variables, flags and stored classes
ui — mounting HTML/PixiJS UI layers over the canvas, screen navigation, theming, and connecting UI to storage
migration — upgrading an existing project to the current version

Pixi’VN - PixiJS Game Engine