Pixi'VN Narration module

When to use this skill

Use this skill whenever the task is about the story itself: creating a new scene/label, writing a line of dialogue, adding a menu of player choices, branching a label's content based on game state, or driving story progression (starting the game, moving to the next step, calling/jumping between labels). This is the core engine of Pixi'VN — almost every "write a scene" or "add a choice" request touches this module.

Do not use this skill for: character definitions/appearance (see

pixi-vn-characters

), undo/go-back mechanics (see

pixi-vn-history

), save files (see

pixi-vn-saves

), or persistent game variables (see

pixi-vn-storage

Official docs for this module: https://pixi-vn.com/start/narration (overview), https://pixi-vn.com/start/labels and https://pixi-vn.com/start/labels-flow (labels/steps/flow), https://pixi-vn.com/start/labels-advanced (hooks, dynamic steps), https://pixi-vn.com/start/dialogue, https://pixi-vn.com/start/choices, https://pixi-vn.com/start/input.

Optional runtime AI:

@drincs/pixi-vn-ai

For dialogue or images generated during play, install the separate

@drincs/pixi-vn-ai

package and its required peers; import its

ai

singleton from that package. This API is experimental: check the installed types before implementing provider-specific options.

Await

ai.init(...)

once during startup. Without options it downloads a local WebLLM text model in the browser; image generation still needs an external provider. Configure

textProvider

and/or

imageProvider

for AI SDK models, or use

ComfyUIImageModel

from

@drincs/pixi-vn-ai/comfyui

with a ComfyUI API-format workflow for images.

In an async label step, generate the text and assign it to the usual dialogue state:

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

// Inside an async step, after startup has awaited ai.init(...):
narration.dialogue = await ai.text.generateDialog(
  "Describe the empty station as the last train leaves.",
  { scene: "A rural station at dusk", language: "English", history: true },
);

ai.image.generateBackground

and

ai.image.generateElement

generate scene imagery; the library builds prompts from the request and structured context. Consult the AI guide and plugin README for dependencies, provider configuration, image results, and display helpers before wiring images into canvas.

1. Defining a label

A label is the Pixi'VN equivalent of a Ren'Py "bookmark"/landmark in the story (the same concept is called a

knot

in the ink language): a container for an ordered list of steps (plain functions), each one run when the player advances the story. Labels are created with

newLabel

and are automatically registered so they can be referenced by id anywhere (choices,

narration.call

narration.jump

Game.start

import { narration, newLabel } from "@drincs/pixi-vn";

const startLabel = newLabel("start", [
  () => {
    narration.dialogue = "Welcome to the game!";
  },
  () => {
    narration.dialogue = { character: "liam", text: "Hi, I'm Liam." };
  },
]);

Key points:

```
newLabel(id, steps, props?)
```
—
```
id
```
must be unique across the whole game;
```
steps
```
is an array of
```
StepLabelType
```
functions, executed in order as the player continues;
```
props
```
is optional (
```
onStepStart
```
,
```
onStepEnd
```
,
```
onLoadingLabel
```
hooks — rarely needed for basic authoring).
Each step is
```
(props, { labelId }) => StepLabelResultType | Promise<StepLabelResultType>
```
. Steps can be
```
async
```
when they need to
```
await
```
something (e.g. calling another label, loading assets). Return value is optional — most steps return nothing (
```
void
```
); returning a string/object is only needed by code that consumes
```
StepLabelResultType
```
explicitly.
Every label file should call
```
newLabel(...)
```
at module scope so the label registers itself simply by being imported. Make sure the module gets imported somewhere reachable at startup.
```
steps
```
can also be a function that returns the array, e.g.
```
() => [...]
```
, which lets step content change dynamically based on game state — see "Conditional branching" below.

2. Dialogue

Set

narration.dialogue

inside a step to display a line. It accepts either a plain string/array of strings, or a

DialogueInterface

-shaped object with

text

and an optional

character

// Narrator line (no character)
narration.dialogue = "He thrusts out his hand.";

// A line with a speaker — character can be a registered character's string id...
narration.dialogue = {
  character: "james",
  text: `You're my roommate's replacement, huh?`,
};

// ...or the character object itself, e.g. imported from your characters module
narration.dialogue = { character: liam, text: "Hi, I'm Liam." };

Which form to prefer depends on the project's setup — see

pixi-vn-characters

for the full rationale, but in short: prefer the instance unless the

@drincs/pixi-vn/vite

plugin's

typeFilePath

generation (narrowing

CharacterIdType

to known ids, see

pixi-vn-getting-started

) is set up, in which case prefer the string-id form — it's just as typo-safe then, without needing to import the character module in every label file.

narration.dialogue

is a getter too: reading it returns

{ text, character }

(with

character

resolved to the full

CharacterInterface

when a registered id was used, or

undefined

/the raw string otherwise).

Gluing dialogue across steps: set

narration.dialogGlue = true

before assigning

narration.dialogue

in a step to have that line's text appended to the current dialogue text instead of replacing it. This lets a paragraph be split across several steps (each free to change a character's pose/sprite in between) while it reads to the player as one continuous block of text, with no waiting/empty-box flash in between. From the official React template (

src/content/labels/second.label.ts

async () => {
    await showImageContainer("steph", ["fm02-body", "fm02-eyes-joy", "fm02-mouth-smile00"]);
    narration.dialogue = `She enters my room before I'VE even had a chance to.`;
},
async () => {
    await showImageContainer("steph", ["fm02-body", "fm02-eyes-joy", "fm02-mouth-smile00"]);
    narration.dialogGlue = true;
    narration.dialogue = `\n\n...I could've just come back and gotten the platter later...`;
},

The player still advances one step at a time as usual (

dialogGlue

only affects how the text accumulates, not whether

continue()

/player input is needed); it resets automatically once a non-glued

narration.dialogue

assignment is made.

Character objects (

CharacterBaseModel

and registration via

RegisteredCharacters

) are covered by the

pixi-vn-characters

skill — this module only needs a character's

id

(or the object) to attach it to a line.

Docs: https://pixi-vn.com/start/dialogue

3. Rich text: Markdown and HTML in dialogue

Docs: pixi-vn.com/start/markup, markup-markdown, markup-tailwindcss.

Pixi'VN isn't tied to any markup language for

narration.dialogue

text, but Markdown is the recommended one, and Markdown can be freely mixed with raw HTML for anything Markdown itself can't express. Every official template already renders dialogue this way — in the React template specifically, via

react-markdown

with the

remark-gfm

(GFM tables/strikethrough/etc.) and

rehype-raw

(allows raw HTML inside the Markdown source) plugins:

tsx

import Markdown from "react-markdown";
import rehypeRaw from "rehype-raw";
import remarkGfm from "remark-gfm";

<Markdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeRaw]}>
  {narration.dialogue?.text}
