Feedback
  • press ENTER to search or ESC to cancel

Table of content

Overview
API Changes

Globals namespaces

Constants

Classes/objects

Edit page

app

The app global namespace.

app.site

Active site (active image, layer, frame, sprite, etc.).

app.range

Range member represents the active selection from an objects collection. It returns a sorted list of selected frames, or cels, or layers, or colors, etc.

app.cel

Gets or sets the active Cel object.

app.frame 

local frame = app.frame
assert(frame.sprite == app.sprite)
app.frame = app.sprite.frames[2] -- go to the second frame

app.frame = 3 -- you can assign a frame number directly
app.frame = 1 -- 1 is the first frame of the sprite

Returns a Frame object that represents the active frame in the focused sprite editor. You can set this property assigning a frame number directly to jump to another frame.

To known the active frame number use app.frame.frameNumber

app.image 

local image = app.image

Returns the active image, an Image object.

app.layer

Returns the active layer, a Layer object.

app.sprite 

local sprite = app.sprite

Returns the active sprite, a Sprite object.

app.tag

Returns the active tag, which is the tag located at the active frame.

app.tool

Returns the active tool (a Tool object) selected in the tool bar.

app.brush

Returns the active brush (a Brush object) selected in the context bar.

app.editor

Returns the active editor (a Editor object).

app.window

Returns the main window (a Window object).

app.pixelColor

This pixelColor namespace contains internal functions to handle color at the lowest level.

app.version

Returns the Aseprite version number as a Version object (e.g. Version("1.2.10-beta1")).

app.apiVersion

Returns the API version. See the changes file between version to know what offer each API version.

app.fgColor

Gets or sets the current foreground color.

app.bgColor

Gets or sets the current background color. Remember that some commands use the background color to clear the active layer.

app.isUIAvailable

Returns true if the UI is available. E.g. if this is true you can use app.alert or dialogs. The UI is not available when we run in --batch mode.

app.sprites 

for i,sprite in ipairs(app.sprites) do
  -- do something with each sprite...
end

Returns an array of sprites.

app.params

This is a table with parameters specified as --script-param key=value in the CLI or as <param> in user.aseprite-keys or gui.xml file.

app.alert() 

app.alert "Text"
app.alert("Text")
app.alert{title="Title", text="Text", buttons="OK"}
app.alert{title="Title", text="Text", buttons={"OK", "Cancel"}}
app.alert{title="Title", text={"Line 1", "Line 2", ...}, buttons={"Yes", "No", "Cancel", ...}}

Shows an alert message. If buttons are not specified, it will show a message box with the OK button only.

Returns an integer with the selected button i.e. 1 if the first button was clicked, 2 if the second one, etc. Example:

local result = app.alert{ title="Warning",
                          text="Save Changes?",
                          buttons={"Yes", "No"}}
if result == 1 then
  app.alert "Yes was pressed"
end

app.open() 

app.open(filename)

Opens a new sprite loading it from the given filename. Returns an instance of the Sprite class or nil if something went wrong.

app.exit() 

app.exit()

Closes the application. It's like clicking File > Exit menu option.

app.transaction() 

app.transaction(
  function()
    ...
  end)

app.transaction(
  string,
  function()
    ...
  end)

Creates a new transaction so you can group several sprite modifications in just one undo/redo operation.

The function in the argument is called inside the transaction, if the function fails, the whole transaction is undone. If the function successes, the transaction is committed and then all actions will be grouped in just one undo/redo operation.

If a string is given as first argument, that string will be used as a label for the undo/redo action.

app.command

Check the app.command documentation.

app.preferences

Check the app.preferences documentation.

app.fs

Check the app.fs documentation.

app.theme

Check the app.theme documentation.

app.uiScale 

local scale = app.uiScale

Returns the UI Elements Scaling value specified in Edit > Preferences as an scale factor (1 for 100%, 2 for 200%, etc.)

app.refresh() 

app.refresh()

This function is available just in case you see that your script updates the sprite but the screen is not showing the updated state of the sprite. It should not be needed, but it's here just in case that something is not working right on the Aseprite side.

