Create a new Aseprite canvas with specified dimensions.

Args: width: Width of the canvas in pixels height: Height of the canvas in pixels filename: Name of the output file (default: canvas.aseprite)

Add a new layer to the Aseprite file.

Args: filename: Name of the Aseprite file to modify layer_name: Name of the new layer group: Optional group to place the new layer inside, by name or "group/subgroup" path (default: top level)

Add a new, empty group layer.

Combine with add_layer(group=...) / duplicate_layer(group=...) to build a grouped layer structure.

Args: filename: Name of the Aseprite file to modify group_name: Name of the new group parent_group: Optional existing group to nest the new group inside, by name or "group/subgroup" path (default: top level)

Add a new frame to the Aseprite file.

Args: filename: Name of the Aseprite file to modify

Set the active frame by index (1-based).

Args: filename: Name of the Aseprite file to modify frame_index: Frame index starting at 1

Set the duration of a frame in milliseconds.

Args: filename: Name of the Aseprite file to modify frame_index: Frame index starting at 1 duration_ms: Duration in milliseconds

Set the active layer by name.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to activate create_if_missing: Create layer if it does not exist

Draw pixels on the canvas with specified colors.

Args: filename: Name of the Aseprite file to modify pixels: List of pixel data, each containing: {"x": int, "y": int, "color": str} where color is a hex code like "#FF0000"

Draw a line on the canvas.

Args: filename: Name of the Aseprite file to modify x1: Starting x coordinate y1: Starting y coordinate x2: Ending x coordinate y2: Ending y coordinate color: Hex color code (default: "#000000") thickness: Line thickness in pixels (default: 1)

Draw a rectangle on the canvas.

Args: filename: Name of the Aseprite file to modify x: Top-left x coordinate y: Top-left y coordinate width: Width of the rectangle in pixels (must be > 0) height: Height of the rectangle in pixels (must be > 0) color: Hex color code (default: "#000000") fill: Whether to fill the rectangle (default: False)

Fill an area with color using the paint bucket tool.

Args: filename: Name of the Aseprite file to modify x: X coordinate to fill from y: Y coordinate to fill from color: Hex color code (default: "#000000")

Draw a circle on the canvas.

Args: filename: Name of the Aseprite file to modify center_x: X coordinate of circle center center_y: Y coordinate of circle center radius: Radius of the circle in pixels color: Hex color code (default: "#000000") fill: Whether to fill the circle (default: False)

Draw pixels on a specific layer/frame.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target frame_index: Frame index starting at 1 pixels: List of pixel data with x/y/color create_if_missing: Create cel if it does not exist

Draw a line on a specific layer/frame.

Draw a rectangle on a specific layer/frame.

Draw a circle on a specific layer/frame.

Fill an area on a specific layer/frame.

Draw a polygon on a specific layer/frame.

Draw a path using a polyline on a specific layer/frame.

Apply a linear gradient fill to a rectangle.

Draw an ellipse on a specific layer/frame.

Args: filename: Aseprite file to modify layer_name: Layer to draw on frame_index: Frame index starting at 1 center_x: Ellipse center x center_y: Ellipse center y radius_x: Horizontal radius in pixels radius_y: Vertical radius in pixels color: Hex color code (default "#000000") fill: Fill the ellipse instead of outlining it create_if_missing: Create the cel if it does not exist

Export the Aseprite file to another format.

Args: filename: Name of the Aseprite file to export output_filename: Name of the output file format: Output format (default: "png", can be "png", "gif", "jpg", etc.)

Copy a sprite to a new Aseprite file.

Args: filename: Name of the Aseprite file to copy output_filename: Name of the output .aseprite file overwrite: Whether to overwrite if output exists

Export a single frame as a PNG, optionally scaled up.

Use this for visual feedback while drawing: export at scale 8-10 and open the PNG to inspect the result, then keep iterating.

Args: filename: Aseprite file to export frame_index: Frame index starting at 1 output_filename: Output PNG path scale: Integer nearest-neighbor scale factor (default 1)

Export frames as a sprite sheet, optionally with a JSON data file.

