Foundry VTT Canvas & PIXI.js

Domain: Foundry VTT Module/System Development Status: Production-Ready Last Updated: 2026-01-05

Overview

The Foundry canvas is a WebGL-powered HTML5 canvas using PIXI.js for rendering. Understanding the layer architecture and PIXI basics is essential for visual customizations.

When to Use This Skill

• Adding custom visual elements to the canvas
• Extending token/tile rendering
• Working with canvas layers
• Optimizing render performance
• Handling canvas lifecycle events

Canvas Architecture

Layer Hierarchy (Bottom to Top)

Primary Group:

• Background Layer - Scene backdrop
• Token Layer - Characters and creatures
• Tile Layer - Props and decorations
• Foreground Layer - Overlay images
• Weather Layer - Environmental effects
• Effects/Lighting - Vision and lighting

Interface Group:

• Walls Layer - Movement/sight blocking
• Sounds Layer - Audio zones
• Drawings Layer - User markup
• Templates Layer - Spell areas
• Notes Layer - Journal pins
• Controls Layer - Selection UI
• Grid Layer - Grid overlay

Accessing Layers

canvas.tokens      // TokenLayer
canvas.tiles       // TileLayer
canvas.drawings    // DrawingsLayer
canvas.templates   // TemplatesLayer
canvas.walls       // WallsLayer
canvas.lighting    // LightingLayer
canvas.sounds      // SoundsLayer
canvas.notes       // NotesLayer
canvas.grid        // GridLayer

canvas.primary     // PrimaryCanvasGroup
canvas.interface   // InterfaceCanvasGroup
canvas.environment // EnvironmentCanvasGroup

PIXI.js Basics

Containers

Group objects together:

const group = new PIXI.Container();
group.addChild(sprite1);
group.addChild(sprite2);

// Position the group (moves all children)
group.position.set(100, 100);
group.rotation = Math.PI / 4;

canvas.tokens.addChild(group);

Sprites

Display images:

const sprite = PIXI.Sprite.from("path/to/image.png");

// Use anchor for rotation center (0-1 percentage)
sprite.anchor.set(0.5);  // Center

sprite.position.set(100, 100);
sprite.width = 50;
sprite.height = 50;
sprite.rotation = Math.PI / 4;  // Radians
sprite.alpha = 0.8;
sprite.tint = 0xFF0000;  // Red tint

Graphics

Draw shapes programmatically:

const graphics = new PIXI.Graphics();

// Filled rectangle
graphics.beginFill(0x0000FF, 0.5);  // Blue, 50% alpha
graphics.drawRect(0, 0, 100, 100);
graphics.endFill();

// Stroked circle
graphics.lineStyle(2, 0xFF0000);  // 2px red line
graphics.drawCircle(50, 50, 25);

// Polygon
graphics.beginFill(0x00FF00);
graphics.drawPolygon([0, 0, 50, 100, 100, 0]);
graphics.endFill();

canvas.drawings.addChild(graphics);

Visual Effects

// Transparency
sprite.alpha = 0.5;

// Color tint (multiply)
sprite.tint = 0xFF0000;  // Red
sprite.tint = 0xFFFFFF;  // No change (white)

// Blend modes
sprite.blendMode = PIXI.BLEND_MODES.ADD;       // Glow effect
sprite.blendMode = PIXI.BLEND_MODES.MULTIPLY;  // Darken
sprite.blendMode = PIXI.BLEND_MODES.SCREEN;    // Lighten

// Filters (use sparingly - performance impact)
const blur = new PIXI.BlurFilter();
blur.blur = 10;
sprite.filters = [blur];

Masking

// Graphics mask
const mask = new PIXI.Graphics();
mask.beginFill(0xFFFFFF);
mask.drawCircle(50, 50, 50);
mask.endFill();

container.mask = mask;
container.addChild(contentToMask);

Placeable Objects

Common Placeables

• Token - Actor representation
• Tile - Static artwork
• Drawing - User shapes
• Note - Journal pin
• Wall - Blocking segment
• AmbientLight - Light source
• AmbientSound - Audio emitter
• MeasuredTemplate - Area indicator

PlaceableObject Properties

const token = canvas.tokens.get(tokenId);

token.document    // TokenDocument
token.scene       // Parent Scene
token.isOwner     // Ownership check

// Permission checks
token.can("update")
token.can("delete")
token.can("control")

PlaceableObject Methods

// Control
token.control();           // Select
token.release();           // Deselect
await token.rotate(45);    // Rotate by degrees

// Rendering
await token.draw();        // Full redraw
token.refresh();           // Incremental update

Render Flags

Optimize updates by specifying what changed:

Token Render Flags

