Skip to main content

​
Overview

Automation scripts help you perform repetitive tasks quickly and consistently. These examples demonstrate common automation scenarios based on Aseprite’s actual test suite.

​
Adding Outlines to Sprites

This script automatically adds an outline to the current sprite’s content: 
-- Add outline to the active sprite
local sprite = app.activeSprite
if not sprite then
  print("No active sprite")
  return
end

-- Define outline color
local outlineColor = Color(0, 0, 0)  -- Black outline

-- Apply outline command
app.command.Outline{
  color = outlineColor,
  matrix = 'circle',  -- or 'square'
  place = 'outside'   -- 'inside' or 'outside'
}

print("Outline added successfully")

​
Automatically Resize Sprites

Resize all layers in a sprite to a specific size: 
-- Resize sprite to specific dimensions
local sprite = app.activeSprite
if not sprite then
  return app.alert("No sprite is active")
end

local targetWidth = 64
local targetHeight = 64

sprite:resize(targetWidth, targetHeight)
print("Resized to " .. targetWidth .. "x" .. targetHeight)

​
Crop to Selection

Automatically crop sprites to the current selection: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

if sprite.selection.isEmpty then
  return app.alert("No selection")
end

-- Crop to selection
app.command.CropSprite()
print("Cropped to selection")

​
Auto-Trim Transparent Pixels

Remove empty space around sprites: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

-- Store original size
local originalWidth = sprite.width
local originalHeight = sprite.height

-- Trim the sprite
app.command.AutocropSprite()

local newWidth = sprite.width
local newHeight = sprite.height

print(string.format("Trimmed from %dx%d to %dx%d",
  originalWidth, originalHeight, newWidth, newHeight))

​
Flatten Layers Automatically

local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

local layerCount = #sprite.layers

-- Flatten all layers
sprite:flatten()

print("Flattened " .. layerCount .. " layers into one")

​
Create Layer Structure

Automatically create a standard layer structure: 
local sprite = app.activeSprite
if not sprite then
  sprite = Sprite(32, 32)
end

-- Create organized layer groups
local layerNames = {
  { group = "Background", layers = { "BG Color", "BG Details" } },
  { group = "Character", layers = { "Body", "Face", "Clothes" } },
  { group = "Effects", layers = { "Shadows", "Highlights" } }
}

for _, groupData in ipairs(layerNames) do
  -- Create group
  local group = sprite:newGroup()
  group.name = groupData.group
  
  -- Create layers in group
  for _, layerName in ipairs(groupData.layers) do
    local layer = sprite:newLayer()
    layer.name = layerName
    layer.parent = group
  end
end

print("Created layer structure")

​
Auto-Number Frames

Add frame numbers to each frame: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

-- Create a layer for frame numbers
local numberLayer = sprite:newLayer()
numberLayer.name = "Frame Numbers"

local textColor = Color(255, 255, 255)

for i, frame in ipairs(sprite.frames) do
  app.activeFrame = frame
  
  -- Draw frame number (simple implementation)
  -- In practice, you'd use a text rendering library or pre-made number sprites
  local cel = sprite:newCel(numberLayer, frame)
  print("Frame " .. i)
end

print("Added frame numbers")

​
Apply Color Adjustments in Bulk

Adjust brightness/contrast on all frames: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

-- Save current frame
local originalFrame = app.activeFrame

-- Apply brightness to all frames
for i, frame in ipairs(sprite.frames) do
  app.activeFrame = frame
  app.command.BrightnessContrast{
    brightness = 25,
    contrast = 10
  }
  print("Processed frame " .. i)
end

-- Restore original frame
app.activeFrame = originalFrame

