/narration

name: pixi-vn-narration
description: Use when writing or editing Pixi'VN story content — defining labels (scenes) with newLabel, writing dialogue steps, adding player choices with newChoiceOption/newCloseChoiceOption, conditional/branching labels, or wiring up narration.call/jump/continue and Game.start to progress the story.

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](https://pixi-vn.com/start/ai-generated-content) and [plugin README](https://github.com/DRincs-Productions/pixi-vn-ai) for dependencies, provider configuration, image results, and display helpers before wiring images into canvas. For exact signatures and types, see the plugin's JSDoc reference: [jsdocs.pixi-vn.com/pixi-vn-ai](https://jsdocs.pixi-vn.com/pixi-vn-ai).

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`) 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 st