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.

Args: filename (str): The path to the Aseprite file. layer_name (str): The name of the layer to draw on. frame_index (int): The index of the frame to draw on. x1 (int): The x coordinate of the first point of the line. y1 (int): The y coordinate of the first point of the line. x2 (int): The x coordinate of the second point of the line. y2 (int): The y coordinate of the second point of the line. color (str, optional): The color to draw the line with. Defaults to "#000000". thickness (int, optional): The thickness of the line. Defaults to 1. create_if_missing (bool, optional): Whether to create the layer if it doesn't exist. Defaults to True.

Draw a rectangle on a specific layer/frame.

Args: filename (str): The path to the Aseprite file. layer_name (str): The name of the layer to draw on. frame_index (int): The index of the frame to draw on. x (int): The x coordinate of the top-left corner of the rectangle. y (int): The y coordinate of the top-left corner of the rectangle. width (int): The width of the rectangle. height (int): The height of the rectangle. color (str, optional): The color to draw the rectangle with. Defaults to "#000000". fill (bool, optional): Whether to fill the rectangle. Defaults to False. create_if_missing (bool, optional): Whether to create the layer if it doesn't exist. Defaults to True.

Draw a circle on a specific layer/frame.

Args: filename (str): The path to the Aseprite file. layer_name (str): The name of the layer to draw on. frame_index (int): The index of the frame to draw on. center_x (int): The x coordinate of the center of the circle. center_y (int): The y coordinate of the center of the circle. radius (int): The radius of the circle. color (str, optional): The color to draw the circle with. Defaults to "#000000". fill (bool, optional): Whether to fill the circle. Defaults to False. create_if_missing (bool, optional): Whether to create the layer if it doesn't exist. Defaults to True.

Fill an area on a specific layer/frame.

Args: filename (str): The path to the Aseprite file. layer_name (str): The name of the layer to draw on. frame_index (int): The index of the frame to draw on. x (int): The x coordinate of the point to start filling from. y (int): The y coordinate of the point to start filling from. color (str, optional): The color to fill the area with. Defaults to "#000000". create_if_missing (bool, optional): Whether to create the layer if it doesn't exist. Defaults to True.

Draw a polygon on a specific layer/frame.

Args: filename (str): The path to the Aseprite file. layer_name (str): The name of the layer to draw on. frame_index (int): The index of the frame to draw on. points (List[Dict[str, int]]): The list of points to draw the polygon. color (str, optional): The color to draw the polygon with. Defaults to "#000000". fill (bool, optional): Whether to fill the polygon. Defaults to False. create_if_missing (bool, optional): Whether to create the layer if it doesn't exist. Defaults to True.

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

Args: filename (str): The path to the Aseprite file. layer_name (str): The name of the layer to draw on. frame_index (int): The index of the frame to draw on. points (List[Dict[str, int]]): The points to draw the path with. color (str, optional): The color to draw the path with. Defaults to "#000000". thickness (int, optional): The thickness of the path. Defaults to 1. create_if_missing (bool, optional): Whether to create the layer if it doesn't exist. Defaults to True.

Apply a linear gradient fill to a rectangle.

Args: filename (str): The path to the Aseprite file. layer_name (str): The name of the layer to draw on. frame_index (int): The index of the frame to draw on. x (int): The x coordinate of the rectangle to draw on. y (int): The y coordinate of the rectangle to draw on. width (int): The width of the rectangle to draw on. height (int): The height of the rectangle to draw on. color_start (str): The start color of the gradient. color_end (str): The end color of the gradient. horizontal (bool, optional): Whether to draw the gradient horizontally. Defaults to True. create_if_missing (bool, optional): Whether to create the layer if it doesn't exist. Defaults to True.

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 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) data_format: JSON format for the data file: "json-array" (default) or "json-hash" list_tags: Include animation tag metadata in the JSON data file (default: False)

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.

Args: filename (str): The path to the Aseprite file. layer_name (str): The name of the layer to remap colors in. start_frame (int): The start frame index to remap colors in. end_frame (int): The end frame index to remap colors in. mappings (List[dict]): The color mappings to use. create_missing_cels (bool, optional): Whether to create missing cels. Defaults to False. source_frame_index (int | None, optional): The source frame index to use for remapping. Defaults to None.

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

Create a tilemap layer with its own tileset.

Sets the sprite grid to the tile size and adds a tilemap layer. Tile index 0 is always the empty tile; add real tiles with draw_on_tile (which creates tiles on demand).

Args: filename: Aseprite file to modify layer_name: Name for the new tilemap layer tile_width: Tile width in pixels tile_height: Tile height in pixels

Draw pixels onto a tile in a tilemap layer's tileset.

Coordinates are tile-local (0,0 = tile top-left). When tile_index equals the current tile count, a new tile is appended automatically.

Args: filename: Aseprite file to modify layer_name: Tilemap layer whose tileset to edit tile_index: Tile to draw on (1 = first real tile; 0 is reserved for the empty tile and cannot be drawn on) pixels: List of {"x": int, "y": int, "color": "#RRGGBB"}

Place tiles on a tilemap layer by grid position.

Args: filename: Aseprite file to modify layer_name: Tilemap layer to edit frame_index: Frame index starting at 1 tiles: List of {"col": int, "row": int, "tile_index": int} (col/row are grid coordinates; tile_index 0 clears the cell)

Read which tile is placed at a grid position.

Args: filename: Aseprite file to read layer_name: Tilemap layer to read frame_index: Frame index starting at 1 col: Grid column (0-based) row: Grid row (0-based)

Returns: JSON with {col, row, tile_index} (0 = empty).

