Adjustments

app.antiAlias(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Anti-aliases the stair steps where color A meets color B on a layer's cels, pixel-art style, as a single undo step: only the pixels next to a one-pixel step change, the longer the straight run the more of them, while straight edges, corners and 45-degree diagonals stay crisp (app.setLayerEffects keeps it live instead, kind "antiAlias"). Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are smoothed (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • cels (Array of { layerId = ..., frameId = ... }) — Smooth these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • a (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); default "#000000") — Color A: the colour whose stair steps are smoothed where it meets color B.
  • anyA (boolean; default false) — Pass true to treat every visible colour other than B as A (to smooth a whole outline).
  • b (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); default "#ffffff") — Color B: the colour A meets. A fully transparent colour ("#00000000") means any transparent pixel; the in-betweens then fade A's alpha.
  • steps (integer 1–4; default 2) — How many in-between colours are generated from A to B (in OKLCH), and the most pixels one step takes.
  • into (string; default "b") — Which side of the edge is repainted: "a", "b" or "both".
  • strength (integer 0–100; default 100) — How far along each straight run the smoothing reaches: 100 is up to half the run.
  • colors (string; default "any") — Pass "palette" to snap the in-between colours to the nearest palette entries. Indexed sprites always do.
  • respectSelection (boolean; default false) — Pass true to change only pixels inside the current selection. By default the selection is ignored.

Returns nothing.

