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

TextOptions

(PixiJS

CanvasTextOptions

plus the

align

percentagePosition

positioning extensions), so

style

fontSize

fill

, 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

canvas.animate

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).

Filter-based articulated animations

The same

effects

namespace also has primitives built on the

filters

module (raw

pixi-filters

pixi.js

filter classes, re-exported as

filters.*

- see

@drincs/pixi-vn/filters

) instead of

canvas.animate

: each one attaches a filter to the component, drives one of the filter's own properties through a decaying (or one-shot) keyframe array via

filters.animate

, and detaches/destroys the filter once done - the component is left exactly as it was before, same guarantee as every effect above.

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

// glitch: jittery, decaying bursts of slice displacement with a matching red/blue channel split
// (returns two ticker ids; `rgbSplit: 0` drops the channel split)
await effects.glitchEffect("liam", { strength: 40, bursts: 3, rgbSplit: 6 });

// chromaticAberration: red/blue channels split apart and snap back, in a decaying burst
await effects.chromaticAberrationEffect("liam", { strength: 8, axis: "horizontal" });

// shockwave: a single ripple distortion travels outward from `origin` (normalized to the element's
// bounds) - by default until it has fully left the element
await effects.shockwaveEffect("liam", { origin: { x: 0.5, y: 0.5 } });

// radialBlur: a decaying burst of zoom-blur radiating from `origin` (normalized to the element's bounds)
await effects.radialBlurEffect("liam", { strength: 0.3, bursts: 1 });

// blurPulse: a repeated, decaying blur bump (distinct from blurIn/blurOut, which are one-shot
// reveal/conceal transitions, not a repeated pulse)
await effects.blurPulseEffect("liam", { strength: 8, pulses: 3 });

// vignettePulse: the edges darken and recover, in a repeated, decaying pulse - it darkens the corners
// of the element's own rectangle, so use it on backgrounds/full-frame images, not on characters
await effects.vignettePulseEffect("background", { strength: 1, pulses: 1, radius: 0.5 });

// desaturate: color drains out and recovers - a single dip, not a repeated pulse
await effects.desaturateEffect("liam", { amount: 0, holdDuration: 0.2 });

// glowPulse: a repeated, decaying outward glow
await effects.glowPulseEffect("liam", { strength: 4, pulses: 3, color: 0xffee00 });

All 8 are per-component (same

alias

pattern as everything else here) - there's no screen-wide/global filter effect yet. Distortion effects (glitch, chromatic aberration, shockwave, radial blur) move pixels around, so they only read on an image with detail/edges - on a flat, single-color element they look like nothing happened. Build a custom one the same way: construct any

filters.*

class, attach it to

component.filters

yourself, and drive it with

filters.animate

(see the low-level example just above this section) -

AdjustmentFilter

HslAdjustmentFilter

(color grading),

CRTFilter

OldFilmFilter

(retro looks), and

BloomFilter

AdvancedBloomFilter

(glow) are good starting points not covered above.

canvas.animate(componentOrAlias, keyframes, options, priority)

is the primitive all transition helpers are built on (motion's

animate

semantics: keyframes are arrays of target values,

options

supports

duration

ease

repeat

, etc.). Pixi'VN tracks animation state so it can be saved/restored — this is why you should prefer

canvas.animate

(or the transition helpers) over driving PixiJS directly with your own

requestAnimationFrame

loop. For UI that is not part of the saved scene graph (e.g. a PixiJS UI overlay), the docs recommend importing the raw

animate

from

@drincs/pixi-vn/motion

instead — it skips the save-state bookkeeping and is cheaper.

Frame tickers

canvas.animate

and the transition helpers above already use tickers internally — most tasks never need to touch the ticker API directly. For a genuinely continuous/looping custom effect (no fixed duration) or manual pause/resume/completion control over a running animation, see tickers.md
in this same skill folder (registering a

Ticker

tickers.addSequence

tickers.pause

resume

remove

tickers.completeOnStepEnd

). Docs: pixi-vn.com/start/canvas-tickers.

External rendering plugins

These optional packages are installed separately from

@drincs/pixi-vn

; their component classes must be imported from the plugin, not the engine. Check the installed package's peer dependencies and types before adapting examples to a project's PixiJS/Pixi'VN versions.

Live2D:

@drincs/pixi-vn-live2d

Use this wrapper around

untitled-pixi-live2d-engine

for Live2D models. Register its render plugin before

Game.init()