print("Applied adjustments to " .. #sprite.frames .. " frames")

​
Replace Colors Across Sprite

Replace all instances of one color with another: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

local fromColor = Color(255, 0, 0)   -- Red
local toColor = Color(0, 0, 255)     -- Blue

-- Replace color using command
app.command.ReplaceColor{
  from = fromColor,
  to = toColor
}

print("Replaced red with blue")

​
Create Animation Preview

Generate a contact sheet of all frames: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

local frameCount = #sprite.frames
local cols = math.ceil(math.sqrt(frameCount))
local rows = math.ceil(frameCount / cols)

-- Export as sprite sheet
app.command.ExportSpriteSheet{
  type = SpriteSheetType.HORIZONTAL,
  textureFilename = "preview-sheet.png",
  shapePadding = 2,
  borderPadding = 2
}

print("Created preview sheet: preview-sheet.png")

​
Smart Selection by Color Range

Select all pixels within a color range: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

-- Select all red-ish colors
local targetColor = Color(255, 0, 0)
local tolerance = 32

app.command.MaskByColor{
  color = targetColor,
  tolerance = tolerance
}

print("Selected colors similar to red")

​
Apply Filter to Selection

Apply filters only to selected areas: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

if sprite.selection.isEmpty then
  return app.alert("Make a selection first")
end

-- Apply blur filter
app.command.ConvolutionMatrix{
  fromResource = "blur-3x3"
}

print("Applied blur to selection")

​
Invert Colors

Quickly invert colors in the active sprite: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

-- Invert all colors
app.command.InvertColor()

print("Inverted colors")

​
Adjust Hue/Saturation

Shift hue or adjust saturation: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

-- Shift hue by 60 degrees
app.command.HueSaturation{
  hue = 60,
  saturation = 0,
  value = 0
}

print("Shifted hue by 60 degrees")

​
Create Palette from Sprite

Extract unique colors and create a palette: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

if sprite.colorMode ~= ColorMode.INDEXED then
  -- Convert to indexed to extract palette
  app.command.ChangePixelFormat{ format="indexed" }
end

local palette = sprite.palettes[1]
print("Palette has " .. #palette .. " colors")

for i = 0, #palette - 1 do
  local color = palette:getColor(i)
  print(string.format("Color %d: RGB(%d, %d, %d)",
    i, color.red, color.green, color.blue))
end

​
Flip Sprites Automatically

local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

-- Flip horizontally
app.command.Flip{ orientation = "horizontal" }

print("Flipped sprite horizontally")

-- For vertical flip:
-- app.command.Flip{ orientation = "vertical" }

​
Create Animated Rotation

Create frames with rotated versions: 
local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

local steps = 8  -- Number of rotation steps
local angleStep = 360 / steps

for i = 1, steps - 1 do
  sprite:newFrame()
  app.activeFrame = sprite.frames[i + 1]
  
  -- Rotate by angle
  app.command.Rotate{
    angle = angleStep * i
  }
  
  print("Created frame " .. (i + 1) .. " (rotated " .. (angleStep * i) .. " degrees)")
end

print("Created " .. steps .. "-frame rotation animation")

​
Export All Layers as Separate Files

local sprite = app.activeSprite
if not sprite then
  return app.alert("No active sprite")
end

local baseName = sprite.filename or "sprite"
baseName = app.fs.fileTitle(baseName)

for i, layer in ipairs(sprite.layers) do
  -- Hide all layers
  for _, l in ipairs(sprite.layers) do
    l.isVisible = false
  end
  
  -- Show only current layer
  layer.isVisible = true
  
  -- Export
  local filename = baseName .. "_" .. layer.name .. ".png"
  sprite:saveCopyAs(filename)
  
  print("Exported: " .. filename)
end

-- Show all layers again
for _, l in ipairs(sprite.layers) do
  l.isVisible = true
end

print("Exported " .. #sprite.layers .. " layers")

​
Next Steps

Batch Processing

Process multiple files at once

Custom Tools

Create custom drawing tools

Scripting Introduction

Learn the basics of Aseprite scripting

Build docs developers (and LLMs) love

Get started for freeTalk to us