### Install Aseprite Extension

Source: https://github.com/aseprite/api/blob/main/api/command/Options.md

Prompts the user to install an Aseprite extension file by providing the file path.

```lua
app.command.Options {
  installExtension="" 
}
```

--------------------------------

### Get Application Path - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Retrieves the installation path of the Aseprite application.

```lua
app.fs.appPath
```

--------------------------------

### Initialize path

Source: https://github.com/aseprite/api/blob/main/api/graphicscontext.md

Starts a new path by clearing existing sub-paths.

```lua
gc:beginPath()
```

--------------------------------

### AddColor Usage Examples

Source: https://github.com/aseprite/api/blob/main/api/command/AddColor.md

Examples showing how to add a specific color object or the current foreground color to the palette.

```lua
app.command.AddColor {
  color=Color(255, 0, 0)
}

app.command.AddColor {
  source="fg"
}
```

--------------------------------

### WebSocket Message Handling Example

Source: https://github.com/aseprite/api/blob/main/api/websocket.md

An example demonstrating how to handle different WebSocket message types (OPEN, TEXT, CLOSE) and send messages. Ensure the server URL is correct.

```lua
local function handleMessage(mt, data)
  if mt == WebSocketMessageType.OPEN then
    print("Connection open. Sending a message...")
    ws:sendText("Hello!")

  elseif mt == WebSocketMessageType.TEXT then
    print("Message recived: " .. data)
    ws:close()

  elseif mt == WebSocketMessageType.CLOSE then
    print("Connection closed")
  end
end

local ws = WebSocket{
    onreceive = handleMessage,
    url = "http://127.0.0.1:9000",
    deflate = false
}
```

--------------------------------

### app.command.Options()

Source: https://github.com/aseprite/api/blob/main/api/command/Options.md

Opens the Aseprite preferences dialog or prompts to install an extension.

```APIDOC
## app.command.Options()

### Description
Opens the Aseprite preferences dialog. This command can also be used to prompt the user to install an Aseprite extension file.

### Method
Command

### Endpoint
app.command.Options

### Parameters
#### Query Parameters
- **installExtension** (string) - Optional - The path to the `*.aseprite-extension` file to be installed.

### Request Example
```lua
app.command.Options {
  installExtension="path/to/your/extension.aseprite-extension"
}
```

### Response
This command does not return a value, but it may open a dialog or initiate an installation process.
```

--------------------------------

### Create and Start a Repeating Timer

Source: https://github.com/aseprite/api/blob/main/api/timer.md

Use this to create a timer that executes a function repeatedly at a specified interval. Ensure the timer is started after creation.

```lua
local timer = Timer{
  interval=5.0,
  ontick=function()
    print('Each 5 seconds')
  end }
timer:start()
```

--------------------------------

### Timer:start()

Source: https://github.com/aseprite/api/blob/main/api/timer.md

Starts the timer, causing the `ontick` function to be called after the specified interval.

```APIDOC
## Timer:start()

### Description
Starts the timer.

### Method
Timer:start()

### Endpoint
N/A (Method call on a Timer object)

### Parameters
None

### Request Example
```lua
timer:start()
```

### Response
#### Success Response (200)
No specific response body, operation is performed.

#### Response Example
N/A
```

--------------------------------

### Get Main Window Width

Source: https://github.com/aseprite/api/blob/main/api/window.md

Retrieves the current width of the Aseprite main window. No setup is required.

```lua
local width = app.window.width
```

--------------------------------

### Apply ColorCurve Example

Source: https://github.com/aseprite/api/blob/main/api/command/ColorCurve.md

A practical example of applying a red channel color curve that maps input 0 to 0 and 255 to 128.

```lua
app.command.ColorCurve {
  ui=true,
  channels=FilterChannels.RED,
  curve={ { 0, 0 }, { 255, 128 } }
}
```

--------------------------------

### Command Parameter Usage

Source: https://github.com/aseprite/api/blob/main/api/app_command.md

Instructions on how to find and use parameters for Aseprite commands, including examples for Lua scripting.

```APIDOC
## Command Parameter Usage

### Finding Command Parameters

If you cannot find a specific command's documentation, you can refer to the `gui.xml` file for definitions of menus and commands, including their parameters.

1.  Choose a command (e.g., `CommandName` in `app.command.CommandName`) from the `gui.xml` file (look for `<key command="CommandName" ...>` or `<item command="CommandName" ...>`).
2.  If the XML elements contain child elements like `<param name="param-name1" value="param-value2" />`, you can specify these parameters in Lua.

### Specifying Parameters in Lua

Parameters can be specified in Lua using a table format.

```lua
app.command.CommandName { ["param-name1"]="param-value1", ["param-name2"]="param-value2" }
```

### Alternative Method: Aseprite Source Code

Another way to determine parameter names is by examining the Aseprite source code:

1.  Locate the corresponding `.cpp` file in `src/app/commands/` (e.g., `app.command.CropSprite` corresponds to `cmd_crop.cpp`).
2.  Find all instances where `params.get` is used within the file. The strings passed to `params.get` are the parameter names.
3.  When setting parameters in Lua, use the bracket notation if the parameter name contains hyphens, as Lua identifiers cannot contain hyphens.

```lua
app.command.CommandName { ["parameter-name"]="value", ["other-parameter-name"]="otherValue" }
```
```

--------------------------------

### Move path cursor

Source: https://github.com/aseprite/api/blob/main/api/graphicscontext.md

Sets the starting point for a new sub-path.

```lua
gc:moveTo(x, y)
```

--------------------------------

### Get OS Version

Source: https://github.com/aseprite/api/blob/main/api/app_os.md

Retrieves the version of the operating system.

```APIDOC
## app.os.version

### Description
Returns an [`Version`](version.md#version) with the Windows or macOS version. It's just `0.0.0` on Linux.

### Method
GET

### Endpoint
/app/os/version

### Response
#### Success Response (200)
- **version** (string) - The version of the operating system (e.g., "14.4.1" for macOS, "10.0.22631" for Windows, or "0.0.0" for Linux).

### Response Example
```json
{
  "version": "14.4.1"
}
```
```

