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 know 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

Gets or sets 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 versions to know what each API version offers.

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.fgTile

Gets or sets the current foreground tile.

app.bgTile

Gets or sets the current background tile.

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.clipboard

Check the app.clipboard documentation.

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.os

Check the app.os documentation.

app.uiScale

local scale = app.uiScale

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

app.defaultPalette

Returns the user's default palette, as a Palette.

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 another sprite, layer, or frame.
'beforesitechange': Before the user switches to another 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 converts 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)

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.tip()

app.tip "Text"
app.tip("Text")
app.tip("Text", 3.5)
app.tip { text="Text", duration=5 }

Shows a tooltip message in the status bar. If the duration (in seconds) is not specified, it will default to 2. The duration can be between 0.5 to 30 seconds.

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. If a string is given as first argument, that string will be used as the label of this undo/redo action (which can be seen in the Edit > Undo History window).

The given function is called inside the transaction. If the function fails, the whole transaction is undone (i.e. all the steps executed so far will be reversed). If the function succeeds, the transaction is committed and then all actions will be grouped in just one undo/redo operation.

You can cancel/reverse/cause an explicit failure of the transaction calling the error() Lua function, e.g:

app.transaction(
  function()
    ...
    if something_is_wrong then
      error() -- this stops the function and doesn't continue with the
              -- following lines / the actions so far will be reversed
              -- automatically leaving the sprite intact
    end
    ...
  end)

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 | Tool,
  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=boolean,
  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 a user stroke on the canvas using the given tool.

tool: The tool to use. Can either be a Tool object or a string 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). Defaults to app.tool.
color: The color to draw with (foreground color), as a Color object. Defaults to app.fgColor.
bgColor: The background color to draw with, as a Color object. Defaults to app.bgColor.
brush: A Brush object for the tool to draw with. Defaults to the active brush.
points: An array of points on the sprite canvas which simulate the positions where a user would put their 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.
The draw location (cel or layer/frame) can be specified:
- cel: The specific Cel where we want to use the tool/draw with the tool (by default app.cel).
- layer: The Layer to use the tool at (by default app.layer).
- frame: The Frame to use the tool at (by default app.frame).
ink: The Ink type for the tool to use.
button: The MouseButton to use, can either be MouseButton.LEFT or MouseButton.RIGHT. Defaults to MouseButton.LEFT.
opacity: The opacity of the tool stroke, as an integer between 0 and 255. Defaults to 255.
tolerance: The tolerance of the tool fill, as an integer between 0 and 255. Defaults to 0.
contiguous: Contiguous mode toggle. Defaults to true.
freehandAlgorithm: Changes the freehand algorithm. Can either be 0 (regular mode) or 1 (pixel-perfect mode). Defaults to 0.
tilemapMode: The TilemapMode of the tool. Defaults to TilemapMode.PIXELS.
tilesetMode: The TilesetMode of the tool. Defaults to TilesetMode.MANUAL.

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.

FilesExpand file tree

app.md

Latest commit

History