Pixi Vn Canvas

Pixi'VN Canvas

The Canvas module is Pixi'VN's 2D scene graph, built directly on top of PixiJS. It manages everything that is visually rendered in the game: background images, character sprites, text, video, and the transitions/animations between them. Official docs: pixi-vn.com/start/canvas.

Every symbol used below (canvas, showImage, Sprite, transition helpers, etc.) is exported from the main package entry point:

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

(Also available from the narrower @drincs/pixi-vn/canvas subpath — see pixi-vn-getting-started for when to prefer that.)

When to use this skill

Load this skill whenever a task involves:

• Showing, replacing, or removing an image/sprite/video/text on screen.
• Building a composite character sprite out of several image layers.
• Applying a transition (dissolve, fade, move, zoom, push, wipe, iris, split, flash, blur, pixelate) when a background or sprite changes.
• Adding a shake effect or a custom PixiJS-ticker-driven animation.
• Reading or modifying canvas element position/anchor/alpha/zIndex.

For building/mounting UI layers (HTML or PixiJS) on top of the canvas, use pixi-vn-ui instead — this skill is about the gameLayer save-able scene graph, not UI chrome.

For dialogue/character-portrait logic use pixi-vn-characters and pixi-vn-narration instead; this skill is about the underlying rendering primitives.

Core mental model

• canvas (from @drincs/pixi-vn) is the single entry-point object developers use. It wraps a PixiJS Application and exposes methods to manage canvas elements and layers. Call await canvas.init(element, options) once at startup (this is normally done for you by Game.init(...) from the core package — see pixi-vn-getting-started).
• Elements are tracked by alias, not by variable (docs). canvas.add(alias, component) inserts a component (an instance of Container, Sprite, ImageSprite, ImageContainer, Text, or VideoSprite) into canvas.layers.gameLayer (a single PixiJS Container that holds all "in-scene" elements) and sets component.label = alias. Use canvas.find<T>(alias) to look elements back up and canvas.remove(alias) to remove them. Aliases are also how Pixi'VN saves/restores canvas state (see pixi-vn-storage), so prefer the alias-based helpers below over holding onto raw object references across steps.
• Every element class is a save-able extension of a PixiJS class: Container extends PIXI.Container, Sprite/ImageSprite/VideoSprite extend PIXI.Sprite, Text extends PIXI.Text. They add a .memory getter / .setMemory() for serialization, plus convenience properties (anchor, align, percentagePosition, xAlign/yAlign, percentageX/percentageY) as alternative ways to position an element without doing pixel math.
• Layer is just a type alias for a plain PIXI.Container<ContainerChild> — there's no special Layer class. A separate, non-save-able PixiJS Container can be attached directly to the stage as a sibling of gameLayer (canvas.layers.add/get/remove) — see pixi-vn-ui for that API, it's how UI layers (HTML or PixiJS) are built on top of the canvas.
• Tickers are how frame-based animation and effects work under the hood; canvas.animate(...) (built on the motion library) is the high-level way to animate numeric properties over time, and it is what all the built-in transition helpers use internally. Running tickers are managed through the separate tickers singleton (also from @drincs/pixi-vn, not a member of canvas — the old canvas.tickers is a deprecated alias of it).

Showing and removing an image

import { canvas, addImage, showImage } from "@drincs/pixi-vn";

// addImage() creates + registers the sprite but does NOT load/display the texture yet
const bunny1 = addImage("bunny1"); // "bunny1" is an alias registered in the assets manifest
await bunny1.load();

// showImage() is addImage() + load() in one call
const bunny2 = await showImage("bunny2");
bunny2.anchor = 0.5;
bunny2.x = canvas.width / 2;
bunny2.y = canvas.height / 2;

// remove it later by alias
canvas.remove("bunny1");

Always pass a manifest alias (as above), not a raw URL/path — see pixi-vn-assets for how assets get registered (local vs. online) and loaded. addImage/showImage do also accept a raw URL as a second argument for quick prototyping, but that couples code to a specific file location; addImage/showImage throw a PixiError if neither a URL nor a registered alias resolves. Both return an ImageSprite.

For a composite image made of multiple stacked textures (e.g. a character body + outfit + face), use ImageContainer via addImageCointainer / showImageContainer (note the exported spelling "Cointainer"):

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

const liam = await showImageContainer("liam", ["liam-body", "liam-head"]);

