Palette

app.addColorCycle(fromIndex, toIndex, opts?) — changes, undoable

Adds a colour-cycling range (indexed sprites): while playing, the colours of that palette range rotate. Pixels aren't changed; use app.bakeColorCycles to turn the cycle into per-frame palettes.

• fromIndex (number) — First palette index of the cycled range.
• toIndex (number) — Last palette index of the range (inclusive).
• opts (table, optional)
  • direction (string; default "forward") — "forward" moves each colour to the next higher index, "reverse" to the lower.
  • framesPerStep (integer 1–1000; default 1) — Playback frames per one-step rotation.

Returns (string): The new cycle's id.

app.bakeColorCycles(frames?) — changes, undoable

Bakes the colour cycles into per-frame palettes (adding frames if needed) so exports such as GIF reproduce the cycling, then removes the cycles. Indexed sprites only.

• frames (number, optional) — Total frames of the baked animation (at least the current count); default: one full loop of the cycles. Frames are appended after the last one.

Returns nothing.

app.cleanPalette(opts?) — changes, undoable

Cleans the palette: merges duplicate and similar colours into their first occurrence and removes unused entries. On indexed sprites pixels follow their colours.

• opts (table, optional) — { removeDuplicates = bool, removeUnused = bool, mergeDistance = 0-100 (delta E; ~2 is barely visible, 10 clearly different), frameId = palette in effect at this frame }. Every option defaults to off.

Returns nothing.

app.createPaletteChange(frameId, colors?) — changes, undoable

Starts a new palette at a frame: that frame and the ones after it (until the next change) resolve indexed pixels through it. Pixel indices don't change.

• frameId (string) — Frame the new palette starts at (not the first frame).
• colors (table, optional) — The palette from that frame on, an array of hex colors; default: a copy of the palette in effect there.

Returns nothing.

app.createPaletteRamp(from, to, count?, space?, mode?, frameId?) — changes, undoable

