Pure Aseprite scripting API. Verified against Aseprite 1.3.18.6-dev; do not rely on APIs newer than 1.3.17.

Pitfalls

Undo: clone, mutate, assign back. cel.image is a live reference; mutating it in place (cel.image:drawPixel(...)) is not recorded in undo history and is not rolled back when the script errors. Recorded form:

local img = cel.image:clone()
img:drawPixel(x, y, color)
cel.image = img

Cel position. cel.image pixel (0,0) sits at cel.position, not at sprite (0,0). Convert: sprite coords = image coords + cel.position. Sprite:newCel(layer, frame, image, Point(x, y)) sets the offset; cel.bounds gives the sprite-space rectangle.

Pixel values follow the sprite's color mode. image:getPixel / drawPixel use raw pixel values:

RGB: app.pixelColor.rgba(r,g,b,a); read with rgbaR/G/B/A.
Grayscale: app.pixelColor.graya(v,a); read with grayaV/A.
Indexed: the palette index (integer, e.g. 1); resolve colors via sprite.palettes[1]:getColor(i).

aseprite-lua

Pitfalls