Skip to main content
The global app object provides access to the application state, active documents, and UI elements.

​
Properties

​
sprite
Sprite
Active sprite. Same as activeSprite.
​
activeSprite
Sprite
The currently active sprite document.
​
layer
Layer
Active layer. Same as activeLayer.
​
activeLayer
Layer
The currently selected layer.
​
frame
Frame
Active frame. Same as activeFrame.
​
activeFrame
Frame
The currently selected frame.
​
cel
Cel
Active cel at the current layer and frame.
​
image
Image
The image from the active cel.
​
tag
Tag
Active tag at the current frame.
​
tool
Tool
Currently selected tool.
​
brush
Brush
Currently selected brush.
​
sprites
array
Array of all open sprites.
​
fgColor
Color
Foreground color.
​
bgColor
Color
Background color.
​
fgTile
number
Foreground tile index (for tilemap mode).
​
bgTile
number
Background tile index (for tilemap mode).
​
version
Version
Aseprite version.
​
apiVersion
number
API version number.
​
site
Site
Active site (sprite, layer, frame location).
​
range
Range
Current selection range in timeline.
​
isUIAvailable
boolean
True if running with UI, false if running from CLI.
​
defaultPalette
Palette
Default palette for new sprites.
​
window
Window
Main application window.
​
events
Events
Application-level events.
​
theme
Theme
Current UI theme.
​
uiScale
number
UI scale factor.
​
editor
Editor
Active sprite editor.
​
clipboard
Clipboard
System clipboard access.

​
Methods

​
app.open(filename)

​
filename
string
required
Path to the sprite file to open.
Opens a sprite from a file and returns the Sprite object. 
local sprite = app.open("path/to/file.aseprite")

​
app.exit()

Closes Aseprite. 
app.exit()

​
app.transaction(function)

​
function
function
required
Function to execute within the transaction.
Executes a function within an undo/redo transaction. If the function completes successfully, the transaction is committed. 
app.transaction(function()
  sprite:newLayer()
  sprite:newFrame()
end)

​
app.transaction(label, function)

​
label
string
required
Label for the undo/redo entry.
​
function
function
required
Function to execute within the transaction.
app.transaction("Create Layer", function()
  sprite:newLayer()
end)

​
app.undo()

Undoes the last operation. 
app.undo()

​
app.redo()

Redoes the previously undone operation. 
app.redo()

​
app.alert(text)

​
text
string
required
Message to display.
Shows an alert dialog with the given text. 
app.alert("Operation completed!")

​
app.alert(options)

​
options
table
required
Alert configuration table.
Shows a customizable alert dialog. 
local result = app.alert{
  title = "Confirm",
  text = "Are you sure?",
  buttons = {"Yes", "No"}
}
if result == 1 then
  print("User clicked Yes")
end

​
app.refresh()

Refreshes the screen. 
app.refresh()

​
app.useTool(options)

​
options
table
required
Tool usage configuration.
Uses a drawing tool programmatically. 
app.useTool{
  tool = "pencil",
  color = Color{ r=255, g=0, b=0 },
  brush = Brush{ size=4 },
  points = { Point(10, 10), Point(20, 20) },
  layer = app.layer,
  frame = app.frame
}

​
app.tip(text, duration)

​
text
string
required
Tooltip text.
​
duration
number
Duration in seconds (default: 2).
Shows a tooltip in the status bar. 
app.tip("Processing...", 3)

​
Examples

​
Creating a New Sprite

local sprite = Sprite(64, 64)
app.sprite = sprite
print("Created sprite:", sprite.width, "x", sprite.height)

​
Working with Colors

app.fgColor = Color{ r=255, g=0, b=0 }
app.bgColor = Color{ r=0, g=0, b=255 }
print("Foreground:", app.fgColor)
print("Background:", app.bgColor)

​
Using Transactions

local sprite = app.sprite
app.transaction("Add Multiple Layers", function()
  for i=1,5 do
    local layer = sprite:newLayer()
    layer.name = "Layer " .. i
  end
end)