Pixi’VN - PixiJS Visual Novel Engine

Pixi’VN is a very versatile and powerful 2D game 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
• Ren'Py

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.

• React
• Vue
• PixiJS

Wiki

• Why Pixi’VN?
  • Ren'Py vs Pixi’VN
• Quick Start
  • Templates
• Make your first:
  • Visual Novel
  • Point and Click adventure game
  • RPG game
  • Game engine

First steps

• Characters
• Narration:
  • Narration with ink:
    • Characters
    • Open a knot
    • Variables
    • Markup language (to add text style)
    • Input
    • Canvas
    • Sounds and Music
    • Assets management
    • Pause
    • Text replacement
    • Translating
    • Custom Hashtag Script
  • Narration with Ren’Py
  • Narration with JS/TS:
    • Dialogue
    • Label and Game Step
      • Game flow with labels
      • Label features
    • Choice Menus
    • Input prompt
    • History
    • Translating
    • Other features
  • Markup language (to add text style)
    • Markdown
    • Tailwind CSS
• Game canvas:
  • Canvas alias
  • Canvas Components
    • ImageSprite
    • ImageContainer
    • VideoSprite
    • Filters
    • Lights
    • Spine 2D
    • Three.js
  • Canvas functions
  • Position properties
  • Transitions
  • Animations and Effects
    • Primitives (ticker)
      • Tickers methods
    • Articulated
• Sounds and Music
• Assets
  • Assets management
• Game storage:
  • Flags Management
  • Stored Classes
• User Interface (UI)
  • JavaScript Frameworks
    • React
    • Vue
    • PixiJS
  • UI screen examples
  • Navigate/switch between UI screens
  • Connect the UI with the storage
• Save and Load
• Distribution
  • Website distribution
  • Desktop & mobile devices

Prerequisites

Before starting, you must have the following tools installed:

• Node.js version 18 or higher.
• Text editor with TypeScript support, such as:
  • Visual Studio Code
  • Cursor
  • VSCodium
• (Recommended) Git
  • A GitHub account

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 
npm create pixi-vn@latest  
# yarn 
yarn create pixi-vn
# pnpm 
pnpm create pixi-vn
# bun 
bun create pixi-vn
# deno
deno init --npm pixi-vn

You can see the list of available templates and interactive demos here.

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

All templates include a README.md file with more information about the project.

Example overview

The example shown is the template i Pixi’VN made in React.

For testing purposes we will recreate the visual novel Breakdown with Pixi’VN in this guide. Breakdown is a short story that has all the features that a visual novel should have. Josh Powlison, the creator of Breakdown, has given us permission to use his narration for educational purposes❤️.

The first page that appears is the main menu. From there, you can start the game, load a saved game, or go to the settings.

The game page is in /narration route. It contains the text box, character avatar, and canvas for the background image. The text box displays the text of the current dialogue. The character avatar displays the character speaking the dialogue. The background image is the background of the scene. When a choice has to be made, the choices are displayed at the top of the screen.

When you are in the game page, you can access with many features through a list of buttons located at the bottom. In this list you can save the game, load a saved game, skip the dialogue, auto play the dialogue, access to the history modal, and access to the settings modal.

The history modal is a list of all the dialogues and choices that have been displayed.

The settings modal allows you to change the text speed, go to full screen, edit theme colors, and change go to main menu. The settings for the audio have not been added nor the libraries to manage it, but I recommend adding them.

Keyboard shortcuts (hotkeys)

• Space or Enter: Continue the dialogue.
• Keep Space or Keep Enter: Skip the dialogue.
• Alt + S: Quick save the game.
• Alt + L: Quick load the game.
• Alt + H: Open the history modal.
• Esc: Open the settings modal.
• Alt + V: Hide the UI (Show only the canvas).

Used libraries

This template uses the following libraries:

Core libraries:

• Pixi’VN: A visual novel library.
• Vite: A build tool that aims to provide a faster and leaner development experience for modern web projects.
• Vite Checker: A Vite plugin that checks TypeScript types and ESLint on each build.
• PWA Vite Plugin: A Vite plugin that provides PWA support. This allows the possibility of installing the game as a Progressive Web App.
• Zustand: A small, fast, and scalable state management library.
• React Router: A library that provides routing for React applications.
• Tanstack Query: A library that provides a set of tools for getting, caching, and updating game data. 

UI libraries:

• Mui Joy: A React UI framework that provides a set of components and styles for building a website.
• Framer Motion: A simple yet powerful motion library for React.
• Notistack: A library that provides snackbar notifications for React.
• React Color Palette: A library that provides a color picker for React.

Text libraries:

• i18next: A library that gives the possibility to manage multiple translations in the application.
• Reacr Markdown: A library that allows you to render markdown in React components.