LogoPixi’VN
Narration/Narration with JS/TS

Labels and steps

Explains the core concepts of labels and steps in Pixi'VN, detailing how narrative flow is structured and managed within the engine.

Visual novels are typically a sequence of scenes with images and text.

Nomenclature

The term label is borrowed from Ren'Py, where it acts as a "bookmark" or "landmark" in the story. In the ink language, the equivalent term is knot.

The term step is introduced by Pixi'VN to represent the individual actions or events that occur within a label.

In Pixi’VN, the entire narrative flow is based on the concepts of labels and steps.

A label is used to organize the narrative; it works as a "bookmark" or section of the story. Technically, a label is a class that acts as a container for steps.

A step is an individual action or event that occurs within a label. Steps are used to display images, text, and other narrative elements.

The basic lifecycle of the game is as follows:

  • The game starts by calling a label. The first step of the label is executed automatically.
  • After that, by connecting the Next Step function to an event (such as a button click), each time the function is called, the next step of the label is executed. Some steps can also start other labels.
  • The game ends only when all steps are completed. At that point, the Game.onEnd function is triggered.

Add

To create a label, use the newLabel() function. This function has the following parameters:

  • id: A unique identifier (string). Used to reference the label in the game (must be unique).
  • steps: An array of functions to be executed in order. To create a dynamic array, you can find more information here.
  • options (Optional): An object with the label's options:
    • onStepStart (Optional): A function executed before each step. See more here.
    • onStepEnd (Optional): A function executed after each step. See more here.
    • onLoadingLabel (Optional): A function executed in onStepStart if the step index is 0, or when loading a save file. See more here.
labels/startLabel.ts
import { narration, StepLabelProps } from '@drincs/pixi-vn'

export const startLabel = newLabel("start_label",
    [
        () => {
            narration.dialogue = { character: liam, text: "Example of dialogue" }
        },
        (props: StepLabelProps, { labelId }) => narration.jumpLabel(labelId, props),
    ]
)

On this page