Skip to main content

​
Overview

Aseprite includes a powerful scripting API that allows you to automate tasks, create custom tools, and extend the functionality of the editor. Scripts are written in Lua, a lightweight and easy-to-learn programming language.

​
What Can You Do with Scripts?

Aseprite’s scripting API provides access to:
  • Sprite manipulation: Create, modify, and save sprites programmatically
  • Layer and frame operations: Add, delete, and organize layers and frames
  • Drawing operations: Use tools like pencil, line, and paint bucket from scripts
  • Image processing: Access and modify pixel data directly
  • File operations: Batch process multiple files
  • UI dialogs: Create custom dialogs for user interaction
  • Command execution: Run any Aseprite command from scripts

​
The Lua API

The Aseprite Lua API is accessed through the global app object, which provides:

​
Core Objects

  • app.activeSprite - The currently active sprite
  • app.activeLayer - The currently selected layer
  • app.activeFrame - The current frame number
  • app.activeCel - The currently selected cel
  • app.activeImage - The image in the active cel

​
Main Classes

  • Sprite: Represents an Aseprite document
  • Layer: A layer in the sprite hierarchy
  • Cel: A cel (image in a specific frame)
  • Image: Pixel data and image manipulation
  • Color: Color values and color spaces
  • Rectangle: Rectangular regions
  • Point: 2D coordinates
  • Selection: Selection masks

​
Script Locations

Aseprite looks for scripts in the following locations:
  • User scripts folder: File > Scripts > Open Scripts Folder
  • Scripts placed here appear in the File > Scripts menu
  • You can organize scripts in subdirectories

​
Running Scripts

There are several ways to run scripts:
  1. From the menu: File > Scripts > [Your Script]
  2. Using the command line: 
    aseprite -b -script path/to/script.lua
  3. Using keyboard shortcuts: Assign shortcuts in Edit > Keyboard Shortcuts > Scripts

​
Example: Hello World

Here’s a simple script that prints a message: 
print("hello world")
print(1, 2, 3)

​
Example: Creating a Sprite

-- Create a new 32x64 pixel sprite
local sprite = Sprite(32, 64)

-- Access sprite properties
print("Width: " .. sprite.width)
print("Height: " .. sprite.height)
print("Color mode: " .. sprite.colorMode)

-- Resize the sprite
sprite:resize(64, 64)

​
Example: Drawing on the Canvas

-- Create a sprite
local sprite = Sprite(32, 32)

-- Use the pencil tool
app.useTool{
  tool = 'pencil',
  color = Color{ r=255, g=0, b=0 },  -- Red
  points = { Point(10, 10), Point(20, 20) }
}

-- Use the line tool
app.useTool{
  tool = 'line',
  color = Color{ r=0, g=0, b=255 },  -- Blue
  points = { Point(0, 0), Point(31, 31) }
}

​
Color Modes

Aseprite supports three color modes: 
-- RGB mode (default)
local rgbSprite = Sprite(32, 32, ColorMode.RGB)

-- Indexed mode (palette-based)
local indexedSprite = Sprite(32, 32, ColorMode.INDEXED)

-- Grayscale mode
local graySprite = Sprite(32, 32, ColorMode.GRAYSCALE)

​
Working with Pixels

local sprite = Sprite(4, 4)
local image = sprite.cels[1].image

-- Get pixel color
local pixelColor = image:getPixel(0, 0)

-- Set pixel color (RGBA)
local red = app.pixelColor.rgba(255, 0, 0, 255)
image:putPixel(2, 2, red)

-- Iterate over pixels
for y = 0, image.height - 1 do
  for x = 0, image.width - 1 do
    local color = image:getPixel(x, y)
    -- Process pixel...
  end
end

​
Undo/Redo Support

Many operations automatically create undo history entries: 
local sprite = Sprite(32, 32)

sprite:resize(64, 64)  -- Creates undo step

app.undo()  -- Undo resize
app.redo()  -- Redo resize

​
Error Handling

Use Lua’s pcall for error handling: 
local success, result = pcall(function()
  -- Code that might fail
  local sprite = app.activeSprite
  if not sprite then
    error("No active sprite")
  end
  return sprite.width
end)

if success then
  print("Width: " .. result)
else
  print("Error: " .. result)
end

​
Next Steps

Your First Script

Write and run your first Aseprite script

Automation Examples

Automate repetitive tasks

Batch Processing

Process multiple files at once

Custom Tools

Create custom drawing tools

​
Resources