--------------------------------

### Get or Set Frame Duration

Source: https://github.com/aseprite/api/blob/main/api/frame.md

Gets or sets the display duration of the current frame in seconds. For example, 0.3333 represents 1/3 of a second.

```lua
local duration = frame.duration
frame.duration = duration
```

--------------------------------

### SpriteSize Re-fetching Reference Example

Source: https://github.com/aseprite/api/blob/main/api/command/SpriteSize.md

Shows how to update a variable reference to a cel image after a resize operation.

```lua
local s = Sprite(1, 1)
local cel = app.cel
local i = cel.image

app.command.SpriteSize{ ui = false, scaleX = 2 }
i = cel.image  -- We have to get the image again
print(i.width) -- it will print "2"
```

--------------------------------

### Get Frame Sprite

Source: https://github.com/aseprite/api/blob/main/api/frame.md

Retrieves the sprite object associated with the current frame. No setup is required.

```lua
local sprite = frame.sprite
```

--------------------------------

### app.command.About

Source: https://github.com/aseprite/api/blob/main/api/app_command.md

Opens the About Aseprite window. Requires UI.

```APIDOC
## app.command.About

### Description
Opens the About Aseprite window.

### Method
POST

### Endpoint
`/aseprite/api/app/command`

### Parameters
#### Path Parameters
- **CommandName** (string) - Required - `About`

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "command": "app.command.About"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the command executed successfully.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Get Main Window Height

Source: https://github.com/aseprite/api/blob/main/api/window.md

Retrieves the current height of the Aseprite main window. No setup is required.

```lua
local height = app.window.height
```

--------------------------------

### Implement Plugin Lifecycle

Source: https://github.com/aseprite/api/blob/main/api/plugin.md

Use init and exit functions to manage plugin state and command registration.

```lua
function init(plugin)
  print("Aseprite is initializing my plugin")

  -- we can use "plugin.preferences" as a table with fields for
  -- our plugin (these fields are saved between sessions)
  if plugin.preferences.count == nil then
    plugin.preferences.count = 0
  end

  --
  plugin:newCommand{
    id="MyFirstCommand",
    title="My First Command",
    group="cel_popup_properties",
    onclick=function()
      plugin.preferences.count = plugin.preferences.count+1
    end
  }
end

function exit(plugin)
  print("Aseprite is closing my plugin, MyFirstCommand was called "
        .. plugin.preferences.count .. " times")
end
```

--------------------------------

### Extract File Title - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Gets the file name without the path and extension. For example, 'file' from 'path/file.png'.

```lua
local title = app.fs.fileTitle(fn)
```

```lua
print(app.fs.fileTitle("path/file.png"))
```

--------------------------------

### app.command.Launch

Source: https://github.com/aseprite/api/blob/main/api/app_command.md

Opens a given path in the desktop web browser.

```APIDOC
## app.command.Launch

### Description
Opens the given `path` in the desktop web browser as relative path to aseprite.org or a full URL.

### Parameters
#### Request Body
- **path** (string) - Required - The URL or relative path to open.
```

--------------------------------

### Extract File Extension - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Gets the file extension without the leading dot. For example, 'png' from 'path/file.png'.

```lua
local extension = app.fs.fileExtension(fn)
```

```lua
print(app.fs.fileExtension("path/file.png"))
```

--------------------------------

### Create Aseprite Plugins

Source: https://context7.com/aseprite/api/llms.txt

Define plugin initialization and exit functions, add custom menu commands, and manage user preferences. Commands can be enabled/disabled based on application state.

```lua
-- In your plugin's main script file (init/exit functions)
function init(plugin)
  print("Plugin initialized: " .. plugin.name)

  -- Initialize preferences with defaults
  if plugin.preferences.lastUsedSize == nil then
    plugin.preferences.lastUsedSize = 64
  end

  -- Add a new command to Aseprite menus
  plugin:newCommand{
    id="MyPluginCommand",
    title="My Plugin Action",
    group="sprite_properties",

    onenabled=function()
      return app.sprite ~= nil  -- Enable only when sprite exists
    end,

    onclick=function()
      local sprite = app.sprite
      local size = plugin.preferences.lastUsedSize

      local dlg = Dialog("My Plugin")
      dlg:number{ id="size", label="Size:", text=tostring(size) }
      dlg:button{ id="ok", text="Apply" }
      dlg:show()

      if dlg.data.ok then
        plugin.preferences.lastUsedSize = dlg.data.size
        -- Do something with the sprite
        app.alert("Applied size: " .. dlg.data.size)
      end
    end
  }

  -- Create a menu group for multiple commands
  plugin:newMenuGroup{
    id="my_plugin_group",
    title="My Plugin",
    group="sprite_properties"
  }

  plugin:newCommand{
    id="SubCommand1",
    title="Sub Command 1",
    group="my_plugin_group",
    onclick=function() app.alert("Sub command 1") end
  }

  plugin:newMenuSeparator{ group="my_plugin_group" }

  plugin:newCommand{
    id="SubCommand2",
    title="Sub Command 2",
    group="my_plugin_group",
    onclick=function() app.alert("Sub command 2") end
  }
end

function exit(plugin)
  print("Plugin exiting")
  -- Preferences are automatically saved
end

```

--------------------------------

### Accessing Point X Coordinate

Source: https://github.com/aseprite/api/blob/main/api/point.md

Shows how to get or set the x property of a Point instance.

```lua
local x = point.x
point.x = newX
```

--------------------------------

### Create and Show a Basic Dialog

Source: https://github.com/aseprite/api/blob/main/api/dialog.md

Demonstrates creating a dialog with an entry field and two buttons, then displaying it and processing user input.

```lua
local dlg = Dialog()
dlg:entry{ id="user_value", label="User Value:", text="Default User" }
dlg:button{ id="confirm", text="Confirm" }
dlg:button{ id="cancel", text="Cancel" }
dlg:show()
local data = dlg.data
if data.confirm then
  app.alert("The given value is '" .. data.user_value .. "'")