Adding text

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

showText("score-label", "Score: 0", {
  fontSize: 24,
  fill: "white",
  x: 20,
  y: 20,
});

showText(alias, text, options) creates/replaces a Text element (extends PIXI.Text) and adds it to the canvas immediately. options is TextOptions (PixiJS CanvasTextOptions plus the align/percentagePosition positioning extensions), so style, fontSize, fill, x/y, etc. all work as in plain PixiJS.

Playing a video

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

const film = await showVideo("intro-film"); // "intro-film" resolves via the assets manifest
film.loop = true;
// film.pause(), film.play(), film.restart(), film.currentTime = 2

addVideo/showVideo mirror addImage/showImage and return a VideoSprite (extends ImageSprite). Files are also recognized as videos by extension automatically anywhere a transition helper accepts an image URL (.mp4, .webm, .mov, etc. — see checkIfVideo).

Transitions

Docs: pixi-vn.com/start/canvas-transition.

All transition helpers take (alias, componentOrUrl?, props?, priority?). If you omit the component/URL argument, the alias itself is used as the texture URL/alias. Each function replaces (or removes) whatever is currently registered under alias, transferring position and running tickers from the old element automatically. They all return a Promise (or array) of ticker ids you can pass to tickers.forceCompletion if you need to await completion, but usually you just call and move on.

import {
  showWithDissolve,
  removeWithDissolve, // fade the new image in / fade the current one out
  showWithFade,
  removeWithFade, // cross-fade old -> new (falls back to dissolve if none exists)
  moveIn,
  moveOut, // slide in/out from a screen edge
  zoomIn,
  zoomOut, // scale in/out from a screen edge
  pushIn,
  pushOut, // new image pushes the old one off-screen
} from "@drincs/pixi-vn";

// change background with a 1s dissolve ("bg-forest" is a manifest alias)
await showWithDissolve("background", "bg-forest", { duration: 1 });

// slide a character sprite in from the left
await moveIn("liam", "liam-neutral", { direction: "left", duration: 0.5 });

// remove a character with a zoom-out toward the right edge
zoomOut("liam", { direction: "right", duration: 0.5 });

props extends AnimationOptions from motion (e.g. duration, ease) plus a completeOnContinue flag (default true) that finishes the transition immediately when the player advances the narration before the animation ends — leave this at its default unless you specifically want an animation to be interruptible/ignored.

Generic reveal/filter transitions: wipe, iris, split, flash, blur, pixelate, glitch, twist, warp, ripple, noiseDissolve, tv, pinch

These are only exposed through the transitions namespace (no flat top-level export like the older moveIn/showWithDissolve), each as a matched xIn/xOut pair with the same (alias, componentOrUrl?, props?, priority?) / (alias, props?, priority?) shapes as above. They favor a handful of configurable options over narrative-specific variants — e.g. there's one wipeIn, not wipeLeft/wipeRight.

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

// wipe: a moving boundary reveals/conceals the image. `angle` in degrees (0 = left-to-right, 90 =
// bottom-to-top, ...); `direction` ("up"/"down"/"left"/"right") is a shorthand for the 4 cardinal angles.
await transitions.wipeIn("background", "bg-forest", { direction: "left", duration: 1 });
await transitions.wipeIn("background", "bg-night", { angle: 45, duration: 1 }); // diagonal wipe
transitions.wipeOut("background", { angle: 180, invert: true, duration: 1 });

// iris: an expanding/contracting radial mask. `origin` is normalized (0-1) to the element's own bounds.
await transitions.irisIn("liam", "liam-happy", { origin: { x: 0.5, y: 0.3 }, duration: 0.8 });
transitions.irisOut("liam", { aspect: 2, duration: 0.8 }); // aspect > 1 = wide ellipse instead of a circle

// split: two mask panels move apart/together - covers "curtain" effects without a dedicated API.
await transitions.splitIn("background", "bg-forest", { orientation: "horizontal", duration: 1 });
transitions.splitOut("background", { orientation: "vertical", origin: 0.3, duration: 1 });

// flash: a configurable color overlay (not just white) fades in/hold/out, optionally pulsing.
await transitions.flashIn("background", "bg-forest", { duration: 0.15 }); // white camera-flash reveal
transitions.flashOut("liam", { color: 0xff0033, holdDuration: 0.05, pulses: 3, duration: 0.1 }); // red damage flash