app.undo() 

app.undo()

Undoes the latest operation in the active sprite. It's like calling app.command.Undo() (the Edit > Undo menu option).

app.redo() 

app.redo()

Redoes the latest undone operation in the active sprite. It's like calling app.command.Redo() (the Edit > Redo menu option).

app.useTool() 

app.useTool{
 tool=string,
 color=Color,
 bgColor=Color,
 brush=Brush,
 points={ Point, Point, .... },
 cel=Cel,
 layer=Layer,
 frame=Frame,
 ink=Ink,
 button=MouseButton.LEFT | MouseButton.RIGHT,
 opacity=integer,
 contiguous=false | true,
 tolerance=integer,
 freehandAlgorithm=0 | 1,
 selection=SelectionMode.REPLACE | SelectionMode.ADD | SelectionMode.SUBTRACT | SelectionMode.INTERSECT,
 tilemapMode=TilemapMode.PIXELS | TilemapMode.TILES,
 tilesetMode=TilesetMode.MANUAL | TilesetMode.AUTO | TilesetMode.STACK,
}

Simulates an user stroke in the canvas using the given tool.

  • tool: A string with a well known tool ID (rectangular_marquee, elliptical_marquee, lasso, polygonal_lasso, magic_wand, pencil, spray, eraser, eyedropper, zoom, hand, move, slice, paint_bucket, gradient, line, curve, rectangle, filled_rectangle, ellipse, filled_ellipse, contour, polygon, blur, jumble) or a tool object
  • color: A color object to draw with the given tool
  • brush: A brush object to draw the points
  • points: An array of points in the sprite canvas which simulate the position of where the user put the mouse to draw with the given tool.
  • selection: What to do with the selection, only for selection-like tools (rectangular_marquee, magic_wand, etc.). The default value when the UI is enabled will be app.preferences.selection.mode, in CLI mode it's SelectionMode.REPLACE.
  • And we can specify the cel or layer/frame where to draw:
    • cel: The specific cel where we want to use the tool/draw with the tool (by default app.cel)
    • layer: The layer where we want to use the tool/draw with the tool (by default app.layer)
    • frame: The frame where to draw (by default app.frame)

app.events

Returns the Events object to associate functions that can act like listeners of specific app events. E.g.

app.events:on('sitechange',
  function()
    print('Now we are located in other sprite, layer, or frame')
  end)

Available events for app:

  • 'sitechange': When the user selects other sprite, layer, or frame.
  • 'fgcolorchange': When the Foreground color in the color bar is changed.
  • 'bgcolorchange': When the Background color in the color bar is changed.
  • 'beforecommand': Before executing any command in the program.
  • 'aftercommand': After executing any command in the program.

The 'beforecommand' and 'aftercommand' events receive an ev argument with the name of the command (ev.name) and the params (ev.params). 'beforecommand' includes a ev.stopPropagation() function to cancel the event, e.g. in case that you've handled the event in a custom way.

E.g. This code catches the Edit > Cut command and convert it to a Copy:

app.events:on('beforecommand',
  function(ev)
    if ev.name == "Cut" then
      app.command.Copy()   -- call Copy command
      ev.stopPropagation() -- and cancel the Cut
    end
  end)

Deprecated Names

The following fields were replaced with new alternatives (generally shorter) names. These will not be removed from the API, so we can offer backward compatibility with old scripts.

app.activeSprite

Deprecated. Use app.sprite.

app.activeLayer

Deprecated. Use app.layer.

app.activeFrame

Deprecated. Use app.frame.

WARNING: This function had two bugs in Aseprite v1.2.10-beta2 where 1) it returned nil if we were in the first frame of the sprite, and 2) it returned a number. Since Aseprite v1.2.10-beta3 it started to return a Frame object.

app.activeCel

Deprecated. Use app.cel.

app.activeImage

Deprecated. Use app.image.

app.activeTag

Deprecated. Use app.tag.

app.activeTool

Deprecated. Use app.tool.

app.activeBrush

Deprecated. Use app.brush.