end
```

--------------------------------

### Extract Path and Title - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Gets the file path joined with the file title (name without extension). For example, 'path/file' from 'path/file.png'.

```lua
local title = app.fs.filePathAndTitle(fn)
```

```lua
print(app.fs.filePathAndTitle("path/file.png"))
```

--------------------------------

### Create a new Selection

Source: https://github.com/aseprite/api/blob/main/api/selection.md

Creates a new empty selection or initializes it with a given rectangle. Use this to start managing a selection.

```lua
Selection()
Selection(rectangle)
```

--------------------------------

### Get Frame Number

Source: https://github.com/aseprite/api/blob/main/api/frame.md

Retrieves the numerical index of the current frame within the sprite's animation sequence. Frame numbers start at 1.

```lua
local frameNumber = frame.frameNumber
```

--------------------------------

### app.command.FullscreenPreview

Source: https://github.com/aseprite/api/blob/main/api/app_command.md

Opens the full-screen preview. Requires UI.

```APIDOC
## app.command.FullscreenPreview

### Description
Opens the full screen preview.

### Method
POST

### Endpoint
`/aseprite/api/app/command`

### Parameters
#### Path Parameters
- **CommandName** (string) - Required - `FullscreenPreview`

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "command": "app.command.FullscreenPreview"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the command executed successfully.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Get or set Sprite pixel ratio

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Gets or sets the pixel ratio of the sprite as a size object.

```lua
local size = sprite.pixelRatio
sprite.pixelRatio = size
```

--------------------------------

### Create All Directories - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Creates all necessary parent directories to access the specified path. Returns true if successful.

```lua
local result = app.fs.makeAllDirectories(path)
```

--------------------------------

### Rectangle Contains Example

Source: https://github.com/aseprite/api/blob/main/api/rectangle.md

An example demonstrating the usage of the `contains` method to check if one rectangle is inside another.

```lua
local bounds = Rectangle{ x=0, y=0, width=32, height=32 }
local rectInside = Rectangle{ x=4, y=4, width=8, height=8 }
if bounds:contains(rectInside) then ... end
```

--------------------------------

### Create Uuid Instances

Source: https://github.com/aseprite/api/blob/main/api/uuid.md

Shows how to initialize a new random Uuid or create one from a specific 36-character string.

```lua
local u = Uuid()
local v = Uuid("74341b56-4f7f-4ab1-9495-58cf5bce0e1c") -- e.g.
```

--------------------------------

### Example ColorQuantization Usage

Source: https://github.com/aseprite/api/blob/main/api/command/ColorQuantization.md

Demonstrates how to call the ColorQuantization command with specific parameters to create a palette with alpha disabled and a maximum of 100 colors using the octree algorithm.

```lua
app.command.ColorQuantization {
  ui=true,
  withAlpha=false,
  maxColors=100,
  algorithm="octree"
}
```

--------------------------------

### Get User Configuration Path - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Retrieves the path to the current user's Aseprite configuration folder.

```lua
app.fs.userConfigPath
```

--------------------------------

### Size Object Creation

Source: https://github.com/aseprite/api/blob/main/api/size.md

Demonstrates the various ways to create a new Size instance.

```APIDOC
## Size()

### Description
Creates a new `Size` instance with the given dimensions (or `width=height=0` if they are not specified).

### Method
`Size()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```lua
-- Example usage of Size() constructor
local defaultSize = Size()
local sizeFromWidthHeight = Size(64, 32)
local sizeFromObject = Size{ width=64, height=32 }
local sizeFromObjectShort = Size{ w=64, h=32 }
local sizeFromArray = Size{ 64, 32 }
local sizeFromOther = Size(anotherSizeInstance)
```

### Response
#### Success Response (200)
- **Size** (object) - A new Size instance.

#### Response Example
```json
{
  "width": 64,
  "height": 32
}
```
```

--------------------------------

### Get or set Sprite filename

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Gets or sets the name of the file associated with the sprite. Returns an empty string for new, unsaved sprites.

```lua
local name = sprite.filename
sprite.filename = newName
```

--------------------------------

### Create and Access Images

Source: https://context7.com/aseprite/api/llms.txt

Initialize new images from various sources and access their properties.

```lua
-- Create a new standalone image
local img = Image(64, 64, ColorMode.RGB)

-- Create from sprite (renders first frame)
local img = Image(app.sprite)

-- Create a copy of another image
local copy = Image(app.image)

-- Create from a portion of an image
local portion = Image(app.image, Rectangle(10, 10, 32, 32))

-- Load from file
local img = Image{ fromFile="/path/to/image.png" }

