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.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 app.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:
  • app.command.BrightnessContrast()
  • app.command.ColorCurve()
  • app.command.ConvolutionMatrix()
  • app.command.Despeckle()
  • app.command.HueSaturation()
  • app.command.InvertColor()
  • app.command.Outline()
  • app.command.ReplaceColor()
• 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)