Document

app.convertColorMode(colorMode, opts?) — changes, undoable

Converts the sprite between color modes (rgba, grayscale, indexed), optionally dithering and generating a palette when going to indexed.

• colorMode (ColorMode: "rgba" | "grayscale" | "indexed") — Conversions out of rgba (and into grayscale) are lossy: color quantizes to its nearest palette entry or its Rec. 709 luma (Aseprite's, truncated: red is 54). Into grayscale the palette becomes 256 grays, black to white (per-frame palettes and palette groups go, the transparent index becomes 0). No-op if the sprite is already in that mode.
• opts (table, optional)
  • dithering (DitherMethod: "none" | "bayer2" | "bayer4" | "bayer8" | "floydSteinberg" | "atkinson"; default "none") — Into indexed only: how colours between palette entries are approximated.
  • ditherAmount (integer 0–100; default 100) — Into indexed only: dithering strength (0 = nearest colour only).
  • paletteColors (integer 1–256; default keep the current palette) — Into indexed only: replace the palette with this many colours generated from the sprite (plus a transparent entry at index 0 unless the Background is the only layer; per-frame palettes are dropped).

Returns nothing.

app.cropToSelection() — changes, undoable

Crops the canvas to the current selection's bounds; a selection reaching past the canvas grows it there. No-op if nothing is selected.

Returns nothing.

app.describe() — reads

Everything about the document's structure in one call (no pixel data): { sprite, activeLayerId, activeFrameId, layers, frames, cels, tags, slices, selection (bounds or nil), context } — each part in the shape of its own query (app.getSprite, app.getLayers, ...). Start here to see what you're working with.

Returns (table): Document table.

app.flip(axis, layerId?) — changes, undoable, refused on a locked layer

Mirrors the whole canvas, or one layer (a group's descendants too) across every frame: cel pixels and positions, tilemap tiles, reference images. Unlike app.flipCelRegion it ignores the selection.

• axis (FlipAxis: "horizontal" | "vertical")
• layerId (string, optional) — The layer (or group) to flip on every frame. Omit to flip the whole canvas: every layer, every frame, the slices and the selection.

Returns nothing.

app.getCanvasHeight() — reads

The sprite's canvas height in pixels.

Returns (number): Height in pixels.

app.getCanvasWidth() — reads

The sprite's canvas width in pixels.

Returns (number): Width in pixels.

app.getColorMode() — reads

The sprite's color mode: "rgba", "grayscale", or "indexed".

Returns (string): "rgba", "grayscale" or "indexed".

app.getSprite() — reads

The sprite: { id, width, height, colorMode ("rgba" | "grayscale" | "indexed"), palette (hex strings), transparentIndex (indexed sprites: the palette index whose pixels are transparent), pixelRatio ({ w, h }; 1:1 = square pixels), colorDepth (levels per channel: { kind = "rgb", red, green, blue } or { kind = "gray", gray }, with profile; nil for full color), layerCount, frameCount }.

Returns (table): Sprite table.

app.newSprite(width, height, background?) — changes, undoable

Replaces the whole document with a brand new sprite (one layer, one frame; a Background layer when a background colour is given). Discards the current document's content.

• width (number) — Canvas width in pixels.
• height (number) — Canvas height in pixels.
• background (color, optional) — Fill colour of a Background layer. Omitted = a transparent "Layer 1" instead.

Returns (table): { layerId, frameId } of the new sprite's one layer and frame.

app.rotateCanvas(degrees) — changes, undoable

Rotates the whole canvas (every layer, every frame) clockwise (90), counter-clockwise (-90), or 180 degrees.

• degrees (number) — 90, -90, or 180.

Returns nothing.

app.setCanvasSize(width, height, anchor) — changes, undoable

Resizes the canvas, repositioning (not resampling) existing content relative to anchor. Content left past the new edge is kept there (only the Background layer is cut), so growing back restores it.

• width (number)
• height (number)
• anchor (CanvasAnchor: "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right")

Returns nothing.

app.setPixelRatio(w, h) — changes, undoable

Sets the sprite's pixel aspect ratio (Aseprite's Sprite Properties > Pixel Ratio), e.g. 2, 1 for pixels twice as wide as tall. Only display and ratio-aware exports change, not the pixels.

• w (number) — Pixel width, a positive integer (1:1 = square).
• h (number) — Pixel height, a positive integer.

Returns nothing.

app.setSpriteSize(width, height) — changes, undoable

Resamples every cel (nearest-neighbor) to fit a new sprite size.

• width (number)
• height (number)

Returns nothing.

app.setUserData(target, userData?) — changes, undoable

Sets the user data (colour tag, text and custom properties, as in Aseprite) of a sprite, layer, cel, tag, slice or tileset. A cel target may be a tilemap frame. Linked cels share one user data, like their image. Changes only what you give, so setting the text keeps the colour, and writing your extension's properties namespace keeps everyone else's (as Aseprite's layer.data, layer.color and layer.properties(ns) are separate). Read it back from app.getSprite, getLayers, getCels, getTags, getSlices or getTileset (the userData field). Allowed on locked layers.

• target (table) — What to annotate: { kind = "sprite" }, { kind = "layer", layerId }, { kind = "cel", layerId, frameId }, { kind = "tag", tagId }, { kind = "slice", sliceId } or { kind = "tileset", layerId }.
  • kind (UserDataKind: "sprite" | "layer" | "cel" | "tag" | "slice" | "tileset") — Which kind of thing.
  • layerId (string) — For layer, cel and tileset targets.
  • frameId (string) — For cel targets.
  • tagId (string) — For tag targets.
  • sliceId (string) — For slice targets.
• userData (table, optional) — What to change: only the parts you give. text = "" or color = "" clears that part; in properties, each namespace you name is replaced and one set to {} is removed, while the others stay. nil removes all the user data.
  • color (string) — The colour tag as "#rrggbb" or "#rrggbbaa". Not accepted for tags (their colour is Tag.color).
  • text (string) — Free text (Aseprite's user data text).
  • properties (namespaces to properties: { [""] = { score = 3 }, ["my-extension"] = { ... } }. Values are plain JSON: nil-free, finite numbers, strings, booleans, lists and tables. properties[""] is your own namespace (Aseprite's user properties).) — Custom properties by namespace. Aseprite's typed values (uuid, fixed, point, ...) appear as tables with a $type key, e.g. { ["$type"] = "uuid", value = "..." }, and are written back as the Aseprite type.

Returns nothing.

app.trim() — changes, undoable

Crops the canvas to what's drawn across every frame, as Aseprite's Trim: the visible layers as shown, shrunk against transparency or a solid border colour (such as an opaque Background). No-op when nothing is left to cut.

Returns nothing.

As Markdown: document.md.