Pixi’VN template (React + Vite + MUI joy)

This is a template for creating visual novels in React. It uses the Pixi’VN library and Vite as a build tool. This Template contains basic functionality inspired by the widespread Visual Noval engine Ren'Py.

Overview

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.

How to use

Before starting, you need to have Node.js installed on your computer. If you don't have it, you can download it here.

Recommended Visual Studio Code extensions

• JavaScript and TypeScript Nightly: Provides JavaScript and TypeScript nightlies.
• ESLint: Integrates ESLint into VS Code.
• vscode-color-picker: A color picker for Visual Studio Code.
• Version Lens: Shows the latest version for each package using code lens.
• Ink: Syntax highlighting for the Ink language.

Change the icon

You can change the icon of the game by replacing the images in the public folder.

Writing/testing the narrative with Inky

To write and test the narrative, you can use the Inky editor. Inky is a tool for writing interactive fiction using the Ink language. Of course, the special features introduced by pixi-vn will not be ignored by Inky. You can download it here.

To use Inky with this template, you can open the src/main.ink file in Inky. Ricorda che quando Importi nuovi file con Inky devi anche importarli in usando TypeScript:

// main.ink
INCLUDE ink_labels/start.ink
INCLUDE ink_labels/second.ink
-> start

// utilities/ink-utility.ts
import { importInkText } from '@drincs/pixi-vn-ink';
import startLabel from '../ink_labels/start.ink?raw';
import secondLabel from '../ink_labels/second.ink?raw';

export async function importAllInkLabels() {
    await importInkText([startLabel, secondLabel])
}

Installation

First, is necessary install the dependencies. To do this, open a terminal in the root folder of the project and run the following command:

npm install

Start the web application

To start the web application, run the following command:

npm start

This command will start the development server. Open http://localhost:5173 to view it in the browser.

Debugging the web application

If you are using Visual Studio Code, you can use the debug configuration provided with the template. To do this, after launching npm start, go to the debug section and select the Launch Chrome configuration.

Keyboard shortcuts (hotkeys)

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

Custom hashtag scripts

By using the onInkHashtagScript function, in this template the following features have been added.

Moving between screens: This feature allows you to navigate between different screens. The syntax is as follows:

# + navigate + [route]

route: The route/path to navigate to. Read more about routes in the Router documentation.

#navigate /narration

Rename the character: This feature allows you to change the name of the character speaking. The syntax is as follows:

# + rename + [character id] + [new name]

Used libraries

This template uses the following libraries:

Core libraries:

• Pixi’VN: A visual novel library.
• Pixi’VN - Ink Integration: A library that provides integration with the Ink language.
• 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.
• Recoil: A state management library for React.
• 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. You can use the following button to show Tanstack Query interactions with the game. (the button will be automatically hidden when released)

UI libraries:

• Mui Joy: A React UI framework that provides a set of components and styles for building a website.
• 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.

Distribution

Web application

To build the project, run the following command:

npm run build

This command will create a dist folder with the files necessary to run the application. You can deploy this folder to a web server.

You can read more about the possibilities of hosting in the Pixi’VN documentation.