</Markdown>;

When writing dialogue text, default to plain Markdown's classic inline styles —

*italic*

**bold**

, and similar simple emphasis — rather than reaching for raw HTML/CSS. Only use HTML (or anything fancier) when the user actually asks for it (e.g. a specific color, an animation, an underline a specific character always has):

narration.dialogue = "*She* was **not** amused.";

When HTML is asked for, the recommended CSS approach (per the docs) is Tailwind CSS — already installed and configured in every official template, optionally with plugins like

@tailwindcss/typography

tw-animate-css

, or

tailwind-animations

for richer text effects. A Tailwind-styled inline element inside dialogue text must be
inline-block
— a plain

inline

element won't apply

transform

/animation utilities correctly mid-paragraph:

narration.dialogue = `The night was <span class="inline-block animate-pulse text-violet-400">still</span>.`;

4. Choices

A choice menu is created by assigning an array to

narration.choices

, typically built with

newChoiceOption

(opens another label) and/or

newCloseChoiceOption

(just closes the menu and lets the current label's next step run).

import {
  narration,
  newChoiceOption,
  newCloseChoiceOption,
  newLabel,
} from "@drincs/pixi-vn";

const choiceLabel = newLabel("choice", [
  () => {
    narration.dialogue = "What do you choose?";
    narration.choices = [
      newChoiceOption("A", ALabel, {}), // default type is "call"
      newChoiceOption("B", BLabel, {}, { type: "jump" }),
      newCloseChoiceOption("Close"),
    ];
  },
  () => {
    narration.dialogue = "end";
  },
]);

```
newChoiceOption(text, label, props, options?)
```
—
```
text
```
is the option's label text;
```
label
```
is the target
```
Label
```
object or its string id;
```
props
```
are passed to the target label's steps (pass
```
{}
```
if none are needed);
```
options.type
```
is
```
"call"
```
(default — the target runs and can return to this label afterwards) or
```
"jump"
```
(the current label is closed first, no return).
```
newCloseChoiceOption(text, options?)
```
— closes the choice menu without opening any label; narration simply continues into the current label's next step.
```
options.closeCurrentLabel: true
```
additionally closes the current label when chosen.
Other
```
ChoiceInterface
```
options available in both:
```
oneTime
```
(option disappears once chosen),
```
onlyHaveNoChoice
```
(shown only as a fallback if every other option has been removed),
```
autoSelect
```
(if it ends up being the only available option, it's chosen automatically without player input).
Read
```
narration.choices.list
```
(a
```
StoredChoiceInterface[]
```
, an indexed array — each option carries a
```
choiceIndex
```
), and call
```
narration.choices.select(choice, props)
```
when the player picks one. Pass through any
```
StepLabelProps
```
the target label needs plus the option's own stored
```
props
```
:

const item = narration.choices.list![0];
await narration.choices.select(item, { ...item.props });

choices.select

dispatches to

narration.call

narration.jump

/closing the menu based on the chosen option's

type

, and records the pick so

narration.queries.alreadyCurrentStepMadeChoices

queries.timesChoiceMade

can reflect past choices (useful for

oneTime

options across replays).

Docs: https://pixi-vn.com/start/choices

5. Progressing and closing labels

Docs: https://pixi-vn.com/start/labels-flow

Start the game:
```
Game.start(label, props)
```
clears all game data and calls the given label — this is the standard entry point, e.g.
```
Game.start(startLabel, {})
```
.
```
label
```
can be the
```
Label
```
object itself (what the docs show) or its string id (
```
Game.start("start", {})
```
) — both work,
```
Game.start
```
is a thin wrapper around
```
narration.call
```
plus
```
Game.clear()
```
.
Advance one step:
```
await narration.continue(props)
```
runs the current label's next step. Guard advancing with
```
narration.canContinue
```
(false while a step is running, or a choice menu / required input is pending) — this is the shape a "next" button/handler should use:

while (narration.canContinue) {
  await narration.continue({});
}

Call a sub-label (like a function call — returns to the caller when it runs out of steps):
```
await narration.call(otherLabel, props)
```
. Can be used both to start the very first label and, from inside a step, to invoke a nested label. If you call it from inside a step, return the result and
```
await
```
it, so the history bookkeeping stays correct:

async (props) => {
  return await narration.call(otherLabel, props);
};

Jump to another label (closes the current label first, no return):
```
await narration.jump(otherLabel, props)
```
. Same rule applies —
```
return await narration.jump(...)
```
when called from within a step.
A label closes automatically once its steps are exhausted; the previously calling label (if any) resumes automatically. To close explicitly from within a step (e.g. after setting state), just
```
return
```
— Pixi'VN advances past the label's end on the next
```
continue()
```
. Use
```
narration.labels.closeCurrent()
```
/
```
narration.labels.closeAll()
```
only for lower-level manual stack control (
```
closeAll()
```
ends the game if nothing is called afterwards).
```
narration.labels.opened
```
and
```
narration.labels.current
```
reflect the current call stack of nested labels, useful for debugging/branching logic.
Going back a step is handled by the history module, not
```
narration
```
— see
```
stepHistory.back()
```
/
```
stepHistory.canGoBack
```
in the
```
pixi-vn-history
```
skill.

6. Input prompts

Docs: https://pixi-vn.com/start/input

To ask the player for a value (string, number, or an HTML element like a textarea), call

narration.input.request

inside a step; the engine will not let the story continue (

narration.canContinue

false

) until a value is provided by the UI:

() => {
    narration.dialogue = "What is your name?";
    narration.input.request({ type: "string" });
},
() => {
    narration.dialogue = `My name is ${narration.input.value}`;
},
() => {
    narration.dialogue = "How old are you?";
    narration.input.request({ type: "number" }, 18); // second arg is an optional default value
},

narration.input.request(info?, defaultValue?)

—

info

InputInfo

minus

isRequired

(e.g.

{ type: "string" }

{ type: "number" }

{ type: "html textarea" }

); omit it for a plain text input.

```
narration.input.isRequired
```
/
```
narration.input.type
```
tell the UI layer whether a prompt is pending and what kind, so it can render the right control.
```
narration.input.value
```
holds the submitted value once the UI resolves the prompt — read it in a later step to use what the player typed.
```
narration.input.removeRequest()
```
cancels a pending request without a value (rarely needed in normal authoring).

7. Conditional branching

Because

steps

can be a function, a label's content can change based on stored state — e.g. showing different dialogue on a repeat visit:

import { narration, newLabel, storage } from "@drincs/pixi-vn";

const talkAliceQuest = newLabel("talk-alice-quest", () => {
  if (storage.flags.get("test") === false) {
    return [
      () => {
        narration.dialogue = {
          character: "alice",
          text: "Hi, can you order me a book?",
        };
      },
      () => {
        narration.dialogue = { character: "mc", text: "Ok" };
      },
      async (props) => {
        storage.flags.set("test", true);
        await narration.continue(props);
      },
    ];
  }
  return [
    () => {
      narration.dialogue = { character: "alice", text: "Thanks for the book." };
    },
  ];
});

The function re-runs every time the engine needs to know the label's steps, so branch on stable storage flags/variables (see

pixi-vn-storage

) rather than on anything that changes mid-step. The last step in a branch can