(or

canvas.init()

import { extensions } from "pixi.js";
import { Live2DPlugin } from "@drincs/pixi-vn-live2d/core";

extensions.add(Live2DPlugin);
// Initialize the game/canvas after registering the plugin.

Once the canvas is initialized, register the model asset and await model readiness before controlling it:

import { Assets, canvas } from "@drincs/pixi-vn";
import { Live2D } from "@drincs/pixi-vn-live2d";

Assets.add({ alias: "hero-model", src: "/models/hero/model3.json" });
const model = new Live2D({ source: "hero-model" });
await model.ready;
model.motion("Idle"); // Use a motion group present in this model.
canvas.add("hero", model);

Consult the plugin README for setup and its API reference for model options. Do not substitute

ImageSprite.load()

for

Live2D.ready

Spine:

@drincs/pixi-vn-spine

Use this wrapper around

@esotericsoftware/spine-pixi-v8

for skeletal animation. Add

import "@drincs/pixi-vn-spine";

to the app entry point: importing the package registers the serializable component. A lazy scene import alone is insufficient when a save is restored before that scene has ever loaded.

import { Assets, canvas } from "@drincs/pixi-vn";
import { Spine } from "@drincs/pixi-vn-spine";

await Assets.load(["hero-skeleton", "hero-atlas"]);
const model = new Spine({ skeleton: "hero-skeleton", atlas: "hero-atlas" });
model.setAnimation(0, "idle", true); // Animation names come from the skeleton.
canvas.add("hero", model);

See the Spine guide for skins and tracks and the package README for save-registration details. Keep the Pixi'VN wrapper when adding saved scene elements.

UI layers

Persistent UI chrome (HUD, menus) does not live on

gameLayer

— it lives on a separate, non-save-able layer built with

canvas.layers.add

get

remove

(PixiJS-only UI) or

canvas.htmlLayers.add

get

remove

(mounting a DOM-based UI framework like React or Vue). That whole API, plus the official template's layer-naming conventions,

extractImage()

for save-file thumbnails, and how to build a UI purely out of PixiJS components, is covered by

pixi-vn-ui

— reach for that skill instead whenever the task is about UI rather than the game scene.

Gotchas

addImage
/
addVideo
/
addImageCointainer
only construct and register the element — the texture is not loaded/visible until you
await element.load()
. The
```
show*
```
variants (
```
showImage
```
,
```
showVideo
```
,
```
showImageContainer
```
, and the transition helpers) call
```
load()
```
for you; prefer them unless you need to prepare an element off-screen first.
getTexture
/
load()
throw a
PixiError
(
unregistered_asset
) if the alias can't be resolved from the PixiJS
```
Assets
```
cache/manifest. See
```
pixi-vn-assets
```
for how to register an alias (local assets via AssetPack, or online assets in
```
src/assets/index.ts
```
) before referencing it here.
Adding an element with an alias that already exists replaces it and — per the "heredity factor" — copies over properties/
```
zIndex
```
/tickers from the old one by default (
```
canvas.add(alias, el, { ignoreOldStyle: true })
```
to opt out) — this is what lets
```
showImage("bg", newUrl)
```
"just work" as a same-alias swap.
canvas.remove(alias)
also removes tickers bound only to that alias; pass
```
{ ignoreTickers: true }
```
if you intend to reattach them elsewhere first.
Event listeners use plain PixiJS
.on(...)
, not a Pixi'VN-specific method — a stray JSDoc comment in the
```
Sprite
```
source suggests
```
sprite.onEvent(...)
```
, but that method doesn't exist; the official docs confirm
```
.on(...)
```
is correct. The Pixi'VN-specific part is only the
```
@eventDecorator()
```
requirement for save/load:
```
sprite.on("pointerdown", Events.handler)
```
only serializes correctly if
```
Events.handler
```
is a static method decorated with
```
@eventDecorator()
```
(from
```
@drincs/pixi-vn
```
); a plain inline arrow function will log a warning and not be restored after loading a save.
Positioning has multiple parallel systems (docs: canvas-position) — pixel (
```
x
```
/
```
y
```
/
```
position
```
), anchor/
```
pivot
```
(where on the element itself the position point sits),
```
align
```
/
```
xAlign
```
/
```
yAlign
```
(Ren'Py-style percentage-of-canvas positioning, e.g.
```
0.5
```
= centered; per source JSDoc, pivot
does not affect
align
), and
```
percentagePosition
```
/
```
percentageX
```
/
```
percentageY
```
(also percentage-of-parent, but pivot
does affect it, unlike
```
align
```
). Setting
```
x
```
/
```
align
```
/
```
percentagePosition
```
on the same axis clears the others; check
```
element.positionType
```
/
```
element.positionInfo
```
if you need to know which mode is active.

CANVAS_APP_GAME_LAYER_ALIAS
(
"__game_layer__"
) is reserved —

canvas.add

remove

, and

addLayer

will refuse to use that alias.

```
canvas.pause()
```
/
```
canvas.resume()
```
stop/restart rendering and tickers for the whole game layer (e.g. when opening a menu) — remember to call
```
resume()
```
or elements will appear frozen.

Related skills

pixi-vn-getting-started: project setup,
```
Game.init()
```
, and how the canvas is wired up at startup.
pixi-vn-assets: registering images/video (local or online) and choosing when their bundle loads, before referencing them here by alias.
pixi-vn-characters: character/emotion definitions that use canvas images under the hood for portraits.
pixi-vn-narration: dialogue/step flow, and how canvas transitions integrate with
```
completeOnContinue
```
.
pixi-vn-storage: how canvas element state (by alias) is saved and restored across game saves.
pixi-vn-ui: building/mounting UI layers (HTML or PixiJS) on top of the canvas —
```
addLayer
```
,
```
addHtmlLayer
```
, and building UI screens with PixiJS components.

pixi-vn-canvas

NPX Install

Tags

SKILL.md Content