Args: filename: Aseprite file to export output_filename: Output sheet image path (PNG) sheet_type: Layout: "horizontal", "vertical", "rows", "columns", or "packed" data_filename: Optional path for a JSON metadata file (json-array format) scale: Integer scale factor applied before packing (default 1) padding: Padding in pixels between frames (default 0) tag_name: Only include frames of this animation tag (default: all frames)

Export each layer as its own PNG file named .png.

Args: filename: Aseprite file to export output_directory: Directory for the per-layer PNGs (created if missing) include_hidden: Also export hidden layers (default False)

Export the frames of an animation tag as a GIF or PNG sequence.

Args: filename: Aseprite file to export tag_name: Animation tag to export output_filename: Output path; .gif gives an animation, .png a sequence scale: Integer scale factor (default 1)

Import an image file (PNG, etc.) into a layer of the sprite.

Useful for bringing in reference images or composing pre-made parts. The layer is created if it does not exist. Works best when the sprite is in RGB color mode.

Args: filename: Aseprite file to modify image_path: Image file to import layer_name: Layer to place the image on frame_index: Frame index starting at 1 (default 1) x: X position for the image's top-left corner (default 0) y: Y position for the image's top-left corner (default 0)

Add multiple frames to a sprite and optionally set their duration.

Args: filename: Name of the Aseprite file to modify count: Number of frames to add duration_ms: Optional duration for each new frame in milliseconds

Set the duration of all frames in milliseconds.

Args: filename: Name of the Aseprite file to modify duration_ms: Duration in milliseconds

Set layer visibility by name.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target visible: Whether the layer should be visible

Set layer opacity by name (0-255).

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target opacity: Opacity value 0-255

Return sprite info as JSON string (size, color mode, frame durations, layers, tags).

Args: filename: Name of the Aseprite file to inspect

Duplicate a frame range and append copies to the end.

Args: filename: Name of the Aseprite file to modify start_frame: Starting frame index (1-based) end_frame: Ending frame index (1-based, inclusive) times: Number of times to append the range (default: 1)

Set a cel's position in a specific layer and frame.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target frame_index: Frame index starting at 1 x: X position in pixels y: Y position in pixels create_if_missing: Create the cel if it does not exist source_frame_index: Optional frame to copy the cel image from

Tween cel positions linearly across a frame range.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target start_frame: Starting frame index (1-based) end_frame: Ending frame index (1-based, inclusive) start_x: Starting X position in pixels start_y: Starting Y position in pixels end_x: Ending X position in pixels end_y: Ending Y position in pixels create_missing_cels: Create missing cels during tween source_frame_index: Optional frame to copy the cel image from

Offset cel positions by a delta across a frame range.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target start_frame: Starting frame index (1-based) end_frame: Ending frame index (1-based, inclusive) dx: X delta in pixels dy: Y delta in pixels

Create an empty cel on a layer/frame.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target frame_index: Frame index starting at 1 x: X position in pixels y: Y position in pixels

Delete a cel on a layer/frame.

Copy a cel from one frame to another.

Copy all cels from a source frame to a target frame (or append).

Copy all layers from a source frame to a range of frames.

Args: filename: Name of the Aseprite file to modify source_frame: Frame index to copy from (1-based) start_frame: Start frame index (1-based) end_frame: End frame index (1-based, inclusive) overwrite: Whether to overwrite existing cels (default: True)

Create or update an animation tag on the sprite.

direction: forward | reverse | pingpong | pingpong_reverse

Configure onion skin settings for Aseprite.

Copy cels from a source frame to a range of frames for specific layers.

Args: filename: Name of the Aseprite file to modify layer_names: List of layer names to copy source_frame: Frame index to copy from (1-based) start_frame: Start frame index (1-based) end_frame: End frame index (1-based, inclusive) replace: Whether to overwrite existing cels (default: True)

Tween cel positions with easing across a frame range.

Oscillate cel positions across a frame range using a sine wave.

Tween cel opacity with easing across a frame range.

Tween cel scale with easing across a frame range.

Delete a frame by index.

Args: filename: Aseprite file to modify frame_index: Frame index starting at 1

Delete an animation tag by name.

Args: filename: Aseprite file to modify name: Tag name to delete

Set the opacity of a single cel (0-255).

Args: filename: Aseprite file to modify layer_name: Layer containing the cel frame_index: Frame index starting at 1 opacity: Opacity 0 (transparent) to 255 (opaque)