await narration.continue(props)

itself if it wants to immediately auto-advance past a "setup" step instead of waiting for another player input.

8. Other useful narration bits

Docs: https://pixi-vn.com/start/other-narrative-features

```
Game.onEnd(async (props) => {...})
```
runs once every open label's steps are exhausted and nothing else is called — the standard place to navigate to an ending screen, or to
```
narration.call
```
/
```
jump
```
back into a menu/loop label if the game should never truly "end".
```
narration.getRandomNumber(...)
```
gives a seeded-safe random number (prefer this over raw
```
Math.random
```
so saves/rollback stay deterministic).
```
narration.queries.isLabelAlreadyCompleted(label | labelId)
```
checks whether a label has fully run before — handy for "seen this scene already" branching.
```
narration.currentStepTimesCounter
```
counts how many times the current step has executed (only increments when actually read, and only once per step execution); set it to
```
0
```
to reset. Useful for "show this the first time only" logic inside a dynamic step-list function.

9. Real-world project convention (official React template)

The library itself doesn't mandate any file layout or UI wiring — the points below are how

npm create pixi-vn@latest

's official "TS narration + React" template does it, as seen in

pixi-vn-react-template

. Treat this as one convention worth following/recognizing, not a hard requirement: other narration styles (e.g. an ink-based project) will have their own skill and their own conventions.

