Pixi Vn Testing

Pixi'VN Testing module

When to use this skill

Use this skill when the task is to play the game from the outside — driving it like a player would, but from a script or an AI agent evaluating JavaScript in the page, instead of clicking UI. Typical asks this covers: "start the game and play through label X", "verify choice B leads to ending Y", "check that this bug repros after going back three steps", "seed storage with gold: 100 and confirm the shop unlocks", "run this game headless as a regression test".

This assumes the game's dev server (or a build served on a URL) and a browser are already running/reachable — starting either one is outside this skill; it only covers the game-control API itself. Do not use this skill for writing story content (pixi-vn-narration), save-file persistence (pixi-vn-saves), or the go-back UI/internals (pixi-vn-history) — those are the modules this skill drives, not what it teaches.

1. Why you can't just call narration.continue({}) from the console

narration.continue, .call, .jump, narration.choices.select, and stepHistory.back all take a props argument typed as StepLabelProps — the exact object a real game passes from its UI layer. Most real projects augment StepLabelProps (via TS module augmentation, see pixi-vn-getting-started) with app-specific fields: a router navigate, an i18n t, a toast, etc. (the official React template does exactly this — see pixi-vn-narration section 9). If a step calls props.navigate(...) or props.t(...), passing {} from a console/script call throws immediately.

Game.testing solves this once: the app pushes its real, live props to it (via setProps, see below) wherever it already builds them, and every action it exposes merges those in before delegating — so agent-driven calls behave exactly like a real player action, with no need to reconstruct or fake the app's props shape.

2. Enabling it

Game.testing is opt-in and disabled by default, and nothing about it depends on any particular bundler (Vite, Webpack, or none at all). Two independent pieces make it work:

• Turning the window bridge on/off — Game.testing.enable(options?) / .disable().
• Keeping it supplied with live props — Game.testing.setProps(props).

Turning it on/off

If the project uses @drincs/pixi-vn/vite's vitePluginPixivn, this is already handled: its testing option defaults to true, auto-enabling Game.testing for as long as vite dev keeps running (by injecting a small module into index.html) — never during vite build, regardless of the option. No app code needed for this part:

// vite.config.ts — this is already the default, shown here just to make it explicit
vitePluginPixivn({ testing: true }); // or { testing: { windowKey: "myGameTesting" } }, or false to opt out

Pass testing: false if you don't want this — e.g. a dev server shared with other people that you don't want remote-controllable.

Without the Vite plugin (a different bundler, or no bundler-level integration at all), call it yourself, gated behind your own dev-only check:

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

if (import.meta.env.DEV) {
  // or process.env.NODE_ENV !== "production", a Webpack DefinePlugin flag, etc.
  Game.testing.enable();
}

• options.windowKey (default "pixiVN") — the property name the API is attached under on window.
• Returns the same API object it attaches to window[windowKey], in case you want to keep a direct reference instead of going through window.
• Calling enable again (e.g. on hot reload) replaces the previous session instead of stacking.
• Game.testing.disable() tears it down (detaches from window, stops capturing errors).
• Game.testing.isEnabled() reports whether a session is currently active.

Only enable this when you actually want the game remote-controllable. It hands out full control over game state (see §4) to anything that can run JavaScript in that page — treat it like any other devtools/debug backdoor.

Keeping it supplied with live props: setProps

Call Game.testing.setProps(props) unconditionally, wherever your app already builds its StepLabelProps — it's a cheap assignment, safe to call whether or not testing happens to be enabled right now, and every Game.testing action reads through whatever was passed here most recently:

import { Game, type StepLabelProps } from "@drincs/pixi-vn";

function useGameProps(): StepLabelProps {
  // ... build props the same way your app always has ...
  const props = { navigate, t, toast /* ... */ };
  Game.testing.setProps(props); // [!code focus]
  return props;
}

React template convention

The official React template's useGameProps() (src/lib/hooks/props-hooks.ts — see pixi-vn-narration section 9) already ends with exactly that Game.testing.setProps(props) call, and vite.config.ts's vitePluginPixivn(...) call needs no extra option — testing defaults to true. Since useGameProps() already runs on every render of every component that needs game props, this is the only line the template needs: no dedicated bridge component, no manual enable() call.

Routing through the app's own narration functions: setActions

Most real apps don't call narration.continue/stepHistory.back/etc. straight from a "next" button — they wrap them in their own functions that also handle UI-only concerns a test session should trigger too: a loading indicator, refusing to advance while a menu/dialog is open, refreshing cached interface data after the step resolves, and so on. By default Game.testing's actions skip all of that and call narration/stepHistory directly, so an agent driving the game through window.pixiVN can get out of sync with what the real UI would have done (e.g. it never sees the loading state, or advances past a guard the real "next" button respects).

Game.testing.setActions(actions) fixes this: register the app's own functions once, and continue()/goBack()/selectChoice()/start()/jump()/call() call them instead. Any action left out keeps calling narration/stepHistory directly, so this is opt-in per action:

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

Game.testing.setActions({
  continue: () => goNext(),
  back: () => goBack(),
  selectChoice: (item) => selectChoice(item),
  start: (label, props) => async () => {
    await props.navigate("/game");
    return await startNewGame(label, props);
  },
  jump: (label, props) => jump(label, props),
  call: (label, props) => call(label, props),
});

Mount that hook once near the app root (same idea as useGameProps() always calling setProps) and window.pixiVN.continue() now runs the exact same code path as a player clicking "next".

A few things follow from continue/back taking no arguments themselves:

• The extraProps/options a caller passes to window.pixiVN.continue(...) / window.pixiVN.goBack(...) are ignored once an override is registered — the override manages its own props (typically via setProps) and usually has no notion of { steps, runNow }. Drive those through window.pixiVN.props/narration/stepHistory directly if you need that level of control.
• selectChoice's override receives the already-resolved choice item (the same shape as getState().choices[i]), not the raw choiceIndex — the lookup (and the "no open choice with that index" error) still happens before the override runs.
• setActions is safe to call whether or not testing is enabled yet, safe to call again to update the registered functions, and persists across disable()/enable() — same as setProps.