Aseprite Live

Palette-lock every ``.aseprite`` in ``folder``: snap each sprite (first frame, alpha preserved) to a palette and export images to ``out_dir``. Give a ``preset`` (gameboy/pico8/cga) or an explicit ``palette`` list of #rrggbb. Non-destructive; continues past per-file errors. Headless.

Export every ``.aseprite`` in ``folder`` (first frame) to an image, optionally integer-upscaled by ``scale``. Non-destructive: writes ``<name>.<format>`` to ``out_dir`` (default = ``folder``); never modifies the source. Continues past per-file errors. Headless. (``file`` is ignored — this operates on a folder.)

Resize every ``.aseprite`` in ``folder`` (first frame, nearest-neighbor) and write images to ``out_dir``. Give either ``scale`` (multiplier) or explicit ``width``/``height``. Non-destructive; continues past per-file errors. Headless.

Blur the active cel with an alpha-weighted box kernel. ``radius`` 1-4 (1 = 3x3). Transparent neighbors don't darken edges. One undo step.

Withdraw a pending ``ask_point`` request (e.g. the artist stepped away and you're moving on).

Empty the cel at the given layer + frame (transparent).

Close the active sprite. Errors if it has unsaved changes unless ``force=true`` — save_sprite first, or force to discard them. Aimed at the live editor (frees the tab); headless has no persistent session, so there is nothing to close there.

Create a named slice (atlas region) at the given rectangle. Slices become Unity sprites via export_unity_slices. One undo step. Headless: pass ``file``.

Create a new sprite. Live: opens a new untitled sprite in the editor. Headless: writes a new .aseprite to ``file`` (required). ``color_mode`` is one of rgb | gray | indexed.

Create an animation tag named ``name`` spanning frames ``from_frame``..``to_frame`` (1-based).

Create a tilemap layer with its own tileset on a tile_width x tile_height grid. The new tileset starts with only tile 0, the reserved empty tile — use add_tile to append editable tiles. One undo step. Headless: pass ``file``.

Crop the sprite to the given rectangle.

Delete frame ``number`` (1-based). Cannot delete the last frame.

Delete the layer with the given name.

Delete the slice with the given name. One undo step. Headless: pass ``file``.

Delete the animation tag named ``name``.

Convert the active cel to grayscale (Rec. 601 luma), keeping alpha. One undo step. Headless: pass ``file``.

Clear the current selection.

Draw a circle centered at (center_x, center_y). ``fill`` true fills the disk. One undo step. Headless: pass ``file``.

Draw an ellipse centered at (center_x, center_y) with independent x/y radii. ``fill`` true fills it. One undo step. Headless: pass ``file``.

Fill a rectangle with a linear gradient from ``color1`` to ``color2``. ``direction`` is horizontal | vertical | diagonal. ``dither`` true uses an ordered Bayer dither between the two colors instead of blending RGB — the palette-friendly way. One undo step. Headless: pass ``file``.

Draw a 2:1 isometric box. The footprint diamond is centered at (center_x, center_y) with the given ``half_width`` (full tile width = 2×half_width), rising ``height`` px. Top/left/right faces are auto-shaded from ``color`` (#rrggbb, light from top-left) with stroke + highlight. Returns the top/SE/SW face corner polygons so you can attach recessed ports or details. One undo step. Headless: pass ``file``.

Draw a vertical isometric cylinder (tank/silo/chimney): top ellipse + shaded body + front rim, auto-shaded from ``color``. ``top_y`` is the top of the body. One undo step. Headless: pass ``file``.

Draw a 1px line from (x1,y1) to (x2,y2). One undo step. Headless: pass ``file``.

Set pixels on one tile of a tilemap layer's tileset. ``pixels`` is a list of {x, y, color} objects (color #rrggbb or #rrggbbaa; x/y relative to the tile's top-left). Pixels outside the tile are skipped and counted. Every placed instance of the tile updates. One undo step. Headless: pass ``file``.

Set individual pixels: ``pixels`` is a list of ``{"x": int, "y": int, "color": "#rrggbb[aa]"}``. The precision tool for detail work — one undo step for the whole batch. Capped at 4096 pixels per call. Headless: pass ``file``.

Stroke connected line segments through ``points`` (ordered [x, y] pairs); ``close=True`` joins the last point back to the first. One undo step. Headless: pass ``file``.

Draw a rectangle on the active layer + frame. ``color`` is #rrggbb or #rrggbbaa. ``fill`` false draws only the outline. One undo step (live). Headless: pass ``file``.

Duplicate frame ``number`` (1-based).

Duplicate a layer (with its cels) above the original.

Erase pixels to transparent. Pass an explicit rect (works everywhere, including headless), or pass nothing to erase the current selection — including non-rectangular ones (live editor). One undo step.

Grow (or shrink, with negatives) the canvas per side WITHOUT scaling content — existing pixels keep their positions relative to the old origin. One undo step. Headless: pass ``file``.

Export every image layer (recursing into groups) as its own PNG in ``out_dir``, named ``<sanitized-layer-name>.png``. Hidden layers are exported too; every layer's original visibility is restored afterwards, so the document ends exactly as it started. A multi-frame sprite splits each layer into ``<name>1.png``, ``<name>2.png``, ...; the returned ``files`` lists what was actually written. Headless: pass ``file``.

Export the active sprite to a file; format is chosen by ``out_path`` extension (.png, .gif, ...). A multi-frame sprite saved to a single-image format is split into ``<name>1.ext``, ``<name>2.ext``, ...; a multi-frame sprite saved to ``.gif`` becomes one animated GIF (all frames, honoring per-frame durations). The returned ``files`` lists what was actually written. Does not modify the sprite. Headless: pass ``file``.

Pack all frames into a single sprite-sheet image (optionally writing a JSON atlas to ``data_path``). ``sheet_type`` is rows | columns | horizontal | vertical | packed. Does not modify the sprite. Headless: pass ``file``.

Export each animation tag's frame range as its own file in ``out_dir``: an animated ``<tag-name>.gif`` (format="gif", default) or a horizontal ``<tag-name>.png`` strip (format="png"). Errors if the sprite has no tags. Returns each tag's file, frame range, and frame count. Does not modify the sprite. Headless: pass ``file``.

Export a tilemap layer's tileset as a horizontal PNG strip (plus an Aseprite JSON atlas if ``data_path`` is given). The strip includes tile 0 (the empty tile) first, so tile index i sits at x = i * tile_width. Writes files but does not modify the sprite (it does make the layer active). Headless: pass ``file``.

Export the sprite as a single PNG AND write a Unity ``.meta`` with one Multiple-mode sprite **per named slice**, each carrying that slice's pivot — so an atlas laid out with slices imports into Unity already sliced *and* pivoted. No competitor's Aseprite→Unity path exports pivots. Requires slices (see create_slice / set_slice_pivot). Headless: pass ``file``.

Export a horizontal sprite sheet AND write the Unity ``.meta`` beside it, pre-sliced into named Multiple-mode sprites (one per frame) — one action, no manual Sprite Editor pass. ``alignment`` is one of center, top_left, top, top_right, left, right, bottom_left, bottom, bottom_right, custom; ``custom`` uses ``pivot_x``/``pivot_y`` (0..1, 0,0 = bottom left). Targets Unity 2021.3+/6. Headless: pass ``file``.

Extract a palette (median-cut) from an external image file and, by default, set it as the active sprite's palette — the concept-art → locked-palette step. Returns the colors as hex, sorted dark→light. Headless: pass ``file``.

Flood-fill the contiguous same-color region at (x, y). Most reliable on RGB sprites. One undo step. Headless: pass ``file``.

Scanline-fill an arbitrary polygon given ``points`` (a list of [x, y] pairs, in order). ``color`` is #rrggbb or #rrggbbaa. One undo step. Headless: pass ``file``.

Flatten all layers into a single layer.

Flip the whole sprite horizontally or vertically.

Pixel-exact diff of two composited frames: changed-pixel count and ratio, the bounding box of the change, and whether they're identical. Use it to verify an animation actually moves — or that an edit didn't leak into frames it shouldn't touch. Headless: pass ``file``.

Generate a dark->light shading ramp from ``base_color`` and APPEND it to the palette in order — ready for ``palette_ramp_walk``. ``count`` colors; ``hue_shift`` pushes shadows toward blue and highlights toward yellow. Returns the ramp as hex. One undo step. Headless: pass ``file``.

Poll the result of ``ask_point``: ``done`` false while waiting, then the clicked ``x``/``y`` (or ``cancelled`` if the artist pressed Esc).

Return a color histogram of the composited sprite: distinct opaque color count, total opaque pixels, and the ``top`` most-used colors with counts — a palette-drift check for the art-QA loop. Read-only. Headless: pass ``file``.

Poll the result of ``show_choice_dialog``: ``done`` false while the dialog is open, then the chosen button text.

Live editor only: current zoom, scroll, and which sprite pixel the mouse is over — lets an agent know what the artist is looking at.

Return the active sprite's palette as #rrggbbaa hex strings.

Read one composited pixel (all layers) at (x, y) as #rrggbbaa.

Read a composited pixel region as a grid of #rrggbbaa strings — the AI feedback loop for 'what does the canvas look like now'. Capped at 4096 px; use a smaller region or export for larger areas.

Report whether a selection exists and its bounding rectangle. (Selection is editor-session state — in headless mode it doesn't persist between calls, so this is mainly a live-editor tool.)

Get the active sprite's size, color mode, and layer/frame/tag lists. Headless: pass ``file`` (the .aseprite to inspect).

Read the sprite's typed key/value metadata (Properties).

Read a tilemap layer: tile size, tileset length, and the cel's grid size, pixel position, and tile-index grid (``tiles`` as rows of columns, flip flags stripped; capped at 64x64 with ``truncated`` set). Read-only. Headless: pass ``file``.

Poll the change counter started by ``watch_changes`` (``reset=True`` zeroes it after reading).

Import an external image file (PNG, etc.) into a new layer at (x, y) — a reference/trace layer for concept-art intake. One undo step. Headless: pass ``file``.

Slice a sheet PNG into animation frames: cells are read row-major at the given frame size onto a new "imported" layer, adding frames as needed. The sheet's dimensions must be exact multiples of the frame size. One undo step. Headless: pass ``file`` (the target sprite).

Invert the active cel's RGB (alpha untouched). One undo step.

Invert the current selection against the canvas bounds.

Draw a recessed docking socket/port on an isometric face — a light lit lip framing a dark recessed interior. ``points`` = the 4 corner [x, y] pairs of a face (e.g. the ``face_se`` returned by draw_iso_box). This is the consistent I/O-port style. One undo step. Headless: pass ``file``.

The full layer tree, top of stack first: name, path, kind (image/group/tilemap), visibility, and opacity — including layers nested in groups (which ``get_sprite_info`` lists only at the top level).

List every slice with its bounds, pivot, and 9-patch center. Read-only. Headless: pass ``file``.

Live editor only: list every open document — filename (or "(unsaved)"), size, frame/layer counts, unsaved-changes flag, and which one is active.

List animation tags with their frame ranges.

Replace the sprite's palette from a palette file (.gpl, .pal, .ase, .png strip — anything Aseprite reads). One undo step.

Measure the transparent 'sticker' padding around the content: content bounding box, per-side padding (left/right/top/bottom), fill ratio, and distinct opaque color count. Read-only. Headless: pass ``file``.

Merge a layer into the layer directly beneath it.

Reorder a layer in the stack. ``direction`` is up | down | top | bottom (bottom = stack index 1).

Move a layer inside a layer group.

Open a sprite file and make it the active document; returns its filename, size, and frame/layer counts. Live: opens a new tab in the editor. Headless: each call is a fresh process, so this is a "can Aseprite read this file" probe returning the file's info — to edit a file headless, pass it as the ``file`` argument of the editing tools instead.

Stamp an image at each [x, y] in ``points`` (points are stamp centers). The stamp comes from ``source_path`` (a PNG) or ``source_rect`` ([x, y, width, height] cut from the composited sprite). One undo step for the whole scatter. Headless: pass ``file``.

Derive the palette FROM the sprite's actual pixels (Aseprite's color quantization) — the inverse of ``quantize_to_palette``. Returns the new palette as hex. One undo step.

Shade by WALKING the arranged palette ±N indices toward lighter/darker (per light direction), instead of snapping to the luminance-nearest color — so hand-ordered shading ramps are respected. ``steps`` = max indices to walk at the fully-lit/shadowed edges. RGB sprite with an ordered ramp palette; one undo step. Headless: pass ``file``.

Audit the active sprite against project conventions and return per-check pass/fail. Any rule you pass is checked: exact canvas size (``expected_width``/``expected_height``), ``grid_multiple`` (canvas dims divisible by N), ``max_colors`` (distinct opaque colors ≤ N), and ``require_symmetric_padding`` (equal left/right + top/bottom margins). Read-only. Headless: pass ``file``.

Snap every opaque pixel of the active cel to its nearest color in the sprite's palette (alpha preserved) — enforce palette discipline after intake or shading. RGB sprite; one undo step. Headless: pass ``file``.

Redo the last undone edit (live editor).

Rename a layer.

Rename the animation tag ``old_name`` to ``new_name``. One undo step. Headless: pass ``file``.

Write a PNG of ``frame`` with up to ``prev`` earlier frames ghosted in red and ``next`` later frames ghosted in blue (Aseprite's onion-skin convention) at the given ghost ``opacity`` — so you can *see* the motion arc in one image. Does not modify the sprite. Headless: pass ``file``.

Replace every pixel matching ``from_color`` (within ``tolerance``, a 0-255 RGB distance) with ``to_color`` across the active cel, preserving each pixel's alpha unless ``to_color`` carries its own. One undo step. Headless: pass ``file``.

Scale the whole sprite to new pixel dimensions.

Reverse frame order (cels on every layer, plus durations) — the whole sprite by default, or the inclusive [from_frame..to_frame] range. One undo step.

Rotate the whole sprite by 90, 180, or 270 degrees clockwise (lossless). One undo step. Headless: pass ``file``.

Run arbitrary Lua inside Aseprite and return its result (advanced escape hatch — equivalent to local code execution). ``J(value)`` is available for JSON returns; wrap your own edits in ``app.transaction`` for clean undo. The prelude also provides ``editCel(fn)`` and ``findLayer(s, name)``. Set ``save=true`` (headless) to persist changes to ``file``. Your code must ``return`` a value.

Write the sprite's palette to a file (.gpl, .pal, .png — by extension).

Save the active sprite to disk: to ``path`` if given (save-as; the document's filename follows it), else to its own filename — errors if the sprite is untitled and no ``path`` is given. Live: persists the edits sitting in the open editor. Headless: mutating tools already save to ``file`` on their own; use this with both arguments to write a copy of ``file`` under a new ``path`` (the source file on disk stays untouched).

Select the whole canvas.

Select every pixel matching ``color`` (composited, within ``tolerance`` 0-255 per channel) — a global magic wand. ``mode`` is ``replace``/``add``/``subtract``.

Select an ellipse inscribed in the given rectangle. ``mode`` is ``replace`` (default), ``add``, or ``subtract`` against the current selection.

Set a rectangular selection. Most meaningful on the live editor.

Live editor only: make one of the open documents active, found by exact filename or basename match (e.g. "turret.aseprite"). Returns which sprite matched and how. Subsequent tools operate on it.

Set the cel's opacity (0-255).

Move the cel's top-left origin to (x, y).

Convert the sprite between rgb | gray | indexed color modes. ``dithering`` applies only when converting to indexed: ordered | old | error-diffusion (default none). Returns the old and new mode. One undo step. Headless: pass ``file``.

Live editor only: set the viewport zoom (1.0 = 100%) and/or scroll — e.g. zoom to the region you're about to edit so the artist can watch.

Set frame ``number``'s duration in milliseconds.

Set every frame in [from_frame..to_frame] to ``ms`` milliseconds.

Set a layer's blend mode. One of: normal, multiply, screen, overlay, darken, lighten, color_dodge, color_burn, hard_light, soft_light, difference, exclusion, hue, saturation, color, luminosity, addition, subtract, divide.

Set a layer's opacity (0-255).

Show or hide a layer.

Configure the editor's onion-skin view: on/off, ghost counts each direction, and whether ghosting stays inside the current tag. A view preference — visually meaningful in the live editor. (For a rendered onion-skin image any backend can produce, use ``render_onion_composite``.)

Replace the whole palette with ``colors`` (list of #rrggbb/#rrggbbaa).

Set palette entry ``index`` to ``color`` (#rrggbb or #rrggbbaa).

Set a slice's 9-patch stretchable center rectangle (relative to the slice). One undo step. Headless: pass ``file``.

Set a slice's pivot point, in pixels relative to the slice's top-left. This pivot is exported into the Unity ``.meta`` by export_unity_slices. One undo step. Headless: pass ``file``.

Attach typed key/value metadata to the sprite (Aseprite's Properties system — stored in the .aseprite file itself). Values may be strings, numbers, or booleans. Useful for provenance ("generated_by", spec IDs) and pipeline state. One undo step.

Live editor only: set mirror-painting symmetry — ``mode`` is ``none``, ``horizontal`` (mirror across a vertical axis), ``vertical``, or ``both``; optionally place the axis lines. Affects the artist's subsequent brush strokes.

Set the timeline label color of the tag ``name`` (#rrggbb or #rrggbbaa). One undo step. Headless: pass ``file``.

Set the playback direction of the tag ``name``: forward | reverse | pingpong | pingpong_reverse. One undo step. Headless: pass ``file``.

Move the tag ``name`` to span frames ``from_frame``..``to_frame`` (1-based, inclusive; validated against the sprite's frame count). One undo step. Headless: pass ``file``.

Place tile references on a tilemap layer's cel. ``tiles`` is a list of {column, row, index} objects (0-based grid cells; index 0 erases to the empty tile). The cel is created or grown as needed, anchored at the sprite origin. ``frame`` is 1-based. One undo step. Headless: pass ``file``.

Sharpen the active cel (unsharp mask over a 3x3 neighborhood). ``strength`` 0.1-2.0. Only opaque pixels are considered, so sprite edges don't halo against transparency. One undo step.

Live editor only: pop a small dialog IN Aseprite with a message and up to 4 option buttons (e.g. approve/redo). Non-blocking — call ``get_dialog_choice`` to collect the artist's pick.

Append a motion-smear frame blending ``from_frame`` and ``to_frame``: overlapping pixels averaged, single-frame areas ghosted at half alpha — a pixel-content smear. RGB sprite only. Headless: pass ``file``.

Reorder palette swatches by ``luminance`` (default), ``hue``, or ``saturation``. Intended for RGB sprites' swatch organization — on an INDEXED sprite this changes which color each pixel shows (indices aren't remapped). One undo step.

Report backend health plus this server's version and whether a newer release exists. Live: whether Aseprite is connected + its version. Headless: the resolved Aseprite executable path and whether it exists.

Detach the ``watch_changes`` listener.

Fade a layer's cels across [from_frame..to_frame]: opacity interpolates from ``from_opacity`` to ``to_opacity`` (0-255) with the chosen easing. Every frame in the range needs a cel on the layer. One undo step.

Insert ``count`` in-between frames between ``from_frame`` and ``to_frame`` that interpolate the cel's position (a motion tween of the start cel's image). ``easing``: linear, ease_in, ease_out, or smoothstep. Headless: pass ``file``.

Undo the last edit on the active sprite (live editor).

Live editor only: start counting edits the ARTIST makes to the active sprite (via ``Sprite.events``). Poll with ``get_watched_changes`` — e.g. wait for the artist to finish touching up, then re-run the QA sweep.