Aseprite Plugin

The PIXL Aseprite plugin brings the full power of the pixl engine into Aseprite — import and export PAX and PAX-L tiles, compact and expand between formats, critique pixel art quality, pack atlases, convert images, and validate tilesets without leaving the editor.

Install

1. Download pixl-aseprite-*.aseprite-extension from the latest release.
2. Double-click the file, or open Aseprite and go to Edit > Preferences > Extensions > Add Extension.
3. All commands appear under Sprite > PIXL in the menu bar.

To build from source:

cd plugins/aseprite
./build.sh
# → pixl-aseprite.aseprite-extension

Commands

All commands are accessible from Sprite > PIXL in the Aseprite menu bar.

Import PAX / PAX-L

Import tiles from a .pax or .paxl file into Aseprite. Pick individual tiles or import the entire tileset as an atlas sprite sheet.

After scanning, a tile picker lets you select which tiles to import. Each tile opens as a separate Aseprite sprite — or as one combined sheet in atlas mode.

When importing from a .paxl file, the plugin automatically expands it to PAX via pixl expand before rendering. The PAXL scanner reads tile names directly from @tile directives without needing the expansion step.

Export to PAX / PAX-L

Export the active Aseprite sprite as a PAX tile. The plugin saves the sprite to a temp PNG, runs pixl import to quantize it against a palette, and appends the tile block to your target file.

When the target is a .paxl file, the exported tile is written as a PAX-L @tile directive. When the target is .pax, it's written as a TOML [tile.NAME] block. If no target file is given, the plugin runs pixl convert for a standalone pixel art conversion.

Render Tile

Render any tile from a .pax or .paxl file as a preview in Aseprite. Useful for checking tiles at different scales or with a pixel grid overlay.

Critique Tile

Run PIXL's structural quality analysis on a tile. The critique checks outline coverage, centering, canvas utilization, contrast, pixel density, and connected components — then returns a verdict of ACCEPT, REFINE, or REJECT with specific fix instructions.

Pack Atlas

Generate a sprite sheet atlas from an entire PAX or PAX-L tileset, with optional JSON metadata (TexturePacker format).

Convert to Pixel Art

Convert any image — a file on disk or the active Aseprite sprite — into true pixel art using PIXL's quantization engine.

Compact to PAX-L

Convert a .pax file to the compact PAX-L wire format. PAX-L is a line-oriented, sigil-based encoding optimized for LLM context windows, offering ~40-70% token savings over TOML.

Expand PAX-L

Convert a .paxl file back to standard .pax TOML format. Useful when you need to hand-edit a file or feed it to tools that only understand TOML.

Validate PAX

Run validation on a .pax or .paxl file and display the report. Checks include:

• Edge compatibility — do tile edges match for seamless tiling?
• Quality analysis — per-tile structural quality metrics
• Completeness check — are transition tiles missing for WFC generation?

Settings

Configure the path to the pixl binary. Use the Test Connection button to verify the plugin can reach the CLI.

How it works

The plugin is a thin Lua wrapper around the pixl CLI. Each command:

1. Collects options via an Aseprite dialog
2. Builds a pixl CLI command
3. Executes it via os.execute(), capturing output through a temp file
4. Parses the result and displays it in Aseprite (opens PNGs, shows text reports, etc.)

This means every feature the CLI supports is available — and new CLI features are automatically accessible without updating the plugin.

Plugin structure

plugins/aseprite/
├── package.json          # Extension metadata
├── plugin.lua            # Entry point — registers all commands
├── LICENSE               # PIXL license
├── build.sh              # Package into .aseprite-extension
├── lib/
│   ├── cli.lua           # pixl CLI wrapper (execute + capture output)
│   ├── pax_scan.lua      # Lightweight PAX scanner (extract tile/palette names)
│   └── image.lua         # Temp file helpers, palette conversion
└── commands/
    ├── import_pax.lua    # Import PAX / PAX-L → Aseprite
    ├── export_pax.lua    # Export Aseprite → PAX / PAX-L
    ├── render.lua        # Render tile preview
    ├── critique.lua      # Structural quality analysis
    ├── atlas.lua         # Pack sprite sheet atlas
    ├── convert.lua       # Image → pixel art conversion
    ├── compact.lua       # PAX → PAX-L conversion
    ├── expand.lua        # PAX-L → PAX conversion
    ├── validate.lua      # PAX validation report
    └── settings.lua      # Configure pixl binary path