Start a simple HTTP server to preview exported sprites.

Args: directory: Directory to serve port: Port to bind (default 8000)

Stop the preview HTTP server for a given port.

Args: port: Port to stop (default 8000)

Get the active sprite palette as a JSON array of hex colors.

Set the active sprite palette using a list of hex colors.

Remap colors in a layer across a frame range using explicit mappings.

List the built-in retro palette presets with their colors.

Returns: JSON object mapping preset name to its list of hex colors.

Set the sprite palette to a built-in retro preset.

This only sets the palette; existing pixels keep their colors. Use quantize_to_palette afterwards to snap pixels to the new palette.

Args: filename: Aseprite file to modify preset: One of: gameboy, monochrome, grayscale_4, cga, pico8, c64, dawnbringer16, dawnbringer32

Generate a shading ramp (dark to light) from a base color.

Produces the standard pixel-art shading technique of hue-shifting: shadows lean cooler (hue shifted one way), highlights lean warmer. Use the returned colors for shading instead of plain darker/lighter versions of the same hue.

Args: base_color: Hex color the ramp is built around, e.g. "#D04648" steps: Number of colors in the ramp, 2-16 (default 5) hue_shift_degrees: Total hue rotation across the ramp (default 20) lightness_range: Total lightness span across the ramp, 0-1 (default 0.5)

Returns: JSON array of hex colors ordered darkest to lightest.

Snap every pixel to the nearest color in the sprite's palette.

Walks the chosen cels and replaces each opaque pixel with the closest palette color (RGB distance). Run after apply_palette_preset or set_palette to make existing art conform to the palette.

Args: filename: Aseprite file to modify layer_name: Layer to quantize (empty = all top-level layers) start_frame: First frame to process (default 1) end_frame: Last frame to process (default 0 = last frame)

Convert the sprite's color mode.

Args: filename: Aseprite file to modify mode: "rgb", "grayscale", or "indexed"

Copy layers by name from a source sprite to a target sprite.

Args: source_filename: Source .aseprite file target_filename: Target .aseprite file layer_names: List of layer names to copy replace: Overwrite existing cels in target layers create_missing_frames: Add frames to target if needed

Return a concise English guide for optimized animation workflows.

Ensure cels exist for layers across a frame range.

Validate presence of layers and cels across a frame range.

Returns JSON with missing layers and missing cels.

Audit animation frames for overlaps and out-of-range layer activity.

overlap_pairs format: ["layerA,layerB", "layerC:layerD"] layer_frame_ranges format: ["layer:1-8,17-24", "clouds:1-12"] Returns JSON for AI consumption (summary, overlaps, out_of_range, optional cels).

Normalize animation consistency and optionally apply fixes.

layer_frame_ranges format: ["layer:1-8,17-24", "clouds:1-12"] out_of_range_action: "set_opacity_zero", "delete_cels", "none" ignore_full_canvas_overlaps: skip overlap checks when a cel is full canvas Returns JSON for AI consumption (summary, layer_stats, alerts, overlaps).

Render a frame with neighboring frames as translucent onion-skin ghosts.

Produces a PNG of the given frame composited over ghosted copies of the surrounding frames — the batch-mode equivalent of Aseprite's onion skinning. Essential for checking motion continuity while animating: export it, open the PNG, and verify the in-between positions line up.

Args: filename: Aseprite file to read frame_index: Frame to render, starting at 1 output_filename: Output PNG path before: Number of previous frames to ghost (default 1) after: Number of following frames to ghost (default 1) scale: Integer nearest-neighbor scale factor (default 4) ghost_opacity: Opacity of ghost frames, 0-255 (default 100)

Compare two frames and report how much they differ.

Flattens the sprite (non-destructively) and diffs the two frames pixel by pixel. Use while animating to confirm a frame actually changed, or that it did not change too much.

Args: filename: Aseprite file to read frame_a: First frame index, starting at 1 frame_b: Second frame index, starting at 1

Returns: JSON with changed pixel count, total pixels, percent changed, and the bounding box of the changed region.

Report the colors used in a frame and how often each appears.

Flattens the sprite (non-destructively) and histograms the frame. Use to check palette discipline: too many near-duplicate colors is a common pixel-art mistake.

