Interactive Fiction

This guide shows how to create an interactive fiction project with Pixi’VN. The reader should feel as if they are reading a book: prose flows through paragraphs, and the player advances the story by reading, making choices, and following story links. Illustrations can appear between passages as vignettes.

Create a projectCopy Anchor Link

Install the prerequisites, then create a project:

npm create pixi-vn@latest

Select the Interactive Fiction template. Open the generated project in your IDE, install its dependencies, and start the development server:

npm install
npm start

For more information about project setup, VS Code tasks, and the generated project structure, see Templates.

Write the first passageCopy Anchor Link

The same Pixi’VN building blocks used in a visual novel also form an interactive fiction story. A label contains the ordered steps of a scene; each step can add a paragraph to the narration.

=== start ===
The rain had stopped by the time I reached the old station.
A light was still burning in the room above the ticket office.
-> DONE

The book-style interface keeps earlier paragraphs on the page while revealing the latest one. Use paragraph breaks to control the rhythm of the reading experience. To continue the same paragraph in the next step, use the glue feature: in Ink, start the next line with <>; in TypeScript, set narration.dialogGlue = true. For more on labels, dialogue, and story flow, see How to make a Visual Novel, Labels, and Dialogue.

Add choices and story linksCopy Anchor Link

Choices work the same way as in other Pixi’VN projects. They can jump to a new label or call a short passage and return to the current one.

=== start ===
The light upstairs flickered. What should I do?
* [Go inside]
    -> enter_station
* [Keep walking]
    -> leave_station

Use a jump (-> label in Ink, narration.jump(label, props) in TypeScript) to move the story forward to a new section. Use a call (<- label in Ink, narration.call(label, props) in TypeScript) for a digression that should return to its caller.

The Interactive Fiction template also renders links written in Markdown. A link whose target matches a registered label becomes an in-story link and jumps to that label; an ordinary URL remains an external link:

I unfolded the [note](read_note) and began to read.

In the template, MarkdownLink provides this behavior; it always jumps, never calls. If the reader must follow a link before continuing, use the template's # require link Ink command (or requireLinkClickToContinue() in TypeScript) in the same step as the link:

# require link
I unfolded the [note](read_note) and began to read.

These are template UI features, not built-in Pixi’VN rendering APIs. The lock is a storage flag that blocks every way of advancing (click, Space/Enter, skip, auto-play) and is cleared automatically when the link is followed.

See Choices and Narration flow control for the shared engine features.

Add vignette illustrationsCopy Anchor Link

The Interactive Fiction template's narration screen uses React and Markdown rather than arranging the story on the Pixi’VN canvas. Add an illustration in the flow of the book with standard Markdown image syntax:

The path climbed above the trees.
![The station on the hill at dusk](station_at_dusk)
The windows were dark, except for the light above the ticket office.

The template's MarkdownImage renderer displays the image as an illustration in the page. A registered Pixi’VN asset alias such as station_at_dusk is resolved to its asset URL; a regular image URL can also be used.

This inline image behavior belongs to the React template. Pixi’VN provides the narrative state and asset system; a custom interface needs its own Markdown image renderer to present vignettes. You can still use Pixi’VN's canvas in a project that intentionally adds a canvas-based scene, but the book layout does not depend on it.

For asset registration and loading, see Asset management.

Track chapters and use savesCopy Anchor Link

Use chapters to give the reader context and to label save slots. The Interactive Fiction template includes a helper that stores the current chapter name and counter in Pixi’VN storage:

=== start ===
# chapter chapter_the_station
The rain had stopped by the time I reached the old station.

Pass a translation key, so the chapter name can be translated when it is displayed. To read the values back, use the Ink variables chapter_counter and chapter_name, or getChapterCounter() and getChapterName() in TypeScript.

The template's save/load menu contains one quick-save slot and five manual slots. A save row can show its custom name or chapter, its date and time, and an excerpt from the latest dialogue.

Chapter tracking, the Ink commands, and the six-slot menu are template features. For Pixi’VN's save API, see Save and load.

Next stepsCopy Anchor Link

Interactive Fiction and Visual Novel projects share Pixi’VN's narrative engine. The book template changes the reading presentation: prose is the page, and illustrations can punctuate it as vignettes. Continue with the shared guides for Characters, Input, History, and Save and load.