drincs-productions/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:

``ts 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:

``ts 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 (consumed by Game.exportGameState() — see pixi-vn-saves). Older steps beyond that limit are dropped from what's exported — meaning after loading a save, the player can only go back up to stepLimitSaved steps, even though narrativeHistory itself may show more (older entries lose the ability to be "gone back to" but keep their display text — the docs put it as "only essential information from older steps is kept"). Set it to Infinity to disable the limit and keep everything go-back-able.
• stepHistory.clear() wipes all history (called by Game.clear() and at the start of Game.restoreGameState()).

Real-world usage (official React template)

The official "TS narration + React" template (what npm create pixi-vn@latest scaffolds, source at pixi-vn-react-template) shows one concrete way to wire up "go back" and a backlog UI. This is that template's convention, not a library requirement — the APIs below (canGoBack, back(), narrativeHistory) are all you actually need; the loading-state/React-Query/i18n wrapping around them is the template's own app architecture.

Guarding the "back" button/gesture — src/lib/query/narration-query.ts exposes stepHistory.canGoBack through a React Query hook so the UI can enable/disable a back button reactively:

export function useQueryCanGoBack() {
  return useQuery({
    queryKey: [NARRATION_DATA_USE_QUERY_KEY, "can_go_back_use_query_key"],
    queryFn: async () => stepHistory.canGoBack,
  });
}

Triggering `back()` — src/lib/hooks/narration-hooks.ts wraps the call in a loading-state guard and error handling, then invalidates cached interface data (dialogue/choices/etc. queries) once it settles:

const goBack = useCallback(async () => {
  if (hasOpenMenu) return;
  GameStatus.setLoading(true);
  return stepHistory
    .back(gameProps) // gameProps: the app's StepLabelProps-shaped object from useGameProps()
    .then(() => {
      GameStatus.setLoading(false);
      gameProps.invalidateInterfaceData();
    })
    .catch((e) => {
      GameStatus.setLoading(false);
      console.error(e);
    });
}, [gameProps, hasOpenMenu]);

The same stepHistory.back is also bound directly as a handler elsewhere (src/lib/hooks/quick-tools-hooks.ts), e.g. stepHistory.back.bind(stepHistory) fired on a scroll-down gesture in a "quick tools" wheel — confirming back(props) is safe to call straight from arbitrary UI event handlers, not just a dedicated button.

Backlog/history-log UI — src/lib/query/narration-query.ts's useQueryNarrativeHistory({ searchString }) maps stepHistory.narrativeHistory into a flat display model per step (translating character name/dialogue text, passing through choices and inputValue as-is), then filters by a search string against character name and text:

const dialogues = stepHistory.narrativeHistory.map((step) => ({
  character: /* step.dialogue?.character name, translated */,
  text: /* step.dialogue?.text, translated */,
  icon: /* character icon, if any */,
  choices: step.choices,
  inputValue: step.inputValue,
}));

This is the shape a backlog/scrollback panel typically wants: one row per narrative-history entry with speaker, line, any choices offered, and any input the player typed at that step.

Gotchas

• Canvas is optional. If Game.init() was called without a canvas element (headless/engine-only usage), canvas state is never captured or restored during back() — going back only affects storage, sound, path and narration position in that setup.
• `"paragraph"` mode replays, it doesn't rewind precisely. back() in "paragraph" mode always lands on the _start_ of the previous paragraph/checkpoint, undoing everything since then in one jump — there is no way to undo "just the last line" within a paragraph.
• There is no "redo" after `back()`. Going back to an earlier step discards every step recorded after the point you land on, rather than merely skipping past them — so there's nothing to go forward to again.
• `stepHistory.get(stepIndex)` can return `undefined` even for a valid, recorded step index if that step carried no dialogue/choices/input worth showing (an internal bookkeeping-only entry) — check for undefined rather than assuming every index in range has a step to render.
• If restoring a step fails (e.g. corrupted or incompatible save data), back() logs an error and leaves the game state unchanged rather than throwing.

Related skills

pixi-vn, pixi-vn-saves, pixi-vn-narration, pixi-vn-canvas, pixi-vn-storage