// blur / pixelate: the image is shown already blurred/pixelated and resolves into focus (or the reverse for *Out).
await transitions.blurIn("liam", "liam-happy", { strength: 40, duration: 1 });
transitions.blurOut("liam", { duration: 1 });
await transitions.pixelateIn("background", "bg-forest", { pixelSize: 48, duration: 1 });
transitions.pixelateOut("background", { duration: 1 });

// glitch: jittery slices + red/blue split, settling on *In, building up on *Out.
await transitions.glitchIn("liam", "liam-happy", { strength: 40, bursts: 3 });
// twist: unwinds out of (or winds into) a swirl - `angle` in degrees, `origin` normalized.
transitions.twistOut("liam", { angle: 540 });
// warp: radial zoom-blur streaks, like dropping out of / jumping into hyperspace.
await transitions.warpIn("background", "bg-space", { strength: 0.6 });
// ripple: fades in/out through a spreading water ring - dreams, magic, memories.
await transitions.rippleIn("liam", "liam-dream", { origin: { x: 0.5, y: 0.3 } });
// noiseDissolve: the classic VN image dissolve - organic noise blotches (`edge: "soft"` for a cloudy fade).
await transitions.noiseDissolveIn("background", "bg-night", { edge: "hard", noiseScale: 8 });
// tv: old TV switching on (dot -> glowing line -> image) / off; scales around the anchor (center it).
transitions.tvOut("liam", { lineThickness: 0.02, brightness: 3 });
// pinch: emerges from / is sucked into a point (`mode: "bulge"` puffs out instead).
transitions.pinchOut("liam", { mode: "pinch" });

// move/push also take an optional motion-blur trail (true = 40px, or a length in pixels).
await transitions.moveIn("liam", "liam-happy", { direction: "right", duration: 0.6, motionBlur: true });

Distortion transitions (glitch, twist, warp, ripple, pinch) move pixels around, so they read best on images with detail - on a flat, single-color element they're much less visible.

They compose freely since each drives its own mask (wipe/iris/split) or filter (blur/pixelate/glitch/...) independently — e.g. call blurIn and then wipeIn on the same alias to combine both. Common narrative effects are just recipes built from these primitives rather than dedicated functions: a "blink"/eyes-opening effect is a color overlay plus an iris reveal, a "dream"/flashback is blurIn + showWithFade, a memory transition is a color overlay plus blurIn, a "curtain" is a configured splitOut, and a diagonal wipe is just wipeIn/wipeOut with a non-cardinal angle.

Creating custom transitions

Docs: pixi-vn.com/start/canvas-transition#custom-functionality.

A custom transition is just a plain function that adds/replaces a component and drives it with canvas.animate — the same primitive showWithDissolve, moveIn, etc. are built on:

import { canvas, ImageSprite, UPDATE_PRIORITY } from "@drincs/pixi-vn";
import { AnimationOptions } from "@drincs/pixi-vn/motion";

export default async function showWithDissolve(
  alias: string,
  component: ImageSprite,
  props: AnimationOptions = {},
  priority?: UPDATE_PRIORITY,
): Promise<string[] | undefined> {
  const { completeOnContinue = true, ...options } = props;
  canvas.add(alias, component);
  component.alpha = 0;
  const id = canvas.animate(alias, { alpha: 1 }, { ...options, completeOnContinue }, priority);
  if (component.haveEmptyTexture) await component.load();
  if (id) return [id];
}

If a component under the same alias may already exist, either let canvas.add replace it outright (per the heredity-factor gotcha above), or explicitly swap it in first — rename the old component's alias, add the new one, restore z-order, then transfer its properties/tickers — so an in-flight animation on the old element carries over instead of snapping:

let oldComponentAlias: string | undefined;
const oldComponent = canvas.find(alias);
if (oldComponent) {
  oldComponentAlias = `${alias}_temp`;
  canvas.editAlias(alias, oldComponentAlias);
}
canvas.add(alias, component);
oldComponent?.parent?.setChildIndex(oldComponent, oldComponent.parent.getChildIndex(oldComponent) - 0.1);
oldComponentAlias && canvas.copyCanvasElementProperty(oldComponentAlias, alias);
oldComponentAlias && tickers.transfer(oldComponentAlias, alias, "duplicate");