Generates a color ramp between two palette entries (Aseprite's palette Gradient): by default it overwrites the entries between them, or with mode "insert" inserts new colors before the later entry. On indexed sprites an insert shifts pixel indices so the image is unchanged. One undoable step.

• from (number) — Palette index of one end of the ramp (0-based).
• to (number) — Palette index of the other end (0-based).
• count (number, optional) — How many colors to insert between them (1-256). Required for mode "insert"; "replace" fills every entry between the ends and ignores it.
• space (string, optional) — Interpolation space: "oklab" (default, perceptually even), "oklch", "rgb" or "hsl".
• mode (string, optional) — "replace" overwrites the entries between the two ends with the ramp (Aseprite's palette Gradient; pixels are untouched); "insert" adds count new colors before the later end. Default: "replace" when entries lie between the ends, otherwise "insert".
• frameId (string, optional) — Edit the palette in effect at this frame (palettes can change per frame); default: the first frame's palette. On indexed sprites "insert" only shifts the pixels of the frames sharing that palette.

Returns nothing.

app.getColorCycles() — reads

The colour-cycling ranges of an indexed sprite: { id, fromIndex, toIndex, direction, framesPerStep } each.

Returns (table): Array of colour cycle tables.

app.getPalette(frameId?) — reads

The palette as an array of hex color strings, "#rrggbb" or, for entries with alpha below 255, "#rrggbbaa", e.g. { "#ff0000", "#00ff0080", ... }. Pass a frame id for that frame's palette.

• frameId (string, optional) — Frame whose palette to read (palettes can change per frame); omit for the first frame's palette.

Returns (table): Array of hex color strings.

app.insertPaletteEntries(index, colors, frameId?) — changes, undoable

Inserts palette entries at an index. On indexed sprites every pixel (and the transparent index) follows its entry, so the image is unchanged.

• index (number) — Where the first new entry goes (0-based; the palette's length appends).
• colors (table) — Array of hex color strings, "#rrggbb" or "#rrggbbaa", e.g. { "#ff0000", "#00ff0080" }.
• frameId (string, optional) — Edit the palette in effect at this frame (palettes can change per frame); default: the first frame's palette.

Returns nothing.

app.movePaletteEntry(fromIndex, toIndex, frameId?) — changes, undoable

Moves a palette entry to a new position. On indexed sprites every pixel follows its color, so the image is unchanged.

• fromIndex (number) — Current palette index (0-based).
• toIndex (number) — Index the entry should end up at (0-based).
• frameId (string, optional) — Edit the palette in effect at this frame (palettes can change per frame); default: the first frame's palette.

Returns nothing.

app.remapColors(mappings, cels) — changes, undoable, refused on a locked layer

Replaces exact colours with other colours across a set of cels: the Palette Audit's remap. RGBA and grayscale sprites.

• mappings (table) — Array of { from = "#rrggbb", to = "#rrggbb" } (either may carry alpha, "#rrggbbaa"); every mapping applies at once.
• cels (table) — Array of { layerId = ..., frameId = ... }: the cels to recolour (image layers).

Returns nothing.

app.removeColorCycle(cycleId) — changes, undoable

Removes a colour cycle.

• cycleId (string)

Returns nothing.

app.removePaletteChange(frameId) — changes, undoable

Removes the palette change at a frame, so it uses the palette before it again. Pixel indices don't change.

• frameId (string) — Frame whose palette change to remove.

Returns nothing.

app.removePaletteEntries(indices, frameId?) — changes, undoable

Removes palette entries by index. On indexed sprites the removed entries' pixels become transparent and every other pixel (and the transparent index) follows its entry.

• indices (table) — Array of the palette indices to remove (0-based), e.g. { 3 } or { 4, 5, 6 }.
• frameId (string, optional) — Edit the palette in effect at this frame (palettes can change per frame); default: the first frame's palette.

Returns nothing.

app.setColorDepth(depth?) — changes, undoable

Pins the sprite to a colour depth, like a console that can only show certain values: pixels, tiles and palettes are folded into it now (one undo step), and everything drawn later stays on it. nil removes it (the lost precision doesn't come back). Read it back with app.getSprite().colorDepth.

• depth (table, optional) — The colour depth as levels per channel, or nil to remove it. n bits are 2^n levels (3 bits = 8).
  • red (integer 2–256) — Levels of red (with green and blue).
  • green (integer 2–256) — Levels of green.
  • blue (integer 2–256) — Levels of blue.
  • gray (integer 2–256) — Levels of gray, instead of red, green and blue: every colour becomes a gray.
  • profile (string) — The hardware profile id it stands for (e.g. "mega-drive"), shown in the editor.

Returns nothing.

app.setPalette(colors, frameId?) — changes, undoable

Replaces the sprite's whole palette slot by slot. On indexed sprites every pixel keeps its index and shows the new color at it (a shorter palette is padded with the old colors of slots still in use). To add or remove colors with pixels following them, use app.insertPaletteEntries / app.removePaletteEntries.

• colors (table) — Array of hex color strings, "#rrggbb" or "#rrggbbaa" (alpha), e.g. { "#ff0000", "#00ff0080" }.
• frameId (string, optional) — Edit the palette in effect at this frame (palettes can change per frame); default: the first frame's palette.

Returns nothing.

app.setPaletteEntry(index, color, frameId?) — changes, undoable

Recolors one palette entry in place. On indexed sprites, every pixel using that entry shows the new color.

• index (number) — Palette entry to recolor (0-based).
• color (string) — Hex color, "#rrggbb" (opaque) or "#rrggbbaa" (with alpha), e.g. "#ff0000" or "#ff000080".
• frameId (string, optional) — Edit the palette in effect at this frame (palettes can change per frame); default: the first frame's palette.

Returns nothing.

app.setPaletteGroups(groups) — changes, undoable

Replaces the palette groups: named labels over palette index ranges. They label slots, so moving or sorting colours doesn't move a group.

• groups (table) — Array of { name = "Skin", from = 0, to = 3 } (0-based inclusive palette indices), sorted by from and not overlapping. {} removes every group.

Returns nothing.

app.setPaletteLock(locked) — changes, undoable

Turns Palette Lock on or off. RGBA sprites only (indexed sprites always paint palette colours); saved with the file.

• locked (boolean) — true: every draw command on an RGBA sprite snaps the pixels it paints to the nearest palette colour.

Returns nothing.

app.setTransparentIndex(index) — changes, undoable

Sets the indexed sprite's transparent color index (Aseprite's Sprite Properties > Transparent Color). Only the property changes, not the pixel bytes.

• index (number) — Palette index (0-255) whose pixels are transparent on indexed sprites (default 0).

Returns nothing.

app.sortPalette(by, descending?, from?, to?, frameId?) — changes, undoable

Sorts the palette (or the from..to range) by a color property, ordered as Aseprite's palette sort: fully transparent entries first in either direction; hue puts grays first (by value) when ascending, last when descending; hue, saturation and brightness compare whole degrees and percent (saturation ties by brightness and the other way round); luminance weighs the squared channels. Remaining ties keep their order. On indexed sprites every pixel follows its color, so the image is unchanged.

• by (string) — Sort key: "hue", "saturation", "brightness", "luminance", "red", "green", "blue" or "alpha".
• descending (boolean, optional) — Sort high-to-low (default false).
• from (number, optional) — First palette index to sort (0-based, default 0).
• to (number, optional) — Last palette index to sort (inclusive, default: last).
• frameId (string, optional) — Edit the palette in effect at this frame (palettes can change per frame); default: the first frame's palette.

Returns nothing.

app.updateColorCycle(cycleId, props?) — changes, undoable

Changes a colour cycle's range, direction or speed.

• cycleId (string)
• props (table, optional)
  • fromIndex (integer 0–255) — First palette index of the range.
  • toIndex (integer 0–255) — Last palette index of the range (inclusive).
  • direction (string) — "forward" or "reverse".
  • framesPerStep (integer 1–1000) — Playback frames per one-step rotation.

Returns nothing.

As Markdown: palette.md.