Get tilemap layer info: tile size, tile count, and map dimensions.

Args: filename: Aseprite file to read layer_name: Tilemap layer to inspect

Returns: JSON with tile_width, tile_height, tile_count (real tiles, excluding the empty tile 0), map_cols, map_rows.

Execute arbitrary Aseprite Lua code in batch mode (escape hatch).

Use this when no dedicated tool covers what you need. The full API is documented at https://www.aseprite.org/api/. Anything the curated tools do can also be done here — they are Lua underneath.

Essentials for batch-mode scripts:

• When filename is given, it is opened first and available as app.activeSprite.

• Changes are NOT saved automatically; call spr:saveAs(spr.filename) at the end if you modified the sprite.

• print() is the only way to return data; a clean exit does not mean your logic succeeded, so print what you need to verify.

• Coordinates on cel images are cel-local: offset sprite-global coordinates by cel.position before getPixel/putPixel.

WARNING: this executes unrestricted code (including io/os access) on the host running Aseprite. Only pass scripts you trust.

Args: script: Lua source code to execute filename: Optional Aseprite file to open before running

List fonts that draw_text can use.

Covers bitmap sprite-sheet fonts and .ttf/.otf files installed under ~/.aseprite-mcp/fonts, plus TrueType fonts found in the system font directories. Bitmap fonts are the right choice for pixel art: their glyphs are already pixels and size scales them by whole numbers.

Measure text without drawing it.

Use this to size a panel or centre a label in one shot instead of guessing and re-rendering.

Args: text: The string to measure font: Font name from list_text_fonts, or a path to a .ttf/.otf or bitmap font directory size: Pixel size for TrueType fonts; integer scale factor for bitmap fonts (default 1) letter_spacing: Extra pixels between glyphs (default 0) bold: Faux-bold passes; each grows strokes by 1px (default 0) antialias: Keep greyscale edges instead of hard pixels (default False)

Returns: width, height, advance_width, and the ink extents above/below the baseline.

Draw text onto a sprite.

Glyphs are rasterised outside Aseprite and composited in, because the Lua API has no text drawing of its own.

Args: filename: Aseprite file to modify text: String to draw x: X coordinate of the anchor point y: Y coordinate of the anchor point font: Font name from list_text_fonts, or a path to a .ttf/.otf or a bitmap font directory size: Pixel size for TrueType fonts; integer scale factor for bitmap fonts (default 1) color: Text colour, #RRGGBB or #RRGGBBAA (default white) layer_name: Layer to draw on; the active/first layer if omitted frame_index: Frame index starting at 1 (default 1) anchor: Which point of the text (x, y) refers to - one of topleft, top, topright, left, center, right, bottomleft, bottom, bottomright, baselineleft, baseline, baselineright (default topleft) letter_spacing: Extra pixels between glyphs (default 0) bold: Faux-bold passes; each grows strokes by 1px (default 0) outline_color: If set, draw a 1px outline in this colour outline_width: Outline thickness in pixels (default 1) outline_diagonal: Include diagonal neighbours in the outline, giving a rounded corner; False gives a boxier 4-way outline (default True) shadow_color: If set, draw a drop shadow in this colour shadow_dx: Shadow X offset (default 1) shadow_dy: Shadow Y offset (default 1) antialias: Keep greyscale edges instead of hard pixels (default False) create_if_missing: Create the layer/cel if absent (default True)

Native Aseprite Outline around opaque pixels (app.command.Outline).

Higher quality than the 1px hand-rolled outline_cel: inside/outside placement + a circle/square brush. Works best on a full-canvas cel.

Args: filename: Aseprite file to modify layer_name: layer to outline (empty = active layer) frame_index: 1-based frame color: outline colour as #RRGGBB place: "outside" or "inside" matrix: "circle" or "square"

Native Hue/Saturation/Lightness filter (engine-quality vs adjust_hsl).

Args: filename: Aseprite file to modify layer_name: layer to adjust (empty = active layer) frame_index: 1-based frame hue: -180..180 (degrees) saturation: -100..100 lightness: -100..100 x, y, width, height: optional region (width>0 & height>0 to scope)

Native Brightness/Contrast filter (app.command.BrightnessContrast).

Args: filename: Aseprite file to modify layer_name: layer to adjust (empty = active layer) frame_index: 1-based frame brightness: -100..100 contrast: -100..100 x, y, width, height: optional region (width>0 & height>0 to scope)

Native colour inversion (app.command.InvertColor).

Args: filename: Aseprite file to modify layer_name: layer to invert (empty = active layer) frame_index: 1-based frame x, y, width, height: optional region (width>0 & height>0 to scope)

Native convolution filter (blur / sharpen / edge / emboss …).

Args: filename: Aseprite file to modify matrix: a built-in matrix name (see list_convolution_matrices), e.g. "blur-3x3", "sharpen-3x3", "edges-find", "misc-emboss" layer_name: layer to filter (empty = active layer) frame_index: 1-based frame x, y, width, height: optional region (width>0 & height>0 to scope)

List the built-in convolution-matrix names usable with apply_convolution.

Returns: JSON array of matrix resource names.

Build an OPTIMAL palette from the sprite via native ColorQuantization.

True palette extraction (vs the nearest-snap quantize_to_palette): writes the resulting palette to the sprite and returns it. NOTE: mutates the sprite's palette. Sprite must be in RGB mode.

Args: filename: Aseprite file to modify max_colors: palette size cap, 1..256 (fewer if the art has fewer) with_alpha: include alpha when quantizing

Returns: JSON {colors: [#RRGGBB, ...], count}