To remove the old component only once the new one's transition finishes, pass aliasToRemoveAfter: oldComponentAlias in canvas.animate's options instead of removing it manually. To have the old component run its own transition-out (instead of a hard cut), give it a second canvas.animate call paused with tickers.pause({ id }) and resumed via the new call's tickerIdToResume option — see the wiki's own two worked examples for the exact sequencing.

Animating a filter's own property instead of a component property — for effects like blur, pixelate, glow, or color grading, use filters.animate (from @drincs/pixi-vn/filters, available since v1.9.4) instead of canvas.animate. It mirrors the same (alias, keyframes, options, priority) shape with the Filter instance inserted as the second argument; you attach the filter to component.filters yourself before animating, and detach + destroy it in the cleanup callback (the 7th argument) once the animation completes — this is exactly how transitions.blurIn/blurOut/pixelateIn/pixelateOut are implemented:

import { canvas, ImageSprite, UPDATE_PRIORITY } from "@drincs/pixi-vn";
import { filters } from "@drincs/pixi-vn/filters";
import { AnimationOptions } from "@drincs/pixi-vn/motion";

export default async function blurIn(
  alias: string,
  component: ImageSprite,
  props: AnimationOptions & { strength?: number } = {},
  priority?: UPDATE_PRIORITY,
): Promise<string[] | undefined> {
  const { strength = 32, completeOnContinue = true, ...options } = props;
  canvas.add(alias, component);
  const filter = new filters.BlurFilter({ strength });
  component.filters = [filter];
  const id = filters.animate(
    alias,
    filter,
    { strength: [strength, 0] },
    { ...options, completeOnContinue },
    priority,
    undefined, // apply - only needed when filter is undefined (see below)
    () => {
      component.filters = null;
      filter.destroy();
    },
  );
  if (component.haveEmptyTexture) await component.load();
  if (id) return [id];
}

filters.animate can also drive a plain numeric value with no live filter — pass undefined as the filter and an apply callback (called every frame with the interpolated value) instead. This is how wipeIn/irisIn/splitIn animate their mask geometry (a growing radius, a moving boundary), since a mask has no filter property to write directly.

Shake and other articulated animations

The effects namespace holds "articulated animations" — helpers built on top of canvas.animate that bake a full keyframe array once and animate it in a single call (docs: canvas-articulated-animations-effects, canvas-motion). Like the transitions above, these are generic primitives — the effect describes how a component moves, the game decides what that means (a hit reaction, an idle fidget, an emphasis beat, ...).

import { effects, canvas } from "@drincs/pixi-vn";

// shake a canvas element horizontally
await effects.shakeEffect("screen-flash-target", {
  shakeType: "horizontal",
  maxShockSize: 15,
  shocksNumber: 10,
});

// bounce: one-directional decaying displacement, e.g. a character landing a jump
await effects.bounceEffect("liam", { direction: "up", distance: 30, bounces: 3 });

// pulse: decaying scale bump, e.g. emphasizing a UI element or a heartbeat
await effects.pulseEffect("liam", { scale: 1.3, pulses: 2 });

// hop: a single displacement-and-return, optionally with smaller decaying follow-up hops
await effects.hopEffect("liam", { direction: "up", distance: 40, secondaryHops: 2 });

// wiggle: decaying rotation oscillation, e.g. a "no" head-shake or a nervous tic
await effects.wiggleEffect("liam", { angle: 15, repetitions: 3 });

// nod: decaying positional oscillation along one axis, e.g. a "yes" nod or a flinch
await effects.nodEffect("liam", { axis: "vertical", distance: 10, repetitions: 3 });

// sway: smooth combined position+rotation drift, e.g. an idle breathing/swaying loop
// (decay defaults to 0 = constant amplitude, unlike the other primitives above)
await effects.swayEffect("liam", { distance: 8, angle: 3, repetitions: 4 });

// punch: a single fast impulse with a settle-back overshoot, e.g. taking a hit
await effects.punchEffect("liam", { mode: "scale", strength: 0.3, overshoot: 0.3 });
await effects.punchEffect("liam", { mode: "rotation", strength: 20 });

// low-level: animate arbitrary numeric properties with motion-style keyframes
canvas.animate("liam", { alpha: [0, 1], y: [50, 0] }, { duration: 0.8 });

There's no separate "tremble"/"vibration" primitive — that's just shakeEffect configured with a small maxShockSize and a high shocksNumber (high-frequency, low-amplitude shaking).