app.autoShade(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Shades flat colours from a light direction, as a single undo step (app.setLayerEffects with kind "autoShade" keeps it live instead): pixels near the lit edge of each region get lighter steps, near the far edge darker ones. The steps follow the ramp when it holds the colour, else they are computed in OKLCH. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are shaded (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • cels (Array of { layerId = ..., frameId = ... }) — Shade these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • target (string; default "base") — What to shade: "base" shades the pixels of the base colour only, "all" shades every flat colour with a ramp of its own.
  • base (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); default "#808080") — The colour to shade when target is "base".
  • angle (integer 0–359; default 135) — Where the light comes from, in degrees counter-clockwise from the right: 90 is above, 135 the top left, 270 below.
  • highlights (integer 0–5; default 2) — How many lighter steps the lit side gets; the edge is the lightest.
  • shadows (integer 0–5; default 2) — How many darker steps the far side gets; the edge is the darkest.
  • width (integer 1–4; default 1) — How many pixels deep each step is.
  • hueShift (integer 0–100; default 30) — How far computed highlights turn toward warm yellow and shadows toward cool blue.
  • chroma (integer -100–100; default 0) — How much more (or, negative, less) colourful each computed step gets.
  • rim (boolean; default false) — Pass true for a 1 px highlight along the outer edge of the shadow side.
  • outline (boolean; default false) — Pass true to paint the shape's outer edge one step darker than the deepest shadow.
  • colors (string; default "any") — "palette" snaps the computed steps to the frame's palette; indexed sprites always do.
  • ramp (Array of colors) — A ramp of colours, in either order, to walk instead of computing the steps when it holds the colour being shaded (for example app.getContext().shades). Empty: computed.
  • respectSelection (boolean; default false) — Pass true to shade only inside the current selection. By default the selection is ignored.

Returns nothing.

app.brightnessContrast(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Brightness/Contrast on a layer's cels, as a single undo step: each channel becomes 128 + factor * (value + brightness * 2.55 - 128), rounded and clamped. Not Aseprite's curve (it applies contrast first and scales brightness). Fully transparent pixels are left alone. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • brightness (number -100–100; default 0) — Adds brightness * 2.55 to every colour channel, before the contrast scale.
  • contrast (number -100–100; default 0) — Scales each channel's distance from 128 by 259(C + 255) / (255(259 - C)), with C = contrast * 2.55: -100 flattens all colour to 128, +100 is close to a threshold.
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.colorBalance(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Color Balance on a layer's cels, as a single undo step: shifts the colour of shadows, midtones and highlights (weighted by luma, 100 = 127.5 levels at full weight). Fully transparent pixels are left alone. On grayscale sprites only shifts with equal red, green and blue are accepted. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • shadows ({ red = -100..100, green = -100..100, blue = -100..100 }) — The shift for dark pixels. Positive red moves toward red, negative toward cyan; likewise green/magenta and blue/yellow.
  • midtones ({ red = -100..100, green = -100..100, blue = -100..100 }) — The shift for mid-luma pixels.
  • highlights ({ red = -100..100, green = -100..100, blue = -100..100 }) — The shift for light pixels.
  • preserveLuminosity (boolean; default true) — Re-add the lightness the shift changed, so only the colour moves.
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.colorCurve(layerId, frameIds, curves, opts?) — changes, undoable, refused on a locked layer

Filter > Color Curve on a layer's cels, as a single undo step: a monotone cubic curve per channel (Aseprite's is linear, with one curve). Fully transparent pixels are left alone. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• curves (AdjustCurveChannel: "value" | "red" | "green" | "blue" | "alpha") — Channel name to control points, e.g. { red = { {0, 0}, {128, 180}, {255, 255} } }. Channels: "value" (red, green and blue alike), "red", "green", "blue", "alpha"; grayscale sprites take only "value" and "alpha". Points are {x, y} pairs (0-255, x strictly increasing, 2 or more); the curve is a smooth monotone spline through them.
• opts (table, optional)
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.convolutionMatrix(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Convolution Matrix on a layer's cels, as a single undo step: blur, sharpen, edge detect, emboss or any kernel you give. Transparent neighbours do not darken colours. Indexed sprites need indexedMode "remap" (results snap to the nearest palette entry). Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • preset (string) — A ready-made kernel instead of kernel/width/height: identity, gaussian3, box3, gaussian5, box5, sharpen, edge, emboss, sobelH, sobelV.
  • width (integer 1–9) — Kernel width (odd). Required with kernel.
  • height (integer 1–9) — Kernel height (odd). Required with kernel.
  • kernel (list of width * height numbers, row by row) — The weights applied to each pixel's neighbourhood, e.g. { 0, -1, 0, -1, 5, -1, 0, -1, 0 } sharpens.
  • divisor (number; default the sum of the kernel (1 if it sums to 0)) — Each weighted sum is divided by this (not 0).
  • bias (number -255–255; default 0) — Added to each channel after dividing (128 centres an edge/emboss result on gray).
  • red (boolean; default true) — Convolve the red channel. On grayscale sprites red, green and blue are the one gray channel: set all three alike.
  • green (boolean; default true) — Convolve the green channel.
  • blue (boolean; default true) — Convolve the blue channel.
  • alpha (boolean; default false) — Convolve the alpha channel too (a blur then grows into transparent pixels). Off, fully transparent pixels stay untouched.
  • edges (ConvolveEdges: "clamp" | "tiled"; default "clamp") — What is read beyond the cel's edge.
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.despeckle(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Despeckle (a median filter) on a layer's cels, as a single undo step: removes isolated pixels and smooths noise. Indexed sprites need indexedMode "remap". Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • width (integer 1–9; default 3) — Median window width (odd).
  • height (integer 1–9; default 3) — Median window height (odd).
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.

Returns nothing.

app.dropShadow(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Draws a drop shadow, glow or inner shadow for the shapes on a layer's cels, as a single undo step (app.setLayerEffects keeps it live instead). Outside shadows grow the cel, clipped to the canvas, and sit beneath the art. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer get the shadow (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • cels (Array of { layerId = ..., frameId = ... }) — Shadow these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • place (OutlinePlace: "outside" | "inside"; default "outside") — A drop shadow or glow beneath the art ("outside"), or an inner shadow over it ("inside").
  • dx (integer -10–10; default 1) — How far the shadow falls to the right (negative: left). 0 and 0 makes a glow.
  • dy (integer -10–10; default 1) — How far the shadow falls downward (negative: up).
  • spread (integer 0–10; default 0) — How many pixels the shadow grows past the art's silhouette.
  • shape (FxShape: "circle" | "square" | "diamond"; default "circle") — The footprint of the spread.
  • softness (integer 0–8; default 0) — How many pixels the shadow's edge fades over (a blur radius); 0 is a hard edge.
  • edge (ShadowEdge: "dithered" | "hard" | "smooth"; default "dithered") — How a soft edge (softness above 0) is drawn: "dithered" keeps one colour as an ordered dither that stays put as the art moves, "hard" cuts it at half strength, "smooth" makes real half-transparent pixels.
  • color (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); default "#00000080") — The shadow colour; its alpha is the shadow's opacity. On an indexed sprite the result snaps to the palette.
  • respectSelection (boolean; default false) — Pass true to paint only inside the current selection. By default the selection is ignored.

Returns nothing.

app.gradientMap(layerId, frameIds, stops, opts?) — changes, undoable, refused on a locked layer

Filter > Gradient Map on a layer's cels, as a single undo step: each pixel's luma picks a colour from the ramp. A pixel keeps its alpha. Fully transparent pixels are left alone. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• stops (table) — 2-32 gradient stops, { { color = ..., position = 0 }, { color = ..., position = 1 } }: the colour a pixel takes at that luma (0 = darkest, 1 = lightest).
• opts (table, optional)
  • space (GradientMapSpace: "rgb" | "oklab" | "oklch"; default "oklab") — The colour space blended in between stops.
  • reverse (boolean; default false) — Run the ramp from light to dark.
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.hueSaturation(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Hue/Saturation in hsv, hsl or a perceptual oklch mode on a layer's cels, as a single undo step. Positive lightness and alpha lift toward full rather than multiplying as Aseprite does, so +50 lightness turns black into mid-gray. Fully transparent pixels are left alone. On grayscale sprites hue and saturation have no effect. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • mode (AdjustHueMode: "hsv" | "hsl" | "oklch"; default "hsv") — The colour model to work in.
  • hue (number -180–180; default 0) — Degrees added to every hue.
  • saturation (number -100–100; default 0) — Scales saturation (chroma in oklch mode): -100 is gray, +100 doubles it (capped at full, or at the sRGB gamut in oklch mode). Grays stay gray.
  • lightness (number -100–100; default 0) — Lightness in hsl and oklch modes, value in hsv mode. Positive moves that share of the remaining way to white/full (l + (1 - l) * k, k = lightness / 100), so +100 reaches it; negative scales toward black (l * (1 + k)), so -100 reaches it.
  • alpha (number -100–100; default 0) — The same lift on alpha (rounded): +100 makes every non-transparent pixel opaque, -100 makes them transparent.
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.invertColor(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Invert Color, as in Aseprite, on a layer's cels, as a single undo step. Fully transparent pixels are left alone. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • red (boolean; default true) — Invert the red channel. On grayscale sprites red, green and blue are the one gray channel: set all three alike.
  • green (boolean; default true) — Invert the green channel.
  • blue (boolean; default true) — Invert the blue channel.
  • alpha (boolean; default false) — Invert the alpha channel (fully transparent pixels still stay transparent).
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.levels(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Levels on a layer's cels, as a single undo step: each channel is rescaled from the input range, bent by gamma and mapped to the output range. Fully transparent pixels are left alone. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • inBlack (integer 0–254; default 0) — Input values at or below this become outBlack.
  • inWhite (integer 1–255; default 255) — Input values at or above this become outWhite. Must be above inBlack.
  • gamma (number 0.1–10; default 1) — Midtone curve: above 1 brightens the midtones, below 1 darkens them.
  • outBlack (integer 0–255; default 0) — The output value for black input.
  • outWhite (integer 0–255; default 255) — The output value for white input. Below outBlack inverts.
  • red ({ inBlack, inWhite, gamma, outBlack, outWhite }) — Levels for the red channel alone, applied after the master ones. Grayscale sprites refuse single channels.
  • green ({ inBlack, inWhite, gamma, outBlack, outWhite }) — Levels for the green channel alone.
  • blue ({ inBlack, inWhite, gamma, outBlack, outWhite }) — Levels for the blue channel alone.
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.posterize(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Posterize: reduces each colour channel of a layer's cels to a few levels, as a single undo step. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • levels (integer 2–256; default 4) — Distinct levels kept per colour channel (alpha is untouched).
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.reduceColors(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Reduce Colors: maps a layer's cels onto a few colours (generated from those cels, or the palette), optionally dithered, as a single undo step. Alpha is kept; the sprite stays in its colour mode. Indexed sprites need indexedMode "remap". Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • colors (integer 1–256; default 16) — How many colours to keep (paletteSource "generate").
  • paletteSource (ReduceColorsPalette: "generate" | "palette"; default "generate") — Generate the colours from the cels, or use the sprite's palette.
  • dithering (DitherMethod: "none" | "bayer2" | "bayer4" | "bayer8" | "floydSteinberg" | "atkinson"; default "none") — How in-between colours are approximated.
  • ditherAmount (integer 0–100; default 100) — Dithering strength (0 = nearest colour only).
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.

Returns nothing.

app.replaceColor(layerId, frameIds, from, to, opts?) — changes, undoable, refused on a locked layer

Filter > Replace Color, as in Aseprite, on a layer's cels, as a single undo step. Fully transparent pixels are never matched. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• from (color) — The colour to find.
• to (color) — The colour to put in its place (alpha included).
• opts (table, optional)
  • tolerance (integer 0–255; default 0) — A pixel matches when none of its r, g, b, a channels is more than this far from from.
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

app.threshold(layerId, frameIds, opts?) — changes, undoable, refused on a locked layer

Filter > Threshold on a layer's cels, as a single undo step: every pixel becomes one of two colours by its luma (Aseprite's rgb_luma). Fully transparent pixels are left alone. Image layers only.

• layerId (string)
• frameIds (table) — Array of frame ids whose cels on this layer are adjusted (one frame for the active cel, every frame for all of them).
• opts (table, optional)
  • level (integer 0–255; default 128) — Pixels whose luma is at least this become above, the rest below.
  • below (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); default "#000000") — The colour of pixels under the level. Alpha is ignored: a pixel keeps its own.
  • above (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); default "#ffffff") — The colour of pixels at or over the level. Alpha is ignored.
  • cels (Array of { layerId = ..., frameId = ... }) — Adjust these cels, across layers and frames, instead of layerId/frameIds (pass nil for both).
  • respectSelection (boolean; default false) — Pass true to adjust only inside the current selection. By default the selection is ignored.
  • indexedMode (AdjustIndexedMode: "remap" | "palette"; default "remap") — Indexed sprites only: recolour the pixels and snap them to the nearest palette entry, or edit the palette entries the cels use.

Returns nothing.

As Markdown: adjustments.md.