Feedback

press ENTER to search or ESC to cancel

Table of content

Globals namespaces

Constants

Classes/objects

API Changes

We will try minimize API changes between versions and keep backward compatibility, but if a function in the API was introduced with a bug, it's probable that its behavior will change in the next Aseprite release.

Deprecated should be avoided because might be removed in future versions of Aseprite.

Detect available API

You can use app.apiVersion:

if app.apiVersion == nil then
  -- First scripting API available
  app.alert("This is Aseprite v1.2.10-beta1 or v1.2.10-beta2")
elseif app.apiVersion == 1 then
  -- Second revision of the scripting API
  app.alert("This is Aseprite v1.2.10-beta3")
else
  -- Future versions will be 2, 3, etc.
end

v1.3.16-beta1

app.apiVersion is 36
Added ui parameter to all commands for enabling/disabling user interaction through their dialogs #3025

v1.3.15.3

app.apiVersion is 36
Enclose key names for plugin preferences with ["..."] when it's required #5412

v1.3.15

app.apiVersion is 35
Added sprite.undoHistory #5205
Added resizeable property to Dialog constructor #5177
Added onchecked parameter to Plugin:newCommand() #5198
Added missing FlipType.DIAGONAL #5359
Added app.tip #5316 #5348
Added autofit and sizeHint properties to Dialog #5176
Refresh timeline when changing layer collapsed status #5366
Process mnemonics consistently for plugins #5250
Escape characters in the console that we can't show properly #5324

v1.3.14.3

app.apiVersion is 34
Added events to listen to blendMode, name, opacity and visibility Sprite layer changes #5164

v1.3.14

app.apiVersion is 33
Added Dialog:separator() more in line with other widgets #4989 (thanks to @MapleGecko)
Added uuid field to layers #5033
Added os.rename() and os.remove() functions
Added fitCriteria parameter to app.command.ChangePixelFormat command #4781
Fixed cel.image:clear() cannot be undone #5015
Fixed regression overwriting path specified in Dialog:file{filename} #5061

v1.3.13

app.apiVersion is 32
New app.clipboard API #2073
New beforesitechange event #4785
New plugin.version and plugin.displayName properties #4904
Don't allow to set invalid pixel ratios for sprites #3285
Fixed Image:drawImage() when BlendMode.SRC is used #5001

v1.3.11

app.apiVersion is 31
Fixed cel.image = nil statement #4514
Added ui param to app.command.MaskByColor #2774

v1.3.11-beta1

app.apiVersion is 30
Added GraphicsContext for images: Image.context property #4330
Added ui/flatten/filename parameters to app.command.DuplicateSprite command #4755

v1.3.10

app.apiVersion is 30
Added app.editor.zoom/scroll properties #4722
New option (Dialog:show{ hand=true }) to enable Hand tool in the active editor with a modal dialog (thanks to @lampysprites)

v1.3.9.2

app.apiVersion is 29
New fgTile/bgTile properties to get/set the foreground/background tile #4403
Added Site.tilemapMode property
Added x and y params to app.command.Paste()
Fixed app.command.Cut/Paste in -batch mode #4354
Fixed app.command.Cancel() command when used from scripts
Fixed default color/bgColor params in app.useTool()

v1.3.7

app.apiVersion is 28
New app.os with some properties about the running platform
New recent parameter to SaveFile and ExportSpriteSheet commands

v1.3.3

app.apiVersion is 27
Fixed some bugs using tabs widget #4288, #4268

v1.3-rc7

app.apiVersion is 26
New Dialog:tab()/endtabs() widget
New Dialog:show{ autoscrollbars=true } parameter
New app.editor:askPoint{ decorate={ rulers=true, dimmed=true } } options
New Align enum
New Image.bytesPerPixel property

v1.3-rc5

app.apiVersion is 25
Removed App.events 'beforepaintemptytilemap'
New app.window object.
New integrated json.decode() and json.encode() functions.

v1.3-rc4