Args: filename: Aseprite file to read frame_index: Frame to analyze, starting at 1 (default 1) top: How many of the most-used colors to list (default 16)

Returns: JSON with unique color count, opaque pixel count, and the top colors with usage counts.

Read the RGBA color of a single pixel.

Args: filename: Aseprite file to read x: X coordinate y: Y coordinate layer_name: Layer to read from (uses active layer when empty) frame_index: Frame index starting at 1

Read all pixel colors in a rectangular region.

Args: filename: Aseprite file to read x: Top-left x coordinate y: Top-left y coordinate width: Width of the region height: Height of the region layer_name: Layer to read from (uses active layer when empty) frame_index: Frame index starting at 1

Returns: JSON array of {x, y, hex, r, g, b, a} objects

Read the RGBA colour VISIBLE at a pixel (flattened composite of all layers).

Unlike get_pixel_color (which reads a single cel), this composites every visible layer — "what the player actually sees" — by flattening a throwaway clone. Essential for value/CVD QA on grouped/multi-layer scenes.

Args: filename: Aseprite file to read x: X coordinate (sprite-global) y: Y coordinate (sprite-global) frame_index: Frame index starting at 1

Read VISIBLE RGBA over a rectangle (flattened composite of all layers).

The rectangular counterpart of get_composite_pixel — reads the composited pixels every visible layer produces, not a single cel.

Args: filename: Aseprite file to read x: Top-left x (sprite-global) y: Top-left y (sprite-global) width: Region width height: Region height frame_index: Frame index starting at 1

Returns: JSON array of {x, y, hex, r, g, b, a} objects

Flip a layer's image horizontally or vertically.

Args: filename: Aseprite file to modify layer_name: Layer name to flip frame_index: Frame index starting at 1 direction: "horizontal" or "vertical"

Rotate a layer's image 90, 180, or 270 degrees clockwise.

Args: filename: Aseprite file to modify layer_name: Layer name to rotate frame_index: Frame index starting at 1 angle: Rotation angle: 90, 180, or 270 (clockwise)

Scale the canvas and all its content to new dimensions.

Args: filename: Aseprite file to modify width: New canvas width in pixels height: New canvas height in pixels

Crop the canvas to the given rectangle, discarding content outside it.

Args: filename: Aseprite file to modify x: Left edge of the crop area y: Top edge of the crop area width: Width of the crop area height: Height of the crop area

Delete a layer by name.

Args: filename: Aseprite file to modify layer_name: Name of the layer to delete

Rename a layer.

Args: filename: Aseprite file to modify layer_name: Current layer name new_name: New layer name

Duplicate a layer with all its cels across every frame.

The copy inherits the source's opacity and blend mode. By default it is placed directly above the source layer; pass group to place it inside a group instead.

Args: filename: Aseprite file to modify layer_name: Layer to duplicate, by name or "group/subgroup/layer" path new_name: Name for the copy (default: " copy") group: Optional group to place the copy inside, by name or "group/subgroup" path (default: directly above the source)

Move a layer to a new position in the layer stack.

Args: filename: Aseprite file to modify layer_name: Layer to move position: Target stack position, 1-based where 1 is the bottom layer

Set a layer's blend mode.

Args: filename: Aseprite file to modify layer_name: Layer to modify mode: One of: normal, darken, multiply, color_burn, lighten, screen, color_dodge, addition, overlay, soft_light, hard_light, difference, exclusion, subtract, divide, hue, saturation, color, luminosity

Merge a layer into the layer directly below it.

Args: filename: Aseprite file to modify layer_name: Layer to merge down (must not be the bottom layer)

Flatten all layers into a single layer.

Args: filename: Aseprite file to modify

Cut a rectangular region of pixels and paste it at a new position.

Coordinates are sprite-global. The source area is left transparent. Pixels moved outside the canvas are discarded. Fully transparent source pixels do not overwrite destination pixels.

Args: filename: Aseprite file to modify layer_name: Layer to operate on frame_index: Frame index starting at 1 x: Left edge of the source region y: Top edge of the source region width: Region width height: Region height dest_x: New left edge for the region dest_y: New top edge for the region

Copy a rectangular region of pixels to another position, layer, or frame.

Coordinates are sprite-global. Fully transparent source pixels do not overwrite destination pixels. The destination cel is created when missing.

Args: filename: Aseprite file to modify layer_name: Source layer frame_index: Source frame index starting at 1 x: Left edge of the source region y: Top edge of the source region width: Region width height: Region height dest_x: Left edge of the destination dest_y: Top edge of the destination target_layer_name: Destination layer (default: same as source) target_frame_index: Destination frame (default: same as source)

Erase (make transparent) a rectangular region of pixels.

Coordinates are sprite-global.

Args: filename: Aseprite file to modify layer_name: Layer to operate on frame_index: Frame index starting at 1 x: Left edge of the region y: Top edge of the region width: Region width height: Region height

Make all pixels of a given color transparent (like a magic eraser).

Args: filename: Aseprite file to modify layer_name: Layer to operate on frame_index: Frame index starting at 1 color: Hex color to erase, e.g. "#FF00FF" tolerance: Per-channel tolerance 0-255 (default 0 = exact match)

Add a 1px outline around all opaque pixels of a cel.

Transparent pixels adjacent to opaque pixels are filled with the outline color. Great for making sprites read clearly against any background.

Args: filename: Aseprite file to modify layer_name: Layer to outline frame_index: Frame index starting at 1 color: Outline hex color (default black) include_diagonals: Also outline diagonal neighbors for a thicker, rounded outline (default False)

Replace one color with another in a cel, preserving alpha.

Args: filename: Aseprite file to modify layer_name: Layer to operate on frame_index: Frame index starting at 1 from_color: Hex color to replace, e.g. "#FF0000" to_color: Replacement hex color tolerance: Per-channel tolerance 0-255 (default 0 = exact match)

Shift hue, saturation, and lightness of all opaque pixels in a cel.

Useful for creating palette-swapped variants and shading: e.g. darken a duplicated layer for shadows or hue-shift toward blue for night scenes.

Args: filename: Aseprite file to modify layer_name: Layer to adjust frame_index: Frame index starting at 1 hue_shift: Degrees to rotate hue, -360 to 360 saturation_shift: Saturation delta, -100 to 100 lightness_shift: Lightness delta, -100 to 100

Fill a rectangle with a two-color gradient using Bayer 4x4 ordered dithering.

This is the classic pixel-art way to blend two colors without introducing new intermediate colors. The gradient runs from color_start (top/left) to color_end (bottom/right).

Args: filename: Aseprite file to modify layer_name: Layer to draw on frame_index: Frame index starting at 1 x: Left edge of the rectangle y: Top edge of the rectangle width: Rectangle width height: Rectangle height color_start: Hex color at the start of the gradient color_end: Hex color at the end of the gradient horizontal: Run the gradient left-to-right instead of top-to-bottom create_if_missing: Create the cel if it does not exist

Fill a rectangle with a uniform Bayer-dithered mix of two colors.

density controls the ratio: 0.0 = all color_a, 0.5 = checkerboard, 1.0 = all color_b. Useful for textures (stone, grass) and flat mid-tones between two palette colors.

Args: filename: Aseprite file to modify layer_name: Layer to draw on frame_index: Frame index starting at 1 x: Left edge of the rectangle y: Top edge of the rectangle width: Rectangle width height: Rectangle height color_a: Base hex color color_b: Mixed-in hex color density: Fraction of color_b, 0.0-1.0 (default 0.5) create_if_missing: Create the cel if it does not exist

Create a named slice (a rectangular region usable by game engines).

Args: filename: Aseprite file to modify name: Slice name x: Left edge of the slice y: Top edge of the slice width: Slice width height: Slice height

Set a slice's 9-patch center rectangle (relative to the slice origin).

The center defines the stretchable region for 9-patch scaling in game engines.

Args: filename: Aseprite file to modify name: Slice name x: Center-rect left edge, relative to the slice y: Center-rect top edge, relative to the slice width: Center-rect width height: Center-rect height

Set a slice's pivot point (relative to the slice origin).

Args: filename: Aseprite file to modify name: Slice name x: Pivot x, relative to the slice y: Pivot y, relative to the slice

List all slices with their bounds, 9-patch centers, and pivots.

Returns: JSON array of {name, x, y, width, height, center?, pivot?}.

Delete a slice by name.

Args: filename: Aseprite file to modify name: Slice name to delete