-- Access image properties
print("Size: " .. img.width .. "x" .. img.height)
print("Color mode: " .. img.colorMode)
print("Bytes per pixel: " .. img.bytesPerPixel)
```

--------------------------------

### Create WebSocket Client

Source: https://github.com/aseprite/api/blob/main/api/websocket.md

Initializes a WebSocket client. Configure connection URL, message handling, compression, and reconnection attempts. The `onreceive` function is called for connection events and incoming messages.

```lua
local ws = WebSocket()
local ws = WebSocket{
    url = string,
    onreceive = function(message, data),
    deflate = bool,
    minreconnectwait=number,
    maxreconnectwait=number
}
```

--------------------------------

### Get or set Sprite color space

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Gets or sets the color space of the sprite. Setting this property is equivalent to using the Sprite:assignColorSpace() method.

```lua
local colorspace = sprite.colorSpace
sprite.colorSpace = colorspace
```

--------------------------------

### Get or set Sprite grid bounds

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Gets or sets the bounds of the sprite grid as a rectangle. The default is 16x16 with origin at 0,0, but this can be configured in Aseprite's preferences.

```lua
local rectangle = sprite.gridBounds
sprite.gridBounds = rectangle
```

--------------------------------

### Example of Scrolling Right by 50 Pixels

Source: https://github.com/aseprite/api/blob/main/api/command/Scroll.md

Demonstrates how to scroll the active editor view 50 pixels to the right using the Scroll command.

```lua
app.command.Scroll{
    quantity=50,
    units="pixel",
    direction="right"
}
```

--------------------------------

### Create Size Instance

Source: https://github.com/aseprite/api/blob/main/api/size.md

Demonstrates various ways to create a new Size instance. Default dimensions are 0,0 if not specified.

```lua
Size()
Size(otherSize)
Size(width, height)
Size{width=number, height=number}
Size{w=number, h=number}
Size{number, number}
```

--------------------------------

### Create a Dialog Using Method Chaining

Source: https://github.com/aseprite/api/blob/main/api/dialog.md

Shows how to create a dialog and add widgets using method chaining for more compact code. The dialog is displayed and its data is accessed.

```lua
local data =
  Dialog():entry{ id="user_value", label="User Value:", text="Default User" }
          :button{ id="confirm", text="Confirm" }
          :button{ id="cancel", text="Cancel" }
          :show().data
if data.confirm then
  app.alert("The given value is '" .. data.user_value .. "'")
end
```

--------------------------------

### Get or set Sprite selection

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Gets or sets the active sprite selection. This property is a reference to the Selection object. To clone the selection, create a new Selection and add the existing one to it.

```lua
local selection = sprite.selection
sprite.selection = newSelection
```

```lua
local selection = Selection()
selection:add(sprite.selection)
```

--------------------------------

### Get Layer UUID

Source: https://github.com/aseprite/api/blob/main/api/layer.md

Retrieve the unique identifier for the layer.

```lua
local uuid = layer.uuid
```

--------------------------------

### Open a file using app.command.OpenFile

Source: https://github.com/aseprite/api/blob/main/api/command/OpenFile.md

Use this command to programmatically open files. The ui parameter determines whether the file selection dialog is displayed.

```lua
app.command.OpenFile {
  ui=bool,
  filename=string,
  folder=string,
  repeat_checkbox=bool,
  oneframe=bool,
  sequence=string
}
```

--------------------------------

### app.command.DeveloperConsole

Source: https://github.com/aseprite/api/blob/main/api/app_command.md

Opens the developer console. Requires UI.

```APIDOC
## app.command.DeveloperConsole

### Description
Opens the developer console (experimental).

### Method
POST

### Endpoint
`/aseprite/api/app/command`

### Parameters
#### Path Parameters
- **CommandName** (string) - Required - `DeveloperConsole`

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "command": "app.command.DeveloperConsole"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the command executed successfully.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Get Color

Source: https://github.com/aseprite/api/blob/main/api/palette.md

Retrieves a specific color from the palette by its index.

```APIDOC
## Palette:getColor()

### Description
Returns the [`color`](color.md#color) in the given entry `index` (the `index` goes from `0` to `#palette-1`).

### Usage Example
```lua
local color = palette:getColor(index)
```
```

--------------------------------

### Initialize a Brush object

Source: https://github.com/aseprite/api/blob/main/api/brush.md

Create a new brush instance using default settings, a specific size, an image, or a table of configuration properties.

```lua
local brush = Brush()
local brush = Brush(size)
local brush = Brush(image)
local brush = Brush{
  type=BrushType,
  size=integer,
  angle=-180...180,
  center=Point
  image=Image
  pattern=BrushPattern
  patternOrigin=Point
}
```

--------------------------------

### Editor.scroll

Source: https://github.com/aseprite/api/blob/main/api/editor.md

Gets or sets the scroll position of the editor view.

```APIDOC
## Editor.scroll

### Description
Gets or sets the editor scroll (coordinates of sprite pixel to center the editor at) as a table, with values `x` and `y` as floats.

### Method
GET/SET

### Endpoint
app.editor.scroll

### Parameters
#### Request Body (for setting scroll)
- **scroll** (object) - A table with `x` and `y` properties representing the desired scroll position.
  - **x** (float) - The horizontal scroll position.
  - **y** (float) - The vertical scroll position.

### Response
#### Success Response (200)
- **scroll** (object) - A table with `x` and `y` properties representing the current scroll position.
```

--------------------------------

### Create Directory - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Creates a single directory. Returns true if successful.

```lua
app.fs.makeDirectory(path)
```

--------------------------------

### Editor.zoom

Source: https://github.com/aseprite/api/blob/main/api/editor.md

Gets or sets the current zoom level of the editor.

```APIDOC
## Editor.zoom

### Description
Gets or sets the editor zoom as a float. To get a percentage, multiply by 100.

### Method
GET/SET

### Endpoint
app.editor.zoom

### Parameters
#### Request Body (for setting zoom)
- **zoom** (float) - The desired zoom level (e.g., 0.333 for 33.3%).

### Response
#### Success Response (200)
- **zoom** (float) - The current zoom level of the editor.
```

--------------------------------

### Open Aseprite Preferences

Source: https://github.com/aseprite/api/blob/main/api/command/Options.md

Opens the Aseprite preferences dialog.

```lua
app.command.Options()
```

--------------------------------

### Editor.mousePos

Source: https://github.com/aseprite/api/blob/main/api/editor.md

Gets the mouse position relative to the screen coordinates.

```APIDOC
## Editor.mousePos

### Description
Returns a [point](point.md#point) indicating the mouse position on the screen.

### Method
GET

### Endpoint
app.editor.mousePos

### Response
#### Success Response (200)
- **point** (object) - A table with `x` and `y` properties representing the mouse coordinates on the screen.
```

--------------------------------

### GET app.sprites

Source: https://github.com/aseprite/api/blob/main/api/app.md

Retrieve an array of all currently open sprites.

```APIDOC
## GET app.sprites

### Description
Returns an array containing all open Sprite objects.

### Method
GET

### Endpoint
app.sprites

### Response
- **sprites** (Array) - A list of Sprite objects.
```

--------------------------------

### WebSocket Constructor

Source: https://github.com/aseprite/api/blob/main/api/websocket.md

Initializes a new WebSocket client instance with configuration options.

```APIDOC
## WebSocket()

### Description
Creates a new WebSocket client instance to communicate with a server.

### Parameters
- **url** (string) - Required - The server address to connect to.
- **onreceive** (function) - Optional - Callback function triggered on events (message type, data).
- **deflate** (boolean) - Optional - Enables compression for sent data.
- **minreconnectwait** (number) - Optional - Minimum wait time in seconds for reconnection.
- **maxreconnectwait** (number) - Optional - Maximum wait time in seconds for reconnection.
```

--------------------------------

### Check OS and Architecture

Source: https://github.com/aseprite/api/blob/main/api/app_os.md

Conditionally execute code based on the operating system and architecture. This example checks for Windows and macOS, including a specific check for Apple Silicon on macOS.

```lua
if app.os.windows then
  print("Running on Windows")
elseif app.os.macos then
  if app.os.arm64 then
    print("Running on Apple Silicon")
  end
end
```

--------------------------------

### Manage Cel Position

Source: https://github.com/aseprite/api/blob/main/api/cel.md

Gets or sets the position of the cel.

```lua
local position = cel.position
cel.position = newPosition
```

--------------------------------

### Aseprite File System Operations

Source: https://context7.com/aseprite/api/llms.txt

Perform path manipulation, check file existence, list directory contents, and create directories using the `app.fs` module.

```lua
-- Path manipulation
local fullPath = "/home/user/sprites/hero.aseprite"
print(app.fs.filePath(fullPath))       -- "/home/user/sprites"
print(app.fs.fileName(fullPath))       -- "hero.aseprite"
print(app.fs.fileTitle(fullPath))      -- "hero"
print(app.fs.fileExtension(fullPath))  -- "aseprite"

-- Join paths (platform-independent)
local newPath = app.fs.joinPath(app.fs.tempPath, "output", "file.png")

-- Check file existence
if app.fs.isFile(fullPath) then
  print("File size: " .. app.fs.fileSize(fullPath))
end

-- List directory contents
local files = app.fs.listFiles(app.fs.userDocsPath)
for _, filename in ipairs(files) do
  local full = app.fs.joinPath(app.fs.userDocsPath, filename)
  if app.fs.isDirectory(full) then
    print("[DIR] " .. filename)
  else
    print("[FILE] " .. filename)
  end
end

-- Create directories
app.fs.makeAllDirectories(app.fs.joinPath(app.fs.tempPath, "myapp", "cache"))

```

--------------------------------

### Close sub-path

Source: https://github.com/aseprite/api/blob/main/api/graphicscontext.md

Connects the current point back to the start of the sub-path.

```lua
gc:closePath()
```

--------------------------------

### app.useTool() - Programmatic Drawing

Source: https://context7.com/aseprite/api/llms.txt

Simulates drawing with any Aseprite tool, including brushes, colors, and blend modes.

```APIDOC
## app.useTool()

### Description
Simulates the use of an Aseprite tool programmatically.

### Parameters
- **tool** (string) - Required - The name of the tool (e.g., "pencil", "filled_rectangle", "paint_bucket").
- **color** (Color) - Optional - The color to use.
- **points** (table) - Required - An array of `Point` objects defining the tool path.
- **brush** (Brush) - Optional - Custom brush settings.
- **tolerance** (number) - Optional - Tolerance for tools like paint bucket.
- **contiguous** (boolean) - Optional - Whether the tool should be contiguous.
```

--------------------------------

### Create a new frame using app.command.NewFrame

Source: https://github.com/aseprite/api/blob/main/api/command/NewFrame.md

Executes the command to add a frame. The content parameter determines the initial state of the new frame.

```lua
app.command.NewFrame {
  content=string
}
```

--------------------------------

### Version() Constructor

Source: https://github.com/aseprite/api/blob/main/api/version.md

Creates a new Version object from a string representation of the version.

```APIDOC
## Version()

```lua
local v = Version("1.2.10")
```

You can create a new version from a string. Then access each field
```

--------------------------------

### Palette Creation

Source: https://github.com/aseprite/api/blob/main/api/palette.md

Demonstrates various ways to create a new Palette object, including default, with a specified number of colors, copying another palette, or loading from a file or resource.

```APIDOC
## Palette()

### Description
Creates a new palette. By default it will contain 256 colors, but you can specify a `numberOfColors` (integer value).

`otherPalette` can be another palette object to create a copy of it.

If `fromFile` is given, the palette is loaded from the file name.

If `fromResource` is given, the `resourceID` is an ID specified in one of the [extensions palette](https://github.com/aseprite/aseprite/tree/main/data/extensions) (e.g. [`DB16`](https://github.com/aseprite/aseprite/blob/8e193b592ae06abb36be6f72ef43c308b511b24c/data/extensions/dawnbringer-palettes/package.json#L13), [`DB32`](https://github.com/aseprite/aseprite/blob/8e193b592ae06abb36be6f72ef43c308b511b24c/data/extensions/dawnbringer-palettes/package.json#L14), [`Solarized`](https://github.com/aseprite/aseprite/blob/8e193b592ae06abb36be6f72ef43c308b511b24c/data/extensions/software-palettes/package.json#L15)).

### Usage Examples
```lua
local palette = Palette()
local palette = Palette(numberOfColors)
local palette = Palette(otherPalette)
local palette = Palette{ fromFile=filename }
local palette = Palette{ fromResource=resourceID }
```
```

--------------------------------

### Get Sprite specification

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Returns the image specification object for the sprite.

```lua
local spec = sprite.spec
```

--------------------------------

### Create File Selection Dialog

Source: https://github.com/aseprite/api/blob/main/api/dialog.md

Use this to create a dialog for selecting files to open or save. Configure options like filename, title, file types, and callbacks.

```lua
local dlg = Dialog()
dlg:file{ id=string,
          title=string,
          filename=string,
          basepath=string,
          open=boolean,
          save=boolean,
          entry=boolean,
          filetypes={ string1,string2,string3... },
          onchange=function }
```

--------------------------------

### Get Sprite color mode

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Returns the color mode of the sprite.

```lua
local colormode = sprite.colormode
```

--------------------------------

### Get Sprite ID

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Returns the unique integer ID of the sprite.

```lua
local id = sprite.id
```

--------------------------------

### Load a library with require()

Source: https://github.com/aseprite/api/blob/main/api/base.md

Loads a module from the script or plugin folder. Modules are namespaced by plugin name to prevent conflicts.

```lua
local library = require "library"
```

--------------------------------

### Layer Color

Source: https://github.com/aseprite/api/blob/main/api/layer.md

Get or set the user-defined color for a layer in the timeline.

```APIDOC
## Layer.color

```lua
local color = layer.color
layer.color = color
```

Gets or sets the user-defined [color](color.md#color) of this layer in the timeline.
```

--------------------------------

### app.command.KeyboardShortcuts

Source: https://github.com/aseprite/api/blob/main/api/app_command.md

Opens the keyboard shortcut menu.

```APIDOC
## app.command.KeyboardShortcuts

### Description
Opens the keyboard shortcut menu, use the `search` parameter to pre-fill the searchbar.

### Parameters
#### Request Body
- **search** (string) - Optional - String to pre-fill the searchbar.
```

--------------------------------

### Rectangle.size

Source: https://github.com/aseprite/api/blob/main/api/rectangle.md

Gets or sets the size of the rectangle using a Size object.

```APIDOC
## Rectangle.size

### Description
Gets or sets the size of the rectangle with a [Size](size.md#size) object, similar to changing [Rectangle.width](#rectanglewidth) and [Rectangle.height](#rectangleheight) simultaneously.

### Method
Getter/Setter

### Parameters
- **newSize** (Size) - Optional - A Size object to set the dimensions to.

### Request Example
```lua
local rect = Rectangle{ x=10, y=20, width=50, height=30 }

-- Get the size
local sizeObject = rect.size

-- Set the size
rect.size = Size(60, 40)
```

### Response
#### Success Response (Size or void)
- **Size** - The size of the rectangle as a Size object (getter).
- **void** - No return value (setter).
```

--------------------------------

### Point Constructor Syntax

Source: https://github.com/aseprite/api/blob/main/api/point.md

Defines the various ways to instantiate a new Point object.

```lua
Point()
Point(otherPoint)
Point(x, y)
Point{x=number, y=number}
Point{number, number}
```

--------------------------------

### Rectangle.origin

Source: https://github.com/aseprite/api/blob/main/api/rectangle.md

Gets or sets the origin of the rectangle using a Point object.

```APIDOC
## Rectangle.origin

### Description
Gets or sets the origin of the rectangle with a [Point](point.md#point) object, similar to changing [Rectangle.x](#rectanglex) and [Rectangle.y](#rectangley) simultaneously.

### Method
Getter/Setter

### Parameters
- **newPoint** (Point) - Optional - A Point object to set the origin to.

### Request Example
```lua
local rect = Rectangle{ x=10, y=20, width=50, height=30 }

-- Get the origin
local originPoint = rect.origin

-- Set the origin
rect.origin = Point(5, 15)
```

### Response
#### Success Response (Point or void)
- **Point** - The origin of the rectangle as a Point object (getter).
- **void** - No return value (setter).
```

--------------------------------

### Access Tag Name

Source: https://github.com/aseprite/api/blob/main/api/tag.md

Gets or sets the string name of the tag.

```lua
local name = tag.name
tag.name = name
```

--------------------------------

### Dialog Constructor Options

Source: https://github.com/aseprite/api/blob/main/api/dialog.md

Illustrates different ways to construct a Dialog object, including setting the title, autofit behavior, parent dialog, and handling close events.

```lua
local dlg = Dialog()
local dlg = Dialog(string)
local dlg = Dialog{ title=string,
                    autofit=align,
                    notitlebar=false,
                    resizeable=false,
                    parent=otherDialog,
                    onclose=function }
```

--------------------------------

### Get Grid Origin

Source: https://github.com/aseprite/api/blob/main/api/grid.md

Retrieves the origin of the grid as a point object.

```lua
local point = grid.origin
```

--------------------------------

### Establish WebSocket Connections in Aseprite

Source: https://context7.com/aseprite/api/llms.txt

Connect to WebSocket servers for real-time communication. Handles connection events, text messages, and closing. Supports sending text and parsing JSON data.

```lua
local ws

local function handleMessage(messageType, data)
  if messageType == WebSocketMessageType.OPEN then
    print("Connected to server")
    ws:sendText("Hello from Aseprite!")

  elseif messageType == WebSocketMessageType.TEXT then
    print("Received: " .. data)

    -- Parse JSON messages
    local msg = json.decode(data)
    if msg.command == "draw" then
      app.useTool{
        tool="pencil",
        color=Color{ r=msg.r, g=msg.g, b=msg.b },
        points={ Point(msg.x, msg.y) }
      }
    end

  elseif messageType == WebSocketMessageType.CLOSE then
    print("Disconnected")
  end
end

ws = WebSocket{
  url="ws://localhost:8080",
  onreceive=handleMessage,
  deflate=false
}

ws:connect()

-- Later: ws:close()
```

--------------------------------

### Initialize Color objects

Source: https://github.com/aseprite/api/blob/main/api/color.md

Constructs a new Color object using various color space parameters. Alpha defaults to 255 if not specified.

```lua
local c
c = Color{ r=255, g=255, b=255, a=255 }
c = Color{ h=360.0, s=1.0, v=1.0, a=255 }
c = Color{ h=360.0, s=1.0, l=1.0, a=255 }
c = Color{ red=255, green=255, blue=255, alpha=255 }
c = Color{ hue=360.0, saturation=1.0, value=1.0, alpha=255 }
c = Color{ hue=360.0, saturation=1.0, lightness=1.0, alpha=255 }
c = Color{ gray=255, alpha=255 }
c = Color{ index=integer }
c = Color(integer)
```

--------------------------------

### GET app.isUIAvailable

Source: https://github.com/aseprite/api/blob/main/api/app.md

Check if the graphical user interface is currently available.

```APIDOC
## GET app.isUIAvailable

### Description
Returns true if the UI is available (e.g., not running in batch mode), allowing the use of alerts or dialogs.

### Method
GET

### Endpoint
app.isUIAvailable

### Response
- **isAvailable** (boolean) - True if UI is available, false otherwise.
```

--------------------------------

### app.clipboard.text

Source: https://github.com/aseprite/api/blob/main/api/app_clipboard.md

Gets or sets the clipboard text. Returns `nil` if there is no text.

```APIDOC
## app.clipboard.text

### Description
Gets or sets the clipboard text. Returns `nil` if there is no text.

### Method
GET/SET

### Endpoint
app.clipboard.text

### Request Example
```lua
local text = app.clipboard.text
app.clipboard.text = "New text"
```

### Response
#### Success Response (200)
- **text** (string | nil) - The text content of the clipboard, or nil if none.
```

--------------------------------

### Get OS Name

Source: https://github.com/aseprite/api/blob/main/api/app_os.md

Retrieves the name of the operating system platform.

```APIDOC
## app.os.name

### Description
Returns the platform name. It can be `Windows`, `macOS`, or `Linux`.

### Method
GET

### Endpoint
/app/os/name

### Response
#### Success Response (200)
- **name** (string) - The name of the operating system (e.g., "Windows", "macOS", "Linux").

### Response Example
```json
{
  "name": "macOS"
}
```
```

--------------------------------

### Simulating Tools with app.useTool

Source: https://context7.com/aseprite/api/llms.txt

Use app.useTool to programmatically trigger Aseprite tools like pencils, rectangles, or paint buckets. This supports custom brushes, colors, and selection modes.

```lua
-- Draw a line with the pencil tool
app.useTool{
  tool="pencil",
  color=Color{ r=255, g=128, b=0 },
  points={ Point(10, 10), Point(50, 50) }
}

-- Draw a filled rectangle
app.useTool{
  tool="filled_rectangle",
  color=Color{ r=0, g=255, b=0, a=128 },
  points={ Point(20, 20), Point(80, 60) }
}

-- Draw with a custom brush
local brush = Brush{
  type=BrushType.CIRCLE,
  size=8
}
app.useTool{
  tool="pencil",
  brush=brush,
  color=app.fgColor,
  points={ Point(0, 50), Point(100, 50), Point(50, 0), Point(50, 100) }
}

-- Use paint bucket with tolerance
app.useTool{
  tool="paint_bucket",
  color=Color{ r=255, g=255, b=0 },
  points={ Point(50, 50) },
  tolerance=32,
  contiguous=true
}

-- Create a selection using the rectangular marquee
app.useTool{
  tool="rectangular_marquee",
  points={ Point(10, 10), Point(90, 90) },
  selection=SelectionMode.REPLACE
}
```

--------------------------------

### Create ColorSpace instances

Source: https://github.com/aseprite/api/blob/main/api/colorspace.md

Initializes a new ColorSpace object as empty, sRGB, or from an ICC file path.

```lua
local none = ColorSpace()
local srgb = ColorSpace{ sRGB=true }
local icc = ColorSpace{ fromFile="/path/file.icc" }
```

--------------------------------

### Layer Data

Source: https://github.com/aseprite/api/blob/main/api/layer.md

Get or set user-defined string data associated with a layer.

```APIDOC
## Layer.data

```lua
local data = layer.data
layer.data = data
```

Gets or sets the user-defined data related to this layer (a text string).
```

--------------------------------

### Load Mask from File

Source: https://github.com/aseprite/api/blob/main/api/command/LoadMask.md

Use this command to load a mask from a specified .msk file. Set `ui` to `false` to bypass the file picker and load directly.

```lua
app.command.LoadMask {
  ui=bool,
  filename=string
}
```

--------------------------------

### Get Palette size

Source: https://github.com/aseprite/api/blob/main/api/palette.md

Retrieves the total number of colors currently in the palette.

```lua
local ncolors = #palette
```

--------------------------------

### Accessing Point Y Coordinate

Source: https://github.com/aseprite/api/blob/main/api/point.md

Shows how to get or set the y property of a Point instance.

```lua
local y = point.y
point.y = newY
```

--------------------------------

### Execute Command with Parameters

Source: https://github.com/aseprite/api/blob/main/api/app_command.md

Use this syntax to pass parameters to an Aseprite command. Note that parameter names with hyphens must be enclosed in brackets and quotes.

```lua
app.command.CommandName { ["param-name1"]="param-value1", ["param-name2"]="param-value2" }
```

```lua
app.command.CommandName { ["parameter-name"]="value", ["other-parameter-name"]="otherValue" }
```

--------------------------------

### Editor.spritePos

Source: https://github.com/aseprite/api/blob/main/api/editor.md

Gets the mouse position relative to the sprite's pixel coordinates.

```APIDOC
## Editor.spritePos

### Description
Returns a [point](point.md#point) of the the mouse position on the sprite, i.e. what pixel is going to be changed if the user clicks the mouse.

### Method
GET

### Endpoint
app.editor.spritePos

### Response
#### Success Response (200)
- **point** (object) - A table with `x` and `y` properties representing the mouse coordinates on the sprite.
```

--------------------------------

### Execute Aseprite Commands

Source: https://github.com/aseprite/api/blob/main/api/app_command.md

Use app.command to execute Aseprite commands. Commands can be called with or without parameters, which are passed as a table.

```lua
app.command.CommandName()
app.command.CommandName { param1=value1, param2=value2, ... }
```

--------------------------------

### Get File Size - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Retrieves the size of the specified file in bytes.

```lua
local size = app.fs.fileSize(fn)
```

--------------------------------

### Rectangle Constructor Overloads

Source: https://github.com/aseprite/api/blob/main/api/rectangle.md

Demonstrates the different ways to create a Rectangle object, including default, copy, coordinate-based, and table-based initializations.

```lua
Rectangle()
Rectangle(otherRectangle)
Rectangle(x, y, width, height)
Rectangle{x=number, y=number, width=number, height=number}
Rectangle{x=number, y=number, w=number, h=number}
Rectangle{number, number, number, number}
```

--------------------------------

### Listen for Application Events

Source: https://context7.com/aseprite/api/llms.txt

Subscribe to application-wide events to react to user actions. Includes examples for site changes, color changes, and command interception.

```lua
-- Listen for site changes (sprite/layer/frame changes)
app.events:on('sitechange', function()
  print("Site changed!")
  if app.sprite then
    print("  Sprite: " .. (app.sprite.filename or "untitled"))
  end
  if app.layer then
    print("  Layer: " .. app.layer.name)
  end
  if app.frame then
    print("  Frame: " .. app.frame.frameNumber)
  end
end)

-- Listen for foreground color changes
app.events:on('fgcolorchange', function()
  print("FG Color: R=" .. app.fgColor.red ..
        " G=" .. app.fgColor.green ..
        " B=" .. app.fgColor.blue)
end)

-- Intercept commands before they execute
app.events:on('beforecommand', function(ev)
  print("Command: " .. ev.name)
  if ev.name == "Cut" then
    -- Convert Cut to Copy
    app.command.Copy()
    ev.stopPropagation()  -- Cancel the original Cut
  end
end)
```

--------------------------------

### Get Current Path - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Retrieves the directory from which the Aseprite executable was launched.

```lua
app.fs.currentPath
```

--------------------------------

### Create a new Palette

Source: https://github.com/aseprite/api/blob/main/api/palette.md

Initializes a new palette object using various constructors, including default, size-based, copy, or file/resource loading.

```lua
local palette = Palette()
local palette = Palette(numberOfColors)
local palette = Palette(otherPalette)
local palette = Palette{ fromFile=filename }
local palette = Palette{ fromResource=resourceID }
```

--------------------------------

### Access Color HSV components

Source: https://github.com/aseprite/api/blob/main/api/color.md

Gets or sets the HSV components of a color.

```lua
local c = Color{ h=45, s=0.5, v=0.2 }
assert(c.hsvHue        == 45)
assert(c.hsvSaturation == 0.5)
assert(c.hsvValue      == 0.2)
```

--------------------------------

### Extract Path Part - Lua

Source: https://github.com/aseprite/api/blob/main/api/app_fs.md

Gets the directory part of a given filename.

```lua
local pathPart = app.fs.filePath(fn)
```

--------------------------------

### Connect WebSocket Client

Source: https://github.com/aseprite/api/blob/main/api/websocket.md

Manually initiates a connection to the WebSocket server. A successful connection triggers the `WebSocketMessageType.OPEN` event in the `onreceive` handler.

```lua
WebSocket:connect()
```

--------------------------------

### LoadPalette Command

Source: https://github.com/aseprite/api/blob/main/api/command/LoadPalette.md

Loads a palette from a specified file path or a built-in preset.

```APIDOC
## LoadPalette

### Description
Loads a palette from the given preset or filename.

### Parameters
#### Request Body
- **ui** (boolean) - Optional - Shows the file picker dialog with filename pre-completed, true by default. Set to false to load filename directly without user confirmation.
- **filename** (string) - Optional - A path to a supported palette or file to extract a palette from.
- **preset** (string) - Optional - The name of a palette preset, "default" resets the palette to default. If set, filename is ignored.

### Request Example
{
  "ui": false,
  "filename": "/path/to/palette.gpl"
}
```

--------------------------------

### Manage Cel Color

Source: https://github.com/aseprite/api/blob/main/api/cel.md

Gets or sets the user-defined color for the cel in the timeline.

```lua
local color = cel.color
cel.color = newColor
```

--------------------------------

### app.open()

Source: https://github.com/aseprite/api/blob/main/api/app.md

Opens a new sprite by loading it from a specified file path. Returns the Sprite object or nil if an error occurs.

```APIDOC
## app.open()

Opens a new sprite loading it from the given filename. Returns an instance of the [Sprite class](sprite.md#sprite) or `nil` if something went wrong.

### Usage:

```lua
local sprite = app.open(filename)
if sprite then
  -- Sprite opened successfully
else
  -- Failed to open sprite
end
```
```

--------------------------------

### Get Sprite redo steps

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Returns the number of available redo steps for the sprite.

```lua
local redosteps = sprite.undoHistory.redoSteps
```

--------------------------------

### Get Sprite undo steps

Source: https://github.com/aseprite/api/blob/main/api/sprite.md

Returns the number of available undo steps for the sprite.

```lua
local undosteps = sprite.undoHistory.undoSteps
```

--------------------------------

### Layer Tileset

Source: https://github.com/aseprite/api/blob/main/api/layer.md

Get or set the tileset associated with a layer, applicable only if the layer is a tilemap.

```APIDOC
## Layer.tileset

```lua
local tileset = layer.tileset
layer.tileset = newTileset
```

Gets or sets the [tileset](tileset.md#tileset) associated to this
layer only when [it's a tilemap](#layeristilemap) (returns nil in
other case).
```

--------------------------------

### Manage Layer Data

Source: https://github.com/aseprite/api/blob/main/api/layer.md

Gets or sets the user-defined string data attached to a layer.

```lua
local data = layer.data
layer.data = data
```