Pixi Vn History

Pixi'VN History module

Official docs: https://pixi-vn.com/start/history — this skill also documents goBackMode and the real-world go-back/backlog patterns not detailed on the public page. It sticks to the public stepHistory API a game actually calls, not how it's implemented internally.

When to use this skill

Load this skill whenever a task involves: letting the player undo the last line(s) of dialogue ("go back" / "rewind" button), reading/rendering the narration backlog (a "history log" or "scrollback" panel), deciding how much can be undone after a save/load, or tuning how coarse/fine-grained "going back" feels (line-by-line vs paragraph-by-paragraph).

Mental model

Every time narration advances one step, Pixi'VN records that moment so the player can later go back to it. stepHistory is the module/singleton that manages these recorded steps: going back to an earlier one, and reading back what was shown at each one (for a backlog/scrollback UI). The manager instance is the named export stepHistory (re-exported at the package root, so import { stepHistory } from "@drincs/pixi-vn" works; also reachable as .history on the package's default export object).

Checkpoints and goBackMode

Not every step is necessarily something the player can go back to on its own — that depends on stepHistory.goBackMode (type HistoryGoBackModeType = "step" | "paragraph", default "step"):

• "step" (default): every single step can be gone back to individually. Matches classic VN-style "click to undo one line" behavior.
• "paragraph": only a step that starts a new paragraph (a call/jump happened, or a called label returned), proposes choices, or requires input can be gone back to on its own — everything else replays together with the next such step. Consequence: calling back() from anywhere inside paragraph N jumps all the way to the start of paragraph N-1, not to "one line up" — the whole of paragraph N-1 gets replayed. Step 0 is always a valid target regardless of mode.

Set it directly on the manager:

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

stepHistory.goBackMode = "paragraph"; // or "step" (default)

Going back

Trigger "go back" from game/UI code with stepHistory.back(props):

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

// In a click handler for a "back" / "undo" button:
await stepHistory.back(props); // props: the StepLabelPropsType passed into your step/label functions
// go back 3 steps (or 3 checkpoints, in "paragraph" mode) at once:
await stepHistory.back(props, { steps: 3 });

This is also how Pixi'VN itself handles the player pressing a system/browser "back" gesture, and Game.addOnError examples show calling await stepHistory.back(props) inside an error handler to roll back to the previous step on failure.

Notes on back():

• steps must be a finite number > 0; anything else logs a warning and does nothing.
• If narration is mid-step, or another back()/continue() is already in flight, the request is queued automatically rather than executed immediately — safe to call from an event handler without extra guarding.
• Use stepHistory.canGoBack (boolean) to decide whether to show/enable a "go back" button. In "step" mode this is true as soon as there's at least one earlier step to return to; in "paragraph" mode it becomes true less often, since most steps aren't individually go-back-able.
• stepHistory.blockGoBack() disables back() from this point on, permanently (only takes effect when no step is currently running) — useful right after an irreversible action (e.g. a choice with real consequences) if the player shouldn't be able to rewind past it.

Reading step/narration history (for a backlog UI)

In Pixi'VN's own terminology, "narrative history" is the list of all dialogues, choices, etc. that have been shown to the player — that's what these getters expose:

• stepHistory.narrativeHistory: NarrationHistory[] — every recorded step across the whole playthrough, in order, each with dialogue, choices, playerMadeChoice, inputValue, stepIndex, openedLabelsNumber. This is the property the official docs' "Get" section shows:

  import { stepHistory } from "@drincs/pixi-vn";
  const dialogues: NarrationHistory[] = stepHistory.narrativeHistory;

  (The public docs page's code sample types this as NarrativeHistory[] — that type isn't actually exported; the real export from @drincs/pixi-vn is NarrationHistory, confirmed in src/narration/interfaces/NarrationHistory.ts and used as the return type in src/history/HistoryManager.ts. Trust the source/this skill's NarrationHistory naming over that docs typo.)
• stepHistory.currentLabelHistory: NarrationHistory[] — just the "current page": steps belonging to the current label and its child labels, reset every time narration.jump is used. Useful for a per-scene backlog.
• stepHistory.currentPageParagraphs: NarrationHistory[][] — currentLabelHistory grouped into paragraphs (a new paragraph starts whenever openedLabelsNumber changes), regardless of goBackMode.
• stepHistory.removeNarrativeHistory(itemsNumber?) — deletes all narrative history if called with no argument, or trims just the oldest itemsNumber entries if you pass a number:

  stepHistory.removeNarrativeHistory(); // delete everything
  stepHistory.removeNarrativeHistory(2); // delete the first 2 elements