/canvas

name: pixi-vn-canvas
description: Use when adding, moving, or removing images, sprites, text, or video on the Pixi'VN game canvas, or when applying or creating transitions (dissolve, fade, move, zoom, push, wipe, iris, split, flash, blur, pixelate, or a custom one built on `canvas.animate`/`filters.animate`), shake/animation effects, or ticker-based animations built on PixiJS. Covers the `canvas` singleton exported from `@drincs/pixi-vn`. For UI layers (HTML or PixiJS) mounted on top of the canvas, see `pixi-vn-ui` instead.

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](https://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` 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`).

• **Elements are tracked by alias, not by variable** ([docs](https://pixi-vn.com/start/canvas-alias)).

`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 `sty