/pixel-export

description: Export sprite to PNG, GIF, or spritesheet with optional scaling
argument-hint: <format> [output-file] [options]
allowed-tools: Read, Bash, mcp__aseprite__export_png, mcp__aseprite__export_gif, mcp__aseprite__export_spritesheet, mcp__aseprite__get_sprite_info

/pixel-export - Quick Export

Export sprites in various formats with optional scaling and layout options.

Usage

/pixel-export <format> [output-file] [options]

Formats

**png** - Export single frame as PNG

/pixel-export png sprite.png
/pixel-export png sprite.png scale=2

**gif** - Export animation as GIF

/pixel-export gif animation.gif
/pixel-export gif animation.gif fps=10

**sheet** - Export spritesheet

/pixel-export sheet spritesheet.png
/pixel-export sheet spritesheet.png layout=horizontal

**json** - Export with JSON metadata

/pixel-export json sprite.json
/pixel-export json sprite.json format=aseprite

Options

**Common Options:**

• `scale=N` - Scale output by N (1, 2, 4, 8) using nearest-neighbor
• `transparent` - Preserve transparency (default: true)
• `background=#RRGGBB` - Set background color (default: transparent)

**GIF Options:**

• `fps=N` - Frames per second (default: 10)
• `loop=N` - Loop count (0 = infinite, default: 0)
• `optimize` - Optimize GIF file size (default: true)

**Spritesheet Options:**

• `layout=horizontal|vertical|grid|packed` - Layout style (default: horizontal)
• `padding=N` - Pixels between frames (default: 0)
• `trim` - Trim transparent edges (default: false)

**JSON Options:**

• `format=aseprite|texturepacker|unity|godot` - Metadata format (default: aseprite)
• `include-layers` - Include layer information (default: false)

Examples

/pixel-export png output.png
→ Exports current frame as PNG (1x scale)

/pixel-export png output.png scale=4
→ Exports at 4x scale (pixel-perfect)

/pixel-export gif animation.gif fps=12
→ Exports animation as GIF at 12 FPS

/pixel-export sheet spritesheet.png layout=grid
→ Exports frames in grid layout

/pixel-export json sprite.json format=unity
→ Exports with Unity-compatible JSON metadata

/pixel-export png sprite.png scale=2 background=#ffffff
→ Exports at 2x scale with white background

Layout Styles

**horizontal** - All frames in a single row

[Frame1][Frame2][Frame3][Frame4]

**vertical** - All frames in a single column

[Frame1]
[Frame2]
[Frame3]
[Frame4]

**grid** - Frames arranged in grid (optimal rows/columns)

[Frame1][Frame2][Frame3]
[Frame4][Frame5][Frame6]
[Frame7][Frame8][Frame9]

**packed** - Optimal space usage (may vary dimensions)

[Frame1][Frame2][Frame5]
[Frame3][Frame4][Frame6]

JSON Metadata Formats

**Aseprite Format:**

{
  "frames": [
    {
      "filename": "sprite_0.png",
      "frame": {"x": 0, "y": 0, "w": 32, "h": 32},
      "duration": 100
    }
  ],
  "meta": {
    "image": "spritesheet.png",
    "size": {"w": 128, "h": 32},
    "scale": "1"
  }
}

**TexturePacker Format:**

{
  "frames": {
    "sprite_0.png": {
      "frame": {"x": 0, "y": 0, "w": 32, "h": 32},
      "sourceSize": {"w": 32, "h": 32}
    }
  }
}

**Unity Format:**

{
  "sprites": [
    {
      "name": "sprite_0",
      "rect": {"x": 0, "y": 0, "width": 32, "height": 32},
      "pivot": {"x": 0.5, "y": 0.5}
    }
  ]
}

**Godot Format:**

{
  "frames": [
    {
      "name": "sprite_0",
      "region": {"x": 0, "y": 0, "w": 32, "h": 32}
    }
  ]
}

Implementation

Parse $ARGUMENTS: 1. Extract format (first argument) 2. Extract output file path (second argument, or auto-generate) 3. Parse options (key=value pairs)

**For PNG export:** 1. Use `mcp__aseprite__export_png` 2. Apply scale option if specified 3. Set background or transparency 4. Confirm export with file path

**For GIF export:** 1. Use `mcp__aseprite__export_gif` 2. Set frame duration based on fps option 3. Apply loop count 4. Optimize if requested 5. Confirm export

**For Spritesheet export:** 1. Use `mcp__aseprite__export_spritesheet` 2. Apply layout option 3. Set padding between frames 4. Optionally trim transparent edges 5. Confirm export

**For JSON export:** 1. Export spritesheet image 2. Generate JSON metadata in specified format 3. Include sprite positions, dimensions, timing 4. Write JSON file alongside image 5. Confirm both files created

Default Behavior

If output file not specified:

• PNG: `sprite.png`
• GIF: `animation.gif`
• Spritesheet: `spritesheet.png`
• JSON: `sprite.json` + `sprite.png`

Output files saved to current working directory or user-specified path.

Scaling Details

**Nearest-Neighbor Algorithm:**

• Preserves sharp pixel art look
• No blur or antialiasing
• Each pixel becomes NxN pixels
• Essential for pixel art aesthetics

**Scale Factors:**

• `scale=1` - Original size
• `scale=2` - 2x size (common for HD displays)
• `scale=4` - 4x size (very large)
• `scale=8` - 8x size (maximum)

GIF Optimization

**Optimization reduces file size by:**

• Using local color tables per frame
• Removing duplicate pixels
• Applying delta compression
• Optimizing frame disposal methods

**Benefits:**

• Smaller file sizes (often 30-50% reduction)
• Faster loading times
• Same visual quality
• No loss of colors or frames

Spritesheet Use Cases

**Horizontal Layout:**

• Simple animation sequences
• Easy to visualize frame order
• Works well with sprite editors
• Good for walkthroughs and documentation

**Vertical Layout:**

• Saves horizontal space
• Good for tall sprites
• Similar benefits to horizontal

**Grid Layout:**

• Optimal space usage for many frames
• Square-ish output dimensions
• Easy to calculate frame positions
• Best for game engines

**Packed Layout:**

• Maximum space efficiency
• Variable frame sizes supported
• Requires JSON metadata for positions
• Advanced game engine feature

JSON Metadata Usage

**Aseprite Format:**

• Native format, most detailed
• Includes frame timing
• Animation tag inf