/migration

name: pixi-vn-migration
description: Use when upgrading an existing @drincs/pixi-vn project to a newer version, or when a runtime/type error matches a known breaking change. Covers every breaking change between versions with before/after code.

Pixi'VN Migration guide

Official docs: [pixi-vn.com/faq/migration](https://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.onNav