token.renderFlags.set({
  refreshPosition: true,    // X/Y changed
  refreshSize: true,        // Width/height changed
  refreshRotation: true,    // Angle changed
  refreshBars: true,        // HP bars changed
  refreshEffects: true,     // Status icons changed
  refreshBorder: true,      // Selection border
  refreshVisibility: true,  // Vision state
  refreshElevation: true,   // Z-axis display
  refreshNameplate: true,   // Name display
  redraw: true              // Complete redraw
});

Why Use Render Flags

// BAD - full redraw every time
token.draw();
token.draw();
token.draw();

// GOOD - batch incremental updates
token.renderFlags.set({ refreshPosition: true });
token.renderFlags.set({ refreshBars: true });
// Updates happen efficiently in next render cycle

Canvas Lifecycle

Initialization Order

init
  → setup
    → canvasConfig
      → canvasInit
        → ready
          → canvasReady

Key Hooks

// Canvas fully ready - safe to access all layers
Hooks.on("canvasReady", (canvas) => {
  console.log("Scene:", canvas.scene.name);
  console.log("Tokens:", canvas.tokens.placeables.length);
});

// Canvas being torn down
Hooks.on("canvasTearDown", (canvas) => {
  // Clean up custom elements
});

// Canvas panned/zoomed
Hooks.on("canvasPan", (canvas, position) => {
  console.log("New center:", position.x, position.y);
  console.log("Scale:", position.scale);
});

Waiting for Canvas

// Promise-based
await canvas.ready;

// Hook-based
Hooks.once("canvasReady", () => {
  // Safe to interact
});

Common Patterns

Add Custom Layer Element

Hooks.on("canvasReady", () => {
  const marker = new PIXI.Graphics();
  marker.beginFill(0xFF0000);
  marker.drawCircle(0, 0, 20);
  marker.endFill();
  marker.position.set(500, 500);

  canvas.interface.addChild(marker);
});

Extend Token Rendering

class CustomToken extends Token {
  async _draw() {
    await super._draw();

    // Add custom aura
    const aura = new PIXI.Graphics();
    aura.beginFill(0x00FF00, 0.2);
    aura.drawCircle(0, 0, this.w);
    aura.endFill();

    this.addChildAt(aura, 0);  // Behind token
  }
}

// Register
CONFIG.Token.objectClass = CustomToken;

Coordinate Conversion

// Client (viewport) to canvas coordinates
const canvasCoords = canvas.canvasCoordinatesFromClient({
  x: event.clientX,
  y: event.clientY
});

// Canvas to client coordinates
const clientCoords = canvas.clientCoordinatesFromCanvas({
  x: 500,
  y: 500
});

Pan and Zoom

// Instant pan
await canvas.pan({ x: 1000, y: 1000 });

// Animated pan
await canvas.animatePan({
  x: 1000,
  y: 1000,
  scale: 1.5,
  duration: 1000
});

// Center on controlled token
await canvas.recenter();

Common Pitfalls

1. Accessing Canvas Before Ready

// WRONG - canvas not initialized
Hooks.on("init", () => {
  canvas.tokens.placeables;  // undefined!
});

// CORRECT - wait for canvasReady
Hooks.on("canvasReady", () => {
  canvas.tokens.placeables;  // works
});

2. Direct DOM Manipulation

// WRONG - breaks PIXI rendering
element.style.transform = "rotate(45deg)";

// CORRECT - use PIXI properties
sprite.angle = 45;  // degrees
sprite.rotation = Math.PI / 4;  // radians

3. Wrong Canvas Group

// WRONG - bypasses layer hierarchy
canvas.app.stage.addChild(myGraphics);

// CORRECT - add to appropriate group
canvas.interface.addChild(myGraphics);

4. Excessive Filters

// BAD - major performance hit
object.filters = [blur, color, displacement, glow];

// BETTER - minimal filters, combine effects
object.filters = [combinedEffect];

5. Not Cleaning Up

// Remember to remove custom elements
Hooks.on("canvasTearDown", () => {
  myCustomElement.destroy();
});

6. Forgetting Anchor/Pivot

// Rotation around top-left (default)
sprite.rotation = Math.PI / 4;

// Rotation around center (usually desired)
sprite.anchor.set(0.5);
sprite.rotation = Math.PI / 4;

Implementation Checklist

• Wait for canvasReady before canvas access
• Add elements to correct canvas group/layer
• Use PIXI properties, not DOM manipulation
• Set anchor/pivot for rotation center
• Use render flags for efficient updates
• Clean up custom elements on canvasTearDown
• Use filters sparingly
• Test at different zoom levels
• Handle scene changes gracefully

References

• Canvas API
• Canvas Wiki
• PIXI.js Guide
• PlaceableObject API
• Token API
• PixiJS Documentation

---

Last Updated: 2026-01-05 Status: Production-Ready Maintainer: ImproperSubset