/history

name: pixi-vn-history
description: Use when implementing "go back" / "rewind" / step-navigation features in a Pixi'VN game, or when you need to read the player-facing dialogue/choice history (e.g. for a backlog or "history log" UI) — covers the History module's `stepHistory` API and the "step" vs "paragraph" goBackMode.

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

Save/load and step limits

• `stepHistory.stepLimitSaved` (default `20`) caps how many steps' worth of go-back history are kept when exporting for a save file