Aseprite API

The Aseprite API is organized into several categories. Use these to navigate the available automation surface:

Global Namespace

Includes core modules like app, app.clipboard, app.command, app.fs, app.os, app.pixelColor, app.theme, and json.

Constants

Enumerations for controlling behavior, such as Align, BlendMode, ColorMode, SelectionMode, BrushType, and TilemapMode.

Classes and Objects

Main data structures and entities including Sprite, Layer, Cel, Frame, Image, Palette, Tag, Slice, Dialog, and Plugin.

Lua Libraries

In addition to the Aseprite API, you have access to standard Lua libraries for string manipulation, math, tables, and coroutines. Note that some os and io functions (like os.execute or io.open) may trigger user permission prompts.

The onreceive callback is the primary way to react to the WebSocket lifecycle. It is called when the connection opens, when data is received, when the connection closes, or when an error occurs. Use the WebSocketMessageType to differentiate between these events.

Common Event Types:

• WebSocketMessageType.OPEN: The connection has been successfully established.
• WebSocketMessageType.TEXT: A text message was received.
• WebSocketMessageType.CLOSE: The connection has been closed.

local function handleMessage(mt, data, error)
  if mt == WebSocketMessageType.OPEN then
    print("Connection open.")
  elseif mt == WebSocketMessageType.TEXT then
    print("Message received: " .. data)
  elseif mt == WebSocketMessageType.CLOSE then
    print("Connection closed")
  end
end

local ws = WebSocket{
    onreceive = handleMessage,
    url = "http://127.0.0.1:9000"
}

Visibility and expansion properties describe the local state of the layer, not its state within the global hierarchy.

• Visibility: Layer.isVisible controls if the layer is visible. If a parent group is hidden, the child is effectively hidden, but child.isVisible will still return true if it was set to true.
• Group Expansion: For group layers, Layer.isCollapsed and Layer.isExpanded control whether child layers are visible in the timeline. These are also local properties.

local visible = layer.isVisible
layer.isVisible = visible

-- Example of local visibility vs hierarchy visibility
local sprite = app.sprite
local layerGroup = sprite:newGroup()
local layers = sprite.layers
local layer1 = layers[1]
layer1.parent = layerGroup
layerGroup.isVisible = false
layer1.isVisible = true
print(layer1.isVisible) -- Returns true

The Version object allows you to represent version numbers and perform comparisons. This is useful for checking if the current app.version meets a minimum requirement before executing specific logic.

You can compare Version objects directly using standard comparison operators like >=.

if app.version >= Version("1.2.10-beta4") then
  -- Execute code compatible with this version or newer
end

The app.editor object provides access to the currently active sprite editor in Aseprite. You can use it to retrieve the current sprite, mouse positions, zoom levels, and scroll offsets.

local editor = app.editor

When an API function accepts a 'size' argument, you can provide the dimensions in several different formats:

1. Direct arguments: Pass width and height as two separate parameters.
2. Object/Table: Pass a table with width and height keys.
3. Array/List: Pass a table containing exactly two numeric elements.
4. Size instance: Pass a pre-constructed Size object.

-- 1. Direct arguments
sprite:resize(64, 32)

-- 2. Object with width and height
sprite:resize{ width=64, height=32 }

-- 3. Array with two elements
sprite:resize{ 64, 32 }

-- 4. Size instance
sprite:resize(Size(64, 32))

The app.site object acts as a snapshot of the editor's active state at a specific moment in time. It captures which sprite, layer, frame, cel, image, and modes were active when the object was accessed.

Important Behavior: The site object is a static snapshot. If the active sprite or any other editor state changes after you have captured the site object, the site object will not be updated to reflect those changes. To get the current state of the editor, you must access app.site again.

-- Captures the state at this exact moment
local site = app.site

-- Even if the user clicks a different layer now,
-- 'site' still points to the layer that was active above.

Aseprite uses two ways to handle colors. While the Color object is a high-level, user-friendly abstraction, performance-critical operations (like using Image:getPixel(), Image:putPixel(), or Image:pixels()) use low-level unsigned integers. The format of these integers depends on the image's color mode:

• RGB images: A 32-bit unsigned integer (8 bits each for Red, Green, Blue, and Alpha).
• Grayscale images: A 16-bit unsigned integer (8 bits for Alpha and 8 bits for Grayscale value).
• Indexed images: An 8-bit unsigned integer (0-255) representing a palette entry index.