JollyPixel

Appearance

PixelArtCanvasOptions ​

Configures a PixelArtCanvas when it is constructed.

ts
import type {
  PixelArtCanvasOptions,
  WindowLike
} from "@jolly-pixel/pixel-draw.renderer";
import { StandalonePixelHistory } from "@jolly-pixel/asset.pixel-art/client";

const options: PixelArtCanvasOptions = {
  defaultMode: "paint",
  texture: { size: { x: 64, y: 32 } },
  history: new StandalonePixelHistory({ limit: 20 })
};

const canvas = new PixelArtCanvas(parent, options);

Types ​

The nested interfaces below are shown for readability; they are fields of PixelArtCanvasOptions.

ts
interface PixelArtCanvasOptions {
  document?: PixelDocument;
  defaultMode?: Mode;
  window?: WindowLike;
  texture?: TextureOptions;
  zoom?: ZoomOptions;
  backgroundTransparency?: BackgroundTransparencyOptions;
  backgroundColor?: ColorInput;
  brush?: BrushOptions;
  select?: SelectOptions;
  uv?: UVOptions;
  grid?: TextureGridOptions;
  onDrawEnd?: () => void;
  history?: PixelArtCanvasHistory;
  onHistoryChange?: (state: PixelHistoryState) => void;
  clipboard?: ClipboardAdapter | null;
  onClipboardResult?: (result: ClipboardOperationResult) => void;
  onModeChange?: (mode: Mode, previousMode: Mode) => void;
}

interface TextureOptions {
  defaultColor?: ColorInput;
  size?: { x: number; y?: number; };
  maxSize?: number;
  init?: HTMLCanvasElement;
}

interface BackgroundTransparencyOptions {
  colors: { odd: string; even: string; };
  squareSize: number;
}

interface SelectOptions {
  eraseColor?: ColorInput;
  sizeLabel?: boolean;
}

interface UVOptions {
  deselectOnEmptyClick?: boolean;
  resizable?: boolean;
}

type PixelArtCanvasHistory =
  | { enabled?: boolean; limit?: number; }
  | { history: CommandHistory<string>; scope: string; };

type ColorInput = string | Color;

Color is the colorjs.io class.

Document ​

document ​

An existing PixelDocument to edit instead of creating one. texture is then ignored. Destroying the canvas leaves the document intact.

Interaction ​

defaultMode ​

Initial interaction mode. It accepts "paint", "move", "fill", "select" or "uv" and defaults to "paint". See PixelArtCanvas.mode.

window ​

Event target used for drag continuation, held Ctrl key tracking (keydown and keyup), and blur handling. It defaults to the global window and accepts an object with compatible addEventListener() and removeEventListener() methods.

WindowLike is exported for typed browser adapters and test doubles.

clipboard ​

Overrides navigator.clipboard with an adapter exposing compatible read() and write() methods. Omit it to use the Async Clipboard API when available. Pass null to force internal-only copy and paste.

onClipboardResult ​

Receives every copy or paste result, including toolbar, shortcut and direct API calls. Codes cover success, internal-only copy, busy operations, denied access, missing or invalid images, transparent images, maximum-size rejection, and a decoded selection that could not be placed (paste-failed).

onModeChange ​

Called after an explicit mode change and after a successful paste switches the canvas to Select mode. It receives the new and previous modes.

Texture ​

texture.size ​

Initial texture size. y defaults to x; the full default is { x: 64, y: 32 }.

texture.defaultColor ​

Initial texture color. It defaults to opaque white.

texture.maxSize ​

Maximum texture dimension. Retained master storage grows toward this limit only as larger texture dimensions are reached. It must be a positive integer and defaults to 2048.

texture.init ​

Initial texture canvas. Its pixel data and dimensions replace the freshly created texture.

View ​

zoom ​

ts
interface ZoomOptions {
  default?: number;
  min?: number;
  max?: number;
  sensitivity?: number;
  smoothing?: number;
}

The default zoom fits the texture inside the parent with a small margin. It falls back to 4 when the parent has no size. min and max default to 1 and 32.

sensitivity is the relative zoom change per wheel notch at min (default 0.25, so 25%). The step shrinks to half of it at max, so zooming is quick from afar and precise up close. A zoom within 3% of a whole level snaps to it, keeping texture pixels evenly sized.

smoothing is the easing time constant in milliseconds (default 50). Wheel input moves zoom.target and zoom.value eases toward it while the texture pixel under the cursor stays put. 0 applies zoom instantly.

backgroundTransparency ​

Sets the checkerboard colors and square size behind transparent pixels. Omit it to use { odd: "#999", even: "#666" } with 8-pixel squares.

backgroundColor ​

Sets the canvas area outside the texture. When omitted, the canvas uses the parent's non-transparent computed background color or "#424242".

grid ​

Initial cell size, visibility, snapping and line color of canvas.grid. The grid starts hidden, without snapping, with 16-pixel cells.

Drawing and selection ​

brush ​

Initial brush colors, size and highlight colors. See BrushOptions.

brush.eraseColor sets what erase mode writes, and defaults to transparency. It is unrelated to select.eraseColor below, which only covers pixels a selection leaves behind.

select.eraseColor ​

Color used for pixels vacated by selection deletion, movement or transforms. When omitted, the canvas uses the dominant neighboring color and falls back to transparency when no in-bounds neighbor exists.

select.sizeLabel ​

Whether the selection shows its size as 16×16 next to the outline. It defaults to true.

The label reports the bounding box in texture pixels, including for shape selections, and follows the selection while it is created, moved and transformed. It is anchored below the bottom-right corner, flips above the selection near the bottom of the viewport, and hides when the selection scrolls out of view or measures less than 2 pixels on either axis. It is local only: peer selections never show one.

uv.deselectOnEmptyClick ​

Whether a UV-mode click landing outside every visible region clears the selection. It defaults to true.

Set it to false when the host application owns the selection, for instance when a block library drives which region is selected: an outside click then does nothing instead of hiding the selected region. It only governs that gesture; Delete, UVMap.select(null) and deleting the selected region still clear the selection.

uv.resizable ​

Whether the selected region shows resize handles in UV mode. It defaults to false, and canvas.tools.uv.resizable changes it later.

History ​

history ​

A PixelArtCanvasHistory the canvas binds its document and selection to. Without one, the canvas records nothing. @jolly-pixel/asset.pixel-art provides StandalonePixelHistory and SharedPixelHistory.

onHistoryChange ​

Called when the bound history changes: a step is filed, undone, redone or refused. The callback receives its PixelHistoryState.

Edit callbacks ​

onDrawEnd ​

Called after a stroke, global fill or selection edit is applied. It also runs after equivalent remote edits and successful undo or redo. Resizing, texture replacement and UV changes do not call it directly.

Local pixel and UV commands, undo and redo included, are emitted by the document: subscribe with canvas.document.on("command", listener). See PixelDocument.