Metadata-Version: 2.4
Name: aseprite-automation
Version: 0.5.0
Summary: Aseprite automation for AI agents. Simple. Stable. Congruent. Create, edit, verify, and export pixel art and sprite animations via CLI, Agent Skill, or MCP server.
Keywords: aseprite,pixel-art,sprite-animation,sprite-sheet,tileset,game-assets,ai-agent,ai-game-development,cli,agent-skill,mcp,mcp-server,model-context-protocol,asset-pipeline
Author: aigengame
License-Expression: MIT AND CC0-1.0
License-File: LICENSE
License-File: LICENSES/CC0-1.0.txt
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Requires-Dist: pillow>=12,<13
Requires-Dist: pydantic>=2.11,<3
Requires-Dist: typer>=0.16,<1
Requires-Dist: mcp>=2.3,<3 ; extra == 'mcp'
Requires-Dist: jsonschema>=4,<5 ; extra == 'mcp'
Requires-Python: >=3.13
Project-URL: Repository, https://github.com/aigengame/aseprite-automation
Project-URL: Issues, https://github.com/aigengame/aseprite-automation/issues
Project-URL: Changelog, https://github.com/aigengame/aseprite-automation/blob/main/CHANGELOG.md
Provides-Extra: mcp
Description-Content-Type: text/markdown

# SPA — Aseprite Automation for AI Agents

**Simple. Stable. Congruent.**

![SPA: Sun Wukong relaxes in a spa while memories of Havoc in Heaven become pixel art layers and animation frames](https://raw.githubusercontent.com/aigengame/aseprite-automation/2eec52707c2de90127e47f0a8a7d384967bfdd82/docs/assets/hero-wukong-spa-heaven.png)

**Create, edit, verify, and export pixel art and sprite animations with AI agents.**

SPA brings Aseprite to your agent workflows through a CLI, Agent Skill, or MCP server.
Keep editable Aseprite source files (`.aseprite`) alongside PNGs,
GIFs, sprite sheets, and tile assets for your game.

[![PR CI](https://github.com/aigengame/aseprite-automation/actions/workflows/ci.yml/badge.svg?event=pull_request)](https://github.com/aigengame/aseprite-automation/actions/workflows/ci.yml?query=event%3Apull_request)
[![PyPI version](https://img.shields.io/pypi/v/aseprite-automation.svg)](https://pypi.org/project/aseprite-automation/)
[![Python 3.13+](https://img.shields.io/badge/Python-3.13%2B-blue)](https://www.python.org/)
[![CLI · Agent Skill · MCP](https://img.shields.io/badge/access-CLI%20%C2%B7%20Agent%20Skill%20%C2%B7%20MCP-7057ff)](#choose-your-integration)

**Read this in:** English · [简体中文](https://github.com/aigengame/aseprite-automation/blob/main/docs/README.zh-CN.md)

[Quick start](#quick-start) · [Usage guide](https://github.com/aigengame/aseprite-automation/blob/main/docs/usage.md) ·
[Examples](#examples) · [MCP setup](https://github.com/aigengame/aseprite-automation/blob/main/docs/mcp.md)

## TL;DR

Just tell your AI agent:

> Install the SPA CLI with `uv tool install --python 3.13 aseprite-automation`,
> and install its Agent Skill with
> `npx skills add aigengame/aseprite-automation --skill spa -g`.
> Then read the skill, follow it to configure SPA for my Aseprite installation,
> and verify the setup with `spa info`.

A separate Aseprite installation is required. See [Installation](#installation)
and [Agent Skill](#agent-skill) for prerequisites and setup options. You can also
use the CLI directly or connect an [MCP client](#mcp).

## Contents

- [Why SPA?](#why-spa)
- [What can you build?](#what-can-you-build)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Choose your integration](#choose-your-integration)
- [Examples](#examples)
- [Documentation and support](#documentation-and-support)
- [Contributing](#contributing)

## Why SPA?

**Simple to use. Stable in practice. Congruent with your creative vision.**

- **Keep your assets editable.** Work with native Aseprite layers, frames, cels, and
  tags. Retain the source for later revisions alongside exports for your game.
- **Control the animation.** Set frame timing, position, opacity, and motion on
  existing cels. Use explicit requests to make repeatable workflow steps.
- **Bring your own artwork.** Prepare external PNGs with palette, transparency,
  size, and anchor choices, then import compatible images for animation.
- **Check what changed.** Inspect saved assets, validate expected facts, compare
  frames, and preview results. Structured results help agents handle failures.
- **Choose your agent connection.** Use shell commands, reusable Skill guidance,
  or an Aseprite MCP server with the same underlying operations.

SPA runs Aseprite in batch mode. You do not need to drive the editor UI for supported
operations. Art direction, visual review, and downstream game integration remain
part of your workflow.

## What can you build?

| Your goal | SPA can help with | Start with |
| --- | --- | --- |
| Create reusable pixel art assets | Sprites, layers, frames, cels, tags, slices, and editable native files | `sprite`, `layer`, `frame`, `cel`, `tag`, `slice` |
| Prepare and edit artwork | PNG preparation and import, image transforms, selections, native paint and filters | `raster`, `image`, `selection`, `paint`, `filter` |
| Animate and inspect motion | Frame timing, cel placement, motion curves, animation checks, frame comparison, previews | `motion`, `animation`, `frame`, `cel` |
| Work with colors and tiles | Palettes, color modes and profiles, keyed tiles, tilesets, and tilemap regions | `palette`, `sprite`, `tileset`, `tilemap` |
| Deliver assets to a game | PNG images, GIFs, PNG sequences, sprite sheets with JSON, and tileset/map exports | `export` |
| Automate a sequence of edits | Supported edits to one sprite, checked before one final save | `plan check`, `plan run` |

Use `spa --help` and each command's `--schema` for your installation.
`spa info` checks your Aseprite runtime; `spa schema` also reports unavailable
native capabilities.

## Installation

You need **Python 3.13+**, [uv](https://docs.astral.sh/uv/getting-started/installation/),
and a separate [Aseprite installation](https://www.aseprite.org/). SPA does not bundle
the Aseprite executable.

The [PyPI package](https://pypi.org/project/aseprite-automation/) is
**`aseprite-automation`**; the command is **`spa`**.

### Install from PyPI

```sh
uv tool install --python 3.13 aseprite-automation
spa version
```

Update an existing installation with `uv tool upgrade aseprite-automation`.
For MCP, install the optional extra:
`uv tool install --python 3.13 'aseprite-automation[mcp]'`.
If `spa` is not on `PATH`, run `uv tool update-shell` and open a new shell.

You can also install a wheel from a
[GitHub Release](https://github.com/aigengame/aseprite-automation/releases) with
`uv tool install --python 3.13 /absolute/path/to/the-wheel.whl`.

### Install the current development version

Install [Git LFS](https://git-lfs.com/), then run:

```sh
git clone --branch dev https://github.com/aigengame/aseprite-automation.git
cd aseprite-automation
git lfs install
git lfs pull
uv tool install --python 3.13 .
spa version
```

Git LFS retrieves the native probe fixtures and example assets. The development
branch may include capabilities that are not in the latest release.
For source development, use `uv sync` and `uv run spa`; see the
[usage guide](https://github.com/aigengame/aseprite-automation/blob/main/docs/usage.md).

## Quick start

Point SPA at your Aseprite executable. On macOS, use the binary inside
`Aseprite.app/Contents/MacOS/`, rather than the `.app` directory.

```sh
export SPA_ASEPRITE_EXECUTABLE="/absolute/path/to/aseprite"
spa info
```

Use a new working directory for these commands. They create a 32×32 sprite, draw a
purple disk on a transparent layer, export a PNG, and check the saved dimensions.
Existing destinations are refused.

**1. Create an editable source.**

```sh
spa sprite create --input-json '{
  "target_sprite_file":"canvas.aseprite","overwrite":false,
  "width":32,"height":32,"color_mode":"rgb",
  "initial_layer":{"kind":"transparent"}
}'
```

**2. Draw on the first layer and frame.**

```sh
spa paint ellipse --input-json '{
  "source_sprite_file":"canvas.aseprite","target_sprite_file":"orb.aseprite",
  "in_place":false,"overwrite":false,
  "target":{"layer":{"layer_path":[1]},"frame_number":1},
  "coordinate_space":"image-pixel",
  "bounds":{"x":8,"y":8,"width":16,"height":16},"style":"filled",
  "brush":{"kind":"circle","size":1},
  "color":{"kind":"rgba","red":166,"green":104,"blue":255,"alpha":255},
  "ink":"simple","opacity":255
}'
```

**3. Export the image.**

```sh
spa export image --input-json '{
  "source_sprite_file":"orb.aseprite",
  "destination":{"path":"orb.png","if_exists":"fail"},"frame_number":1,
  "export_image_area":{"kind":"canvas"},"layer_composition":{"mode":"visible"},
  "composition_color_mode":"rgb","color_mode":"preserve",
  "color_profile":"preserve","transparency":"preserve"
}'
```

**4. Check the saved source and view `orb.png`.**

```sh
spa sprite validate --input-json '{
  "sprite_file":"orb.aseprite",
  "expected":{"width":32,"height":32,"color_mode":"rgb","frame_count":1}
}'
```

Commands return JSON by default; add `--human` for readable output. For validation,
check `valid`, `checks`, and `findings`: `status: success` means the check ran.
Visual quality still needs a look at the exported image.

Continue with the [usage guide](https://github.com/aigengame/aseprite-automation/blob/main/docs/usage.md)
for animation, import, paint, color, tile, and export recipes. Use `--help` and
`--schema` to discover fields without guessing.

## Choose your integration

| Access path | Best for | Entry point |
| --- | --- | --- |
| **CLI** | Agents that run shell commands, scripts, and asset pipelines | `spa --help` |
| **Agent Skill** | Agents that need reusable guidance for the create–verify–export loop | [SPA Skill](https://github.com/aigengame/aseprite-automation/blob/main/skills/spa/SKILL.md) |
| **MCP** | Clients that discover and call tools, with exported PNGs shown as image content | [MCP setup](https://github.com/aigengame/aseprite-automation/blob/main/docs/mcp.md) |

### Agent Skill

From your consuming project, install the Skill with the
[Skills CLI](https://github.com/vercel-labs/skills). Node/npm is required.

```sh
npx skills add aigengame/aseprite-automation --skill spa
```

Add `-g` to install for your user across projects, as in the TL;DR above.

For a local development checkout, use:

```sh
npx skills add /absolute/path/to/aseprite-automation --skill spa
```

The Skills CLI manages installation and updates. The Skill reads the installed
SPA help and schemas. It does not install SPA or Aseprite and does not add a
separate compatibility or version manager.

### MCP

Install the optional `mcp` extra as shown in [Installation](#installation), then
configure your client to launch the installed `spa-mcp` executable. Follow
[MCP setup](https://github.com/aigengame/aseprite-automation/blob/main/docs/mcp.md) for the stdio configuration.

Normal CLI use does not need the MCP extra. The MCP server uses the same operations
and results; it does not keep an active sprite between calls.

## Examples

[![Animated pixel art wizard casting a spell, exported through SPA](https://raw.githubusercontent.com/aigengame/aseprite-automation/1ca5e1f4cd7587cf351ddcd1a16122f47d3f8ba0/examples/wizard_cast_v2/evidence/scene-loop.webp)](https://github.com/aigengame/aseprite-automation/blob/main/examples/wizard_cast_v2/README.md)

*Moonlit Spell Practice v2: imagegen artwork, Python motion assembly, and SPA animation
and export. This preview uses exported PNG frames; the example also includes a playable
Godot project.*

Both wizard examples keep editable Aseprite sources and exported components.
Their Godot projects use those assets for a spell-timing game: cast at a moving
target, complete a round, and replay.

| Example | Workflow | What to inspect |
| --- | --- | --- |
| [Wizard v1](https://github.com/aigengame/aseprite-automation/blob/main/examples/wizard_cast/README.md) | Procedural pixel and pose sampling → SPA → Godot | A 128×96 scene, a 32-frame loop, reusable components, and a playable consumer |
| [Wizard v2](https://github.com/aigengame/aseprite-automation/blob/main/examples/wizard_cast_v2/README.md) | imagegen concepts and key poses → preparation and motion assembly → SPA → Godot | A 384×288 scene, seven editable `.aseprite` assets, exported PNG components, and a playable consumer |

SPA authors and exports the animation; imagegen supplies v2's initial artwork.
[gda](https://github.com/aigengame/godot-agent) handles Godot verification.
Each example records its preparation choices, validation evidence, and dogfooding feedback.

You can inspect the committed assets or open the Godot project without rebuilding
all assets. Full rebuilds are optional local checks; see each example's instructions
and [testing guide](https://github.com/aigengame/aseprite-automation/blob/main/docs/testing.md).

## Documentation and support

- [Usage guide](https://github.com/aigengame/aseprite-automation/blob/main/docs/usage.md) — recipes, runtime configuration, output handling, and current limits.
- [Sprite sheet export](https://github.com/aigengame/aseprite-automation/blob/main/docs/sprite-sheets.md) — layouts, trimming, colors, and metadata.
- [MCP setup](https://github.com/aigengame/aseprite-automation/blob/main/docs/mcp.md) — installation and client configuration.
- [Issues](https://github.com/aigengame/aseprite-automation/issues) — report a problem or request a capability.
- [Milestones](https://github.com/aigengame/aseprite-automation/milestones) — planned work and delivery progress.
- [Aseprite documentation](https://www.aseprite.org/docs/) — the editor, file formats, and native behavior.

When reporting a problem, include `spa version`, `spa info`, a minimal request,
and the returned error. Attach a small reproducible asset when you can share it.

## Contributing

Start with [testing](https://github.com/aigengame/aseprite-automation/blob/main/docs/testing.md),
[architecture](https://github.com/aigengame/aseprite-automation/blob/main/ARCHITECTURE.md),
and the [domain model](https://github.com/aigengame/aseprite-automation/blob/main/CONTEXT.md).
The [authority matrix](https://github.com/aigengame/aseprite-automation/blob/main/AUTHORITY_MATRIX.md) routes product and implementation decisions.

SPA-owned code and documentation use the
[MIT license](https://github.com/aigengame/aseprite-automation/blob/main/LICENSE).
Bundled third-party resources have their own
[notices](https://github.com/aigengame/aseprite-automation/blob/main/THIRD_PARTY_NOTICES.md).
Aseprite is a separate product with its own [license](https://www.aseprite.org/faq/#is-aseprite-free).
