Skip to content
Permalink
master
Switch branches/tags
Go to file
2 contributors

Users who have contributed to this file

@dacap @Gasparoken

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

Gets or sets the active Cel object.

app.activeFrame

Gets or sets the active frame number (1 is the first frame in the sprite).

WARNING: This function has a bug in Aseprite v1.2.10-beta2, returns nil if we are in the first frame of the sprite. Also it returns a number, but in the future it will returns a frame object, you can use an auxiliary function at the moment:

local function activeFrameNumber()
  local f = app.activeFrame
  if f == nil then
    return 1
  else
    return f
  end
end

app.activeImage

local image = app.activeImage

Returns the active image, an Image object.

app.activeLayer

Returns the active layer, a Layer object.

app.activeSprite

local sprite = app.activeSprite

Returns the active sprite, a Sprite object.

app.activeTag

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

app.activeTool

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

app.activeBrush

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

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.

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)

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.

app.command

Check the app.command documentation.

app.preferences

Check the app.preferences documentation.

app.fs

Check the app.fs documentation.

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 activeSprite. It's like calling app.command.Undo() (the Edit > Undo menu option).

app.redo()

app.redo()

Redoes the latest undone operation in the activeSprite. 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
}

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.
  • And we can specify the cel or layer/frame where to draw: