drincs-productions/pixi-vn/migration

Pixi'VN Migration guide

Official docs: pixi-vn.com/faq/migration. That page also covers the separate nqtr and pixi-vn-ink packages — this skill only covers the core @drincs/pixi-vn package (the ## pixi-vn section of that page), since that's what this skill set documents.

When to use this skill

Use this skill whenever a task is "upgrade this project's @drincs/pixi-vn from version X to the latest", or a developer hits an error that looks like a removed/renamed API. Check the currently installed version first (package.json dependency, or PIXIVN_VERSION/GameState.pixivn_version at runtime — see pixi-vn), then walk forward through only the version sections below that fall between the installed version and the target — most of these changes don't apply unless a project is crossing that specific boundary.

v1.9.3 → v1.9.4 — canvas transitions/effects namespaces, top-level tickers

Canvas transitions and effects namespaces

Canvas transition helpers and canvas effects are now also grouped under discoverable namespaces: transitions contains showWithDissolve, showWithFade, moveIn, moveOut, zoomIn, zoomOut, pushIn, pushOut, removeWithDissolve, and removeWithFade; effects contains shakeEffect.

The previous flat exports remain available in v1.9.4 for compatibility, but are deprecated. Update imports and calls when migrating:

import { moveIn, shakeEffect, zoomIn } from "@drincs/pixi-vn"; // [!code --]
import { effects, transitions } from "@drincs/pixi-vn"; // [!code ++]
await zoomIn("alice", "alice"); // [!code --]
await transitions.zoomIn("alice", "alice"); // [!code ++]
await moveIn("alice", "alice"); // [!code --]
await transitions.moveIn("alice", "alice"); // [!code ++]
shakeEffect("alice"); // [!code --]
effects.shakeEffect("alice"); // [!code ++]

The transition and effect behavior and their options are unchanged. This is an organizational API change intended to make canvas helpers easier to discover. The existing module entry points remain valid; the same namespaces are available from @drincs/pixi-vn/canvas.

canvas.tickers → top-level tickers

Ticker management is no longer part of the canvas manager: it's its own tickers singleton, exported from @drincs/pixi-vn next to canvas, sound, etc. canvas.tickers still works in v1.9.4 — it just forwards to tickers — but it's deprecated. The methods and their arguments are unchanged; only the receiver changes:

import { canvas } from "@drincs/pixi-vn"; // [!code --]
import { tickers } from "@drincs/pixi-vn"; // [!code ++]
canvas.tickers.add("alien", new RotateTicker({ speed: 0.2 })); // [!code --]
tickers.add("alien", new RotateTicker({ speed: 0.2 })); // [!code ++]
canvas.tickers.pause({ canvasAlias: "alien" }); // [!code --]
tickers.pause({ canvasAlias: "alien" }); // [!code ++]
await canvas.tickers.forceCompletion(id); // [!code --]
await tickers.forceCompletion(id); // [!code ++]

The same applies to every other member (addSequence, find, remove, removeAll, resume, isPaused, unlinkComponent, transfer, completeOnStepEnd, onComplete, currentTickers, currentTickersSteps). The type CanvasTickersInterface is likewise a deprecated alias of the new TickersInterface:

import type { CanvasTickersInterface } from "@drincs/pixi-vn"; // [!code --]
import type { TickersInterface } from "@drincs/pixi-vn"; // [!code ++]

TickerBase, tickerDecorator, RegisteredTickers, and the Ticker* types are still exported from @drincs/pixi-vn exactly as before. Saves are unaffected: tickers are still serialized as part of the canvas state.

Only code that reached into canvas internals breaks: the ticker bookkeeping on CanvasManagerStatic (_currentTickers, _currentTickersSequence, _currentTickersTimeouts, _tickersToCompleteOnStepEnd, currentTickersWithoutCreatedBySteps, currentTickersSequence, generateTickerId, addTickerTimeoutInfo, removeTickerTimeout*) moved to the TickersManagerStatic namespace, where the two former getters are now functions:

CanvasManagerStatic._currentTickers; // [!code --]
TickersManagerStatic._currentTickers; // [!code ++]
CanvasManagerStatic.currentTickersSequence; // [!code --]
TickersManagerStatic.currentTickersSequence(); // [!code ++]

Prefer the public tickers.currentTickers / tickers.currentTickersSteps over either.

v1.8.x → v1.9.0 — long-deprecated APIs removed

This release removes several APIs that had been marked @deprecated for a while, with no replacement other than the one already documented at deprecation time:

Repeat/Pause(duration) and the RepeatType/PauseType types are gone. canvas.addTickersSequence now only accepts plain Ticker steps — chain tickers by duration instead of pause/repeat markers:

canvas.addTickersSequence("alien", [
  new RotateTicker({ speed: 0.1, clockwise: true }, 2),
  Pause(1), // [!code --]
  new RotateTicker({ speed: 0.2, clockwise: false }, 2),
  Repeat, // [!code --]
]);

See pixi-vn-canvas/tickers.md for the current sequencing API. forceCompleteBeforeNext is gone from every transition helper (showWithDissolve, moveIn, zoomIn, ...) and from CommonTickerProps — use completeOnContinue directly, it's no longer just an alias:

await showWithDissolve("alice", "alice", {
  forceCompleteBeforeNext: true, // [!code --]
  completeOnContinue: true, // [!code ++]
});

The deprecated AssetMemory.image field was removed; use AssetMemory.alias/url instead. Game.restoreGameState(data, navigate) lost its navigate overload — pass only data, and configure navigation once via Game.onNavigate (or Game.init({ navigate })) instead:

Game.restoreGameState(data, navigateTo); // [!code --]
Game.restoreGameState(data); // [!code ++]

The singular Game.onError(...) handler was removed; use Game.addOnError/Game.removeOnError (already the recommended API since v1.6.0):

Game.onError((type, error, { notify, uiTransition }) => { ... }); // [!code --]
Game.addOnError((error, { notify, uiTransition }) => { ... }); // [!code ++]

See pixi-vn-canvas/tickers.md for the current tickers/transitions API and pixi-vn for the current Game API.

Manager APIs reorganized into namespaces

The canvas, sound, storage, and narration managers used to expose dozens of unrelated methods directly on the manager (ticker methods, layer methods, and HTML-layer methods all mixed together on canvas, for example). This release groups related operations into namespaced sub-APIs — canvas.tickers/.layers/.htmlLayers, sound.channels/.unsaved, storage.temp/.flags, narration.labels/.queries/.input/.choices — so each manager reads as a short, discoverable surface instead of a flat list, and related options/overloads live next to each other. See pixi-vn-canvas, pixi-vn-sound, pixi-vn-storage, and pixi-vn for the current shape of each namespace.

Almost every old flat method still works and just forwards to its namespaced replacement — it's marked @deprecated but not removed, so migrate at your own pace. Two members are an exception: their type changed, so they break immediately rather than just warning.

sound.channels was AudioChannelInterface[]; it is now an object, and the array moved to .values:

sound.channels.map((c) => c.alias); // [!code --]
sound.channels.values.map((c) => c.alias); // [!code ++]

narration.choices (getter) was StoredIndexedChoiceInterface[] | undefined; it now returns a namespace object, and the array moved to .list. The setter, narration.choices = [...], is unchanged — it's a shortcut for .list:

const choices = narration.choices; // [!code --]
const choices = narration.choices.list; // [!code ++]

Every other rename below is a non-breaking, forward-compatible deprecation.

canvas's ticker methods moved to canvas.tickers (since v1.9.4 that is itself a deprecated alias of the top-level tickers — if you are migrating past v1.9.4, go straight to tickers.*, see v1.9.3 → v1.9.4 above):

canvas.transferTickers("old", "new"); // [!code --]
canvas.tickers.transfer("old", "new"); // [!code ++]

canvas.currentTickers; // [!code --]
canvas.tickers.currentTickers; // [!code ++]

canvas.currentTickersSteps; // [!code --]
canvas.tickers.currentTickersSteps; // [!code ++]

canvas.findTicker("t1"); // [!code --]
canvas.tickers.find("t1"); // [!code ++]

canvas.addTicker("alien", new RotateTicker({ speed: 0.2 })); // [!code --]
canvas.tickers.add("alien", new RotateTicker({ speed: 0.2 })); // [!code ++]

canvas.addTickersSequence("alien", steps); // [!code --]
canvas.tickers.addSequence("alien", steps); // [!code ++]

canvas.unlinkComponentFromTicker("alien", RotateTicker); // [!code --]
canvas.tickers.unlinkComponent("alien", RotateTicker); // [!code ++]

canvas.removeAllTickers(); // [!code --]
canvas.tickers.removeAll(); // [!code ++]

canvas.removeTicker("t1"); // [!code --]
canvas.tickers.remove("t1"); // [!code ++]

canvas.pauseTicker({ canvasAlias: "alien" }); // [!code --]
canvas.tickers.pause({ canvasAlias: "alien" }); // [!code ++]

canvas.resumeTicker({ canvasAlias: "alien" }); // [!code --]
canvas.tickers.resume({ canvasAlias: "alien" }); // [!code ++]

canvas.isTickerPaused("alien"); // [!code --]
canvas.tickers.isPaused("alien"); // [!code ++]

canvas.completeTickerOnStepEnd({ id: "t1" }); // [!code --]
canvas.tickers.completeOnStepEnd({ id: "t1" }); // [!code ++]

canvas.forceCompletionOfTicker("t1"); // [!code --]
canvas.tickers.forceCompletion("t1"); // [!code ++]

canvas.onTickerComplete("t1", options); // [!code --]
canvas.tickers.onComplete("t1", options); // [!code ++]

canvas's layer methods moved to canvas.layers:

canvas.gameLayer; // [!code --]
canvas.layers.gameLayer; // [!code ++]

canvas.addLayer("ui", uiLayer); // [!code --]
canvas.layers.add("ui", uiLayer); // [!code ++]

canvas.getLayer("ui"); // [!code --]
canvas.layers.get("ui"); // [!code ++]

canvas.removeLayer("ui"); // [!code --]
canvas.layers.remove("ui"); // [!code ++]

canvas's HTML-layer methods moved to canvas.htmlLayers:

canvas.addHtmlLayer("ui", root); // [!code --]
canvas.htmlLayers.add("ui", root); // [!code ++]

canvas.getHtmlLayer("ui"); // [!code --]
canvas.htmlLayers.get("ui"); // [!code ++]

canvas.removeHtmlLayer("ui"); // [!code --]
canvas.htmlLayers.remove("ui"); // [!code ++]

sound's transient/unsaved playback methods moved to sound.unsaved:

sound.playTransient("ui-click"); // [!code --]
sound.unsaved.playTransient("ui-click"); // [!code ++]

sound.pauseUnsavedAll(); // [!code --]
sound.unsaved.pauseAll(); // [!code ++]

sound.resumeUnsavedAll(); // [!code --]
sound.unsaved.resumeAll(); // [!code ++]

sound.stopTransientAll(); // [!code --]
sound.unsaved.stopTransientAll(); // [!code ++]

sound's channel creation/lookup methods moved to sound.channels (alongside the .values change above):

sound.addChannel("music"); // [!code --]
sound.channels.add("music"); // [!code ++]

sound.findChannel("music"); // [!code --]
sound.channels.find("music"); // [!code ++]

storage's temporary-variable methods moved to storage.temp (a new storage.temp.deadlines map is exposed alongside them):

storage.setTempVariable("key", "value"); // [!code --]
storage.temp.set("key", "value"); // [!code ++]

storage.removeTempVariable("key"); // [!code --]
storage.temp.remove("key"); // [!code ++]

storage's flag methods moved to storage.flags: