Shows the Aseprite executable in use, its version, and whether a live Aseprite is connected to the bridge.

Copies the bridge extension into Aseprite's user extensions folder. A running Aseprite must be restarted to load it.

Starts the Aseprite GUI with the bridge extension and waits for it to connect, enabling live mode. The first time, Aseprite asks to allow the script's network and file access; tick 'Give full trust' / 'Don't show again' in that dialog.

Runs Lua code inside Aseprite with the full scripting API (app, Sprite, Image, Layer, Color, ...). Globals: args (your args object), sprite (resolved sprite or app.sprite), MCP (helper runtime: MCP.color(), MCP.layer(spr, ref), MCP.sprite_info(spr) ...). print output is captured. The return value is sent back as JSON. Use api_docs for the API reference.

Executes any Aseprite menu command (app.command.) with parameters, e.g. Flip, Rotate, Outline, BrightnessContrast, ColorQuantization, LinkCels, ReverseFrames, AutocropSprite. See list_commands for names and parameters. Strings like '#ff0000' become Colors; {x,y,width,height} becomes a Rectangle. ui=false is added unless allowUi is true.

Lists Aseprite commands usable with run_command, with their parameters (extracted from the Aseprite source).

Reads the Aseprite Lua API reference (bundled from github.com/aseprite/api). Without a topic, lists topics. Topics include app, sprite, layer, cel, image, color, palette, tag, slice, tileset, selection, dialog, websocket, and command/.

Runs the Aseprite command line in batch mode (aseprite -b ) and returns its output. Useful for --sheet/--data exports, --split-layers, --list-tags, --save-as with {layer}/{frame} templates, --scale, --color-mode, etc. See https://www.aseprite.org/docs/cli/.

Returns Aseprite's current state: open sprites, active sprite/layer/frame, foreground/background colors, tool, brush, timeline range and editor zoom (live).

Changes what is active in the UI: sprite/layer/frame, foreground/background color, tool, brush, editor zoom, and the timeline range (selected frames/layers/colors). Mostly useful in live mode.

Undoes or redoes steps on a sprite (live mode; batch processes have no history between calls).

Lists Aseprite preference sections and options (from pref.xml) for use with the preferences tool.

Gets or sets an Aseprite preference (app.preferences..), a tool preference (tool=) or a per-sprite document preference (document=true). Use list_preferences to discover names.

Lists sprites open in Aseprite.

Creates a new sprite. In batch mode 'file' is required (the sprite is saved there).

Opens a sprite file (any format Aseprite reads: .aseprite, .png, .gif, .jpg, .webp, .bmp, .tga, .pcx, .ico, .flc, .qoi, .psd...) and returns its structure. In live mode it opens a tab.

Returns a sprite's full structure: size, color mode, frames and durations, layer tree (with opacity, blend mode, visibility...), tags, slices, tilesets, palette size, grid, selection and active layer/frame.

Saves a sprite (Save / Save As), or with copy=true saves a copy without changing the sprite's file name. The extension picks the format. Single-image formats get one file per frame (name1.png, name2.png...); the result lists the files written.

Closes an open sprite (live mode).

Changes sprite metadata: filename, user data, tab color, transparent color index, pixel ratio, grid bounds, user properties, color space.

Scales the whole sprite (all layers and frames). Give width and/or height, or scale.

Grows or shrinks the canvas without scaling pixels: either margins (left/top/right/bottom, negative values cut) or a new width/height with an anchor.

Crops the sprite to a rectangle, to the selection (mode='selection'), or trims empty borders (mode='auto').

Converts the sprite to RGB, grayscale or indexed, with optional dithering.

Flips and/or rotates the whole sprite, the active cel(s) of a layer/frame, or the selection.

Adds an image, group or tilemap layer, optionally inside a group or above/below another layer, with its properties set.

Changes layer properties: name, visibility, lock, opacity, blend mode, color, data, parent group, stack position.

Deletes a layer (and its children if it is a group).

Duplicates a layer with all its cels.

Merges a layer into the one below (mode='down'), flattens all layers ('flatten'), or flattens only visible layers ('visible').

Converts a layer: to a Background layer, from Background to a normal layer, or between image and tilemap layers.

Adds frames. By default copies the previous frame's cels; empty=true adds blank frames.

Deletes one frame, a range, a list, or a tag's frames.

Sets frame durations in milliseconds for one frame, a range, a list, a tag, or 'all'.

Moves a frame (with its cels) to another position.

Lists cels (layer/frame pairs with images) with bounds, opacity, z-index and data, filtered by layer and frames.

Changes a cel: position (absolute x/y or relative dx/dy), opacity, z-index, color, data, properties, or moves it to another frame.

Deletes the cel(s) of a layer in the given frames.

Copies a cel's image to another layer/frame (and optionally another open sprite).

Sets individual pixels on a layer/frame (one undo step). Either 'pixels' as [[x,y,color],...] / [{x,y,color}], or pixel art as 'rows' of characters with a 'legend' mapping each character to a color; rows start at (x,y). Unmapped ' ' and '.' are skipped; map '.' to 'transparent' to erase. The cel grows as needed; pixels outside the canvas are dropped.

Reads pixels of the rendered frame (all visible layers) or of one layer. Default format 'legend' returns rows of characters plus a legend of colors ('.' = transparent); 'hex' returns a grid of '#rrggbbaa' (null = transparent). Indexed sprites return palette indices.

Draws with an Aseprite tool as if the user dragged through 'points' (app.useTool). Tools: pencil, brush-like strokes with eraser/spray/blur/jumble, line, curve (4 points), rectangle, filled_rectangle, ellipse, filled_ellipse, paint_bucket (1 point), gradient, contour, polygon, and selection tools (rectangular_marquee, elliptical_marquee, lasso, polygonal_lasso, magic_wand).

Draws an image file (PNG, etc.) into a layer/frame at (x,y). mode 'blend' composites over existing pixels, 'copy' overwrites the area, 'replace' swaps the whole cel image. Optional source crop, scale or target size.

Clears a layer's cel(s) to transparent (or fills with a color): whole cel, a rect, or the selected area.

Replaces one color with another on a layer (or all layers) across frames, with optional per-channel tolerance (RGB).

Applies an image filter command to the active cel(s) or selection: BrightnessContrast, HueSaturation, ColorCurve, ConvolutionMatrix, Despeckle, InvertColor, Outline, ReplaceColor. Params follow list_commands (e.g. Outline {color:'#000000', place:'outside', matrix:'circle'}; HueSaturation {hue, saturation, lightness, alpha}; BrightnessContrast {brightness, contrast}).

Creates or changes the selection: rect, ellipse, polygon, magic_wand (point), by_color, all, none, invert, reselect, content (layer pixels), modify (expand/contract/border), move (dx/dy), get, save or load (to/from a .msk or image file). The selection lives only in live mode or inside one run_lua call.

Acts on the selection: copy, copy_merged, cut, paste (optional x,y), delete, fill, stroke (with color), move_content / move_bounds (dx,dy, wrap), new_sprite, new_layer_via_copy, new_layer_via_cut, crop.

Returns the sprite palette as '#rrggbbaa' colors (index 0 first).

Changes the palette: set colors starting at 'start', replace it entirely, resize, load from a file (.gpl, .pal, .act, .ase, .png...) or a built-in preset (e.g. DB16, DB32, PICO-8...), or generate it from the sprite's colors (fromSprite).

Saves the sprite palette to a file (.gpl, .pal, .act, .png, .ase, .hex...).

Adds an animation tag over a frame range.

Changes a tag's name, range, direction, repeats, color or data.

Deletes a tag (frames are kept).

Adds a slice (with optional 9-slice center and pivot), or duplicates one with copyFrom.

Changes a slice.

Deletes a slice.

Tileset operations: list, add (tileSize, count), update (name, baseIndex, data), delete, add_tile, delete_tile, get_tile (pixels as rows+legend), set_tile (rows+legend or an image file). Tile index 0 is the empty tile.

Reads (action 'get') or writes (action 'set') the tile indices of a tilemap layer's cel. Set with 'cells' [{col,row,tile}] or 'rows' (2D array of tile indices, -1/null to skip) starting at col/row.

Draws text onto a layer. In live mode it uses Aseprite's text renderer with any font Aseprite knows (its built-in 'Aseprite' pixel font, or an installed system font by name such as 'Arial'). In batch mode, or with font='builtin', it uses a built-in 5x7 pixel font that can be scaled by whole numbers. Multi-line text with \n is supported.

Draws vector shapes with optional antialiasing: rect, rounded_rect, oval/ellipse, line, polyline, polygon, bezier (cubic, points = start then control1, control2, end per segment), or path (ops: move/line/cubic/close). Each shape is stroked (width) or filled. Antialiasing is off by default to keep hard pixel edges. For pixel-exact aliased shapes use_tool is closer to Aseprite's own tools.

Links cels so several frames share one image (edits to one show in all), or unlinks them. Linking needs live mode. Unlinking works in both modes.

Edits the palette structure: add or insert colors, remove entries, move entries, sort (by hue, saturation, value, lightness, luminance, red, green, blue, alpha), reverse a range, generate a ramp between two colors, or dedupe. In indexed sprites pixels are remapped so they keep their colors (set remapPixels=false to skip); pixels using removed colors move to the nearest remaining one.

Reads or changes per-sprite view settings: grid (show, snap, bounds, color, opacity), pixel grid, symmetry mode and axes, tiled mode, onion skin, overlays (layer edges, selection edges, slices, auto guides, tile numbers, brush preview), checkerboard colors; and in live mode zoom, scroll, fit to screen, playback, timeline and preview window. Call with no options to read them.

Reads or writes the system clipboard: info, get_text, set_text, clear, get_image (returned as a preview image, or saved to 'file'), set_image (from an image file, or a rendered sprite frame/layer/rect).

Makes a copy of a whole sprite (all layers, frames, tags, slices). In batch mode 'file' is required.

Gets, sets, deletes or replaces custom properties on a sprite, layer, cel, tag, slice, tileset or tile. With pluginKey ('publisher/extension') it reads/writes that extension's properties instead of the user properties.

Live mode: returns what happened in Aseprite since a sequence number: sprite changes (including undo/redo), switching sprite/layer/frame, commands run, and color changes. Events caused by MCP calls are hidden unless includeMcp is true. Pass the returned lastSeq as 'since' next time.

Live mode: shows a dialog in Aseprite and waits for the user to answer. Can show text plus input fields (entry, number, slider, check, combobox, color, label) and buttons. Returns the pressed button and field values.

Renders frames as an image you can look at (nearest-neighbor upscaled, transparency shown as a checkerboard). Multiple frames are laid out in a grid in frame order. Use this after edits to check the result.

Exports a copy of the sprite to any format (png, gif, webp, jpg, bmp, tga, pcx, ico, qoi, flc, svg, css, ...). Options: scale, a tag or a 1-based frame range, a slice, specific layers, or a filename template like 'out_{frame}.png' ({frame} counts from 0). Single-image formats with several frames get one file per frame (name1.png, name2.png..., or starting from a trailing number in the name); the result lists every file written.

Exports a sprite sheet image plus optional JSON data (File > Export Sprite Sheet). Supports layouts, padding, trimming, extrusion, splitting by layers/tags, tilesets, and listing layers/tags/slices in the JSON.

Opens an image and slices it into frames (File > Import Sprite Sheet). Optionally saves the result.