File layout: each scene lives in its own

src/content/labels/<name>.label.ts

, exporting a

newLabel(...)

result (e.g.

second.label.ts

exports

secondPart = newLabel("second_part", [...])

). Character definitions live alongside under

src/content/characters/

Auto-registration:
```
src/content/index.ts
```
does
```
import.meta.glob(["./**/*.ts", "!./index.ts"], { eager: true })
```
(a Vite feature) to eagerly import every module under
```
content/
```
for its side effects at startup. Since
```
newLabel
```
/character registration runs at module scope, a new label file just needs to exist under
```
content/
```
— no manual import list to maintain.

Driving narration from the UI (see

lib/hooks/narration-hooks.ts

and

lib/query/narration-query.ts

): a "next" handler guards on

narration.canContinue

before calling

await narration.continue(gameProps)

; a choice handler reads

narration.choices.list

and calls

await narration.choices.select(item, gameProps)

; an input prompt reads

narration.input.isRequired

narration.input.type

narration.input.value

. Real code wraps all three in a loading-state guard (e.g. a

GameStatus.setLoading(true/false)

store) so double-clicks can't fire concurrent

continue()

choices.select()

calls, and a combined

narration.canContinue && !narration.input.isRequired

is a convenient "can the player press next" check for enabling/disabling a next button.

```
gameProps
```
above is just that project's augmented
```
StepLabelProps
```
(translation function, router navigate, toast, etc., declared via TS module augmentation in
```
pixi-vn.d.ts
```
) — it's plain application data, not something the narration module requires.

Related skills

pixi-vn-getting-started, pixi-vn-characters, pixi-vn-history, pixi-vn-storage

pixi-vn-narration

NPX Install

Tags

SKILL.md Content