Your First Script

Setting Up

Before writing your first script, you need to know where to save it.

Opening the Scripts Folder

Open Aseprite
Go to File > Scripts > Open Scripts Folder
This opens your user scripts directory

On different platforms, this is typically:

Windows: C:\Users\YourName\AppData\Roaming\Aseprite\scripts
macOS: ~/Library/Application Support/Aseprite/scripts
Linux: ~/.config/aseprite/scripts

Creating Your First Script

Let’s create a simple script that creates a new sprite and draws a red square.

Step 1: Create the Script File

In your scripts folder, create a new file called my-first-script.lua
Open it in your favorite text editor

Step 2: Write the Script

Add the following code to your script:

my-first-script.lua

-- My First Aseprite Script
-- Creates a sprite and draws a red square

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

print("Created sprite: " .. sprite.width .. "x" .. sprite.height)

-- Define red color
local red = Color{ r=255, g=0, b=0 }

-- Draw a filled rectangle
app.useTool{
  tool = 'filled_rectangle',
  color = red,
  brush = Brush(1),
  points = { Point(8, 8), Point(24, 24) }
}

print("Drew a red square!")

Step 3: Run the Script

In Aseprite, go to File > Scripts > Rescan Scripts Folder
Then go to File > Scripts > my-first-script
Your script will run and create a new sprite with a red square

Understanding the Code

Let’s break down what each part does:

Creating a Sprite

local sprite = Sprite(32, 32)

This creates a new sprite that is 32x32 pixels. By default, it uses RGB color mode.

Printing Messages

print("Created sprite: " .. sprite.width .. "x" .. sprite.height)

The print() function outputs text to the console. You can see these messages in the Aseprite console or terminal (if running from command line).

Defining Colors

local red = Color{ r=255, g=0, b=0 }

Creates a red color using RGB values (0-255). You can also create colors other ways:

local blue = Color{ r=0, g=0, b=255, a=255 }  -- With alpha
local green = Color(0, 255, 0)  -- Positional arguments
local indexed = Color{ index=1 }  -- For indexed mode

Using Tools

app.useTool{
  tool = 'filled_rectangle',
  color = red,
  brush = Brush(1),
  points = { Point(8, 8), Point(24, 24) }
}

The app.useTool() function simulates using a drawing tool. Parameters:

tool: The tool name (e.g., ‘pencil’, ‘line’, ‘filled_rectangle’)
color: The color to draw with
brush: The brush to use (size and shape)
points: The points where to apply the tool

Common Tools

Here are some commonly used tools:

-- Pencil
app.useTool{
  tool = 'pencil',
  color = Color(255, 0, 0),
  points = { Point(5, 5), Point(10, 10) }
}

-- Line
app.useTool{
  tool = 'line',
  color = Color(0, 255, 0),
  points = { Point(0, 0), Point(31, 31) }
}

-- Filled ellipse
app.useTool{
  tool = 'filled_ellipse',
  color = Color(0, 0, 255),
  points = { Point(4, 4), Point(27, 27) }
}

-- Paint bucket
app.useTool{
  tool = 'paint_bucket',
  color = Color(255, 255, 0),
  points = { Point(16, 16) }
}

-- Eraser
app.useTool{
  tool = 'eraser',
  points = { Point(10, 10) }
}

Accessing the Active Sprite

Instead of creating a new sprite, you can work with the currently open sprite:

-- Get the active sprite
local sprite = app.activeSprite

if not sprite then
  print("No sprite is open!")
  return
end

print("Working with: " .. sprite.filename)
print("Size: " .. sprite.width .. "x" .. sprite.height)

Working with Layers

local sprite = Sprite(32, 32)

-- Create a new layer
local newLayer = sprite:newLayer()
newLayer.name = "My Layer"

-- Set as active layer
app.activeLayer = newLayer

-- Draw on the new layer
app.useTool{
  tool = 'pencil',
  color = Color(255, 0, 0),
  points = { Point(10, 10) }
}

-- Access layers by index
local firstLayer = sprite.layers[1]
print("First layer: " .. firstLayer.name)

Working with Frames

local sprite = Sprite(32, 32)

-- Create new frames
sprite:newFrame()  -- Frame 2
sprite:newFrame()  -- Frame 3