app.apiVersion is 24
New Image:flip() function and FlipType
New App.events: 'beforecommand', 'aftercommand', 'beforepaintemptytilemap'

v1.3-rc3

app.apiVersion is 23
New require() function
New app.editor and Editor object
New plugin.name and plugin.path properties
New Cel.zIndex property
New Uuid class
New image:clear(bounds, color) variant (we can specify a Rectangle to clear)
New short property names for active objects: app.sprite (same as app.activeSprite), app.layer/frame/cel/tag/tool/brush
New width/height short names for Rectangle.w/h and Size.w/h
New gridBounds parameter to app.command.NewLayer

v1.3-rc2

app.apiVersion is 22
New app.uiScale property
New app.theme:styleMetrics() function
New plugin:newMenuGroup() and plugin:newMenuSeparator() functions
New Size:union() function
New GraphicsContext.opacity/blendMode properties
New GraphicsContext:oval() function
Renamed KeyEvent:repeat to KeyEvent:repeatCount
New ondblclick event for Dialog:canvas() widget

v1.3-rc1

app.apiVersion is 21
New ev argument for Sprite.events:on('change', ...) callback to detect if the change is from an undo/redo change (related to #3539)
New AniDir.PING_PONG_REVERSE field
New Tag.repeats field
New Sprite.isModified property
New Image.bounds property and Image:shrinkBounds() function
New app.theme class
New Dialog:canvas() widget
New GraphicsContext class
New Rectangle.origin and Rectangle.size properties
New Tile and new Sprite:newTile()
New Timer class
New properties field for several objects

v1.2.40 & v1.3-beta21

app.apiVersion is 20
Added app.range.slices object
Only in v1.3-beta21:
- Added bounds parameter to app.command.SaveFileCopyAs command
- Added splitGrid & fromTilesets parameters to app.command.ExportSpriteSheet command

v1.2.36

app.apiVersion is 19
Fixed several issues with app.command.SaveFile/SaveFileAs/SaveFileCopyAs commands
Fixed Sprite:newSlice, now it adds undo information

v1.2.35

app.apiVersion is 18
Now Dialog() returns nil if we are running in -batch mode
New Cel.frame/Cel.frameNumber setters
Comparing Layers with Sprites just return false #3218

v1.2.33

app.apiVersion is 17
New Color{ index }
Now Color.index returns an integer instead of a number

v1.2.31

app.apiVersion is 16
New filenamechange event for Sprite.events
Possibility to change options field for Dialog:combobox() from Dialog:modify()

v1.2.30

app.apiVersion is 15
New onenabled attribute for plugin:newCommand()
New App.events and Sprite.events properties, and Events class
New Image.bytes and Image.rowStride properties
New WebSocket class and WebSocketMessageType constants
New Layer.isReference property

v1.2.28

app.apiVersion is 14
Added selection argument to app.useTool{} to use selection tools
New SelectionMode
In v1.3-beta1
- New Layer.isTilemap
- New Tileset

v1.2.26

app.apiVersion is 13
New app.fs.makeDirectory/app.fs.makeAllDirectories/app.fs.removeDirectory functions to manipulate directories
Added Sprite.pixelRatio property
Added app.command.ImportSpriteSheet.

v1.2.22

app.apiVersion is 12
New app.command.CanvasSize() params (ui and bounds)
Fixed crash undoing Sprite:newCel() in background layer
Fixed Dialog onclose event, now it's called when we close the app and the dialog is still opened #28
API changes:
- You must use Dialog:newrow{ always=true } to activate the automatic "newrow" (Dialog:newrow{ always } cannot be used)
- You must use ColorSpace{ sRGB=true } to create an sRGB color space (ColorSpace{ sRGB } cannot be used)
- Now app.command.SetInkType{ type=... } works

v1.2.19

app.apiVersion is 11
Added support to modify more properties with Dialog:modify{} (PR#2359, separator text #27)
Added some extra onchange and onrelease events for some widgets like Dialog:slider{} (PR#2359)
Added more arguments (bgColor, ink, button, opacity, contiguous, tolerance, freehandAlgorithm) to app.useTool{}
New Ink constants

v1.2.18

app.apiVersion is 10
New Tag.color property
New MouseButton which enumerates possible values for the new ev.button value of the Dialog:shades{ onclick } widget callback
New Dialog:modify{} method to change widget properties dynamically
New Dialog:newrow{ always=true } variant
New Range:clear() function
New Range.layers and Range.frames setters

v1.2.17

app.apiVersion is 9
New app.fs with several functions to handle filenames and paths
New Dialog{ onclose } constructor with a table with fields like title and onclose
New Dialog:shades{} widget
New Image:saveAs{ filename, palette } function

v1.2.16.3

app.apiVersion is 8
Fixed Layer.stackIndex setter when the number we use is higher than the current stackIndex of the layer
Now app.preferences.document(nil) returns the default preferences for documents

v1.2.16

app.apiVersion is 7
Added Sprite.gridBounds property

v1.2.15

app.apiVersion is 6
Fixed Sprite:resize(): Now it can resize the non-active sprite.
Fixed Sprite:newTag(): Adds undo information (can be used inside a transaction now).

v1.2.14

app.apiVersion is 5
Added filter commands:
New types:
- FilterChannels
Added support to convert arrays of 2 or 4 integers into points, sizes, and rectangles.
Added Range.colors and Range.containsColor members. And new commands CopyColors/MoveColors.
Added Image:resize() function.
Changed Sprite:resize() behavior: resizes the sprite and images (not only the canvas).
Sprite.layers returns only the first level of layers (in previous versions it returned all the layers, even sublayers inside groups).
New Layer.layers property to get the layer groups
Possibility to change Layer.parent property
New Layer.stackIndex property to reorder layers

v1.2.13

app.apiVersion is 4
app.useTool() now can be used inside a app.transaction() (#18)
New params for app.command.NewFile.

v1.2.10

app.apiVersion is 3
app.version is an Version object
Sprite
- Added sprite:close() function
- Added sprite:assignColorSpace() and sprite:convertColorSpace()
- Now sprite:saveAs() changes the state of the sprite as a saved document
- Now you can set sprite.filename property
New ColorSpace class.
New focus property for Dialog:button and Dialog:entry.
New parameters for ExportSpriteSheet.
New app.useTool(), Brush, Tool class.

v1.2.10-beta4

app.apiVersion is 2
Fixed app.sprites table
Added app.params table

v1.2.10-beta3

app
- New app.apiVersion with value 1.
- Different return value for app.activeFrame: Now it returns a Frame instead of a frame number (an integer value). In v1.2.10-beta2 this function returned nil when we were in the first frame, now it returns the valid Frame object with frame.frameNumber = 1. You can access the old frame number value doing:
```
local activeFrameNumber = app.activeFrame.frameNumber
```
- New app.range
Site
- Different return value for app.site.frame: Now it returns a Frame instead of a frame number.
Rectangle
- Added Rectangle.contains function.
- Added Rectangle.intersect function.
- Added Rectangle.intersects function.
- Added Rectangle.union function.
Sprite
- Added Sprite.bounds property.
- Different Sprite:newFrame and Sprite:newEmptyFrame behavior (check documentation and issue #4).
Image
- Added Image:clear() function.
- Added Image:isEqual, Image:clear.
- Added Image:drawPixel as an alias for Image:putPixel (both functions will be available).
- Deprecated ~~Image:putImage~~, replaced with Image:drawImage.
- Deprecated ~~Image:putSprite~~, replaced with Image:drawSprite. Also Image:putSprite wasn't working correctly for positions != 0,0.
ColorMode:
- Deprecated ~~ColorMode.GRAYSCALE~~, replaced with ColorMode.GRAY.
Tag:
- Different return value for Tag.fromFrame and Tag.toFrame: now they return a Frame object instead of an integer value.
All functions that receive an integer can automatically accept floating numbers doing an implicit math.floor(number) conversion.

v1.2.10-beta2

app
- app.apiVersion didn't exist (is nil)