print("Total frames: " .. #sprite.frames)

-- Switch to frame 2
app.activeFrame = sprite.frames[2]

-- Draw different content on frame 2
app.useTool{
  tool = 'filled_rectangle',
  color = Color(0, 255, 0),
  points = { Point(8, 8), Point(24, 24) }
}

Saving the Sprite

local sprite = Sprite(32, 32)

-- Draw something
app.useTool{
  tool = 'filled_ellipse',
  color = Color(255, 0, 0),
  points = { Point(4, 4), Point(27, 27) }
}

-- Save the sprite
sprite:saveAs("my-sprite.aseprite")
print("Saved as: " .. sprite.filename)

-- Save as PNG
sprite:saveCopyAs("my-sprite.png")
print("Exported PNG")

Adding User Input with Dialogs

You can create dialogs to get input from users:

local dialog = Dialog("My First Dialog")

dialog:entry{
  id = "name",
  label = "Sprite Name:",
  text = "MySprite"
}

dialog:slider{
  id = "size",
  label = "Size:",
  min = 16,
  max = 256,
  value = 32
}

dialog:button{
  id = "ok",
  text = "Create",
  onclick = function()
    local data = dialog.data
    local sprite = Sprite(data.size, data.size)
    sprite.filename = data.name .. ".aseprite"
    print("Created: " .. sprite.filename)
    dialog:close()
  end
}

dialog:button{
  id = "cancel",
  text = "Cancel"
}

dialog:show()

Running Scripts from Command Line

You can run scripts without opening the Aseprite UI:

# Run a script in batch mode
aseprite -b -script my-first-script.lua

# Run a script on a specific file
aseprite -b input.aseprite -script process.lua -save-as output.png

Debugging Tips

Print Variables

local sprite = Sprite(32, 32)
print("Width: " .. sprite.width)
print("Height: " .. sprite.height)
print("Color Mode: " .. sprite.colorMode)

Check for Nil Values

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

Use Assert

local sprite = Sprite(32, 32)
assert(sprite.width == 32, "Width should be 32")
assert(sprite.height == 32, "Height should be 32")

Error Handling

local success, err = pcall(function()
  local sprite = app.activeSprite
  sprite:resize(100, 100)
end)

if not success then
  print("Error: " .. err)
end

Practice Exercises

Try creating these scripts to practice:

Checkerboard Pattern: Create a sprite with a checkerboard pattern
Rainbow Gradient: Draw a horizontal rainbow gradient
Circle Drawer: Create a script that draws circles at random positions
Layer Manager: Create a script that creates multiple named layers
Frame Animation: Create an animation by drawing different content on each frame

Next Steps

Automation Examples

Automate repetitive tasks with scripts

Batch Processing

Process multiple files efficiently

Custom Tools

Create your own drawing tools

API Reference

Complete API documentation

Getting Started

API Reference

Examples

Your First Script

Setting Up

Opening the Scripts Folder

Creating Your First Script

Step 1: Create the Script File

Step 2: Write the Script

Step 3: Run the Script

Understanding the Code

Creating a Sprite

Printing Messages

Defining Colors

Using Tools

Common Tools

Accessing the Active Sprite

Working with Layers

Working with Frames

Saving the Sprite

Adding User Input with Dialogs

Running Scripts from Command Line

Debugging Tips

Print Variables

Check for Nil Values

Use Assert

Error Handling

Practice Exercises

Next Steps

Automation Examples

Batch Processing

Custom Tools

API Reference

Build docs developers (and LLMs) love

Getting Started

API Reference

Examples

Documentation Index

​Setting Up

​Opening the Scripts Folder

​Creating Your First Script

​Step 1: Create the Script File

​Step 2: Write the Script

​Step 3: Run the Script

​Understanding the Code

​Creating a Sprite

​Printing Messages

​Defining Colors

​Using Tools

​Common Tools

​Accessing the Active Sprite

​Working with Layers

​Working with Frames

​Saving the Sprite

​Adding User Input with Dialogs

​Running Scripts from Command Line

​Debugging Tips

​Print Variables

​Check for Nil Values

​Use Assert

​Error Handling

​Practice Exercises

​Next Steps

Automation Examples

Batch Processing

Custom Tools

API Reference

Build docs developers (and LLMs) love

Setting Up

Opening the Scripts Folder

Creating Your First Script

Step 1: Create the Script File

Step 2: Write the Script

Step 3: Run the Script

Understanding the Code

Creating a Sprite

Printing Messages

Defining Colors

Using Tools

Common Tools

Accessing the Active Sprite

Working with Layers

Working with Frames

Saving the Sprite

Adding User Input with Dialogs

Running Scripts from Command Line

Debugging Tips

Print Variables

Check for Nil Values

Use Assert

Error Handling

Practice Exercises

Next Steps