gh-willibrandon-pixel-plugin/commands/pixel-export.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Export sprite to PNG, GIF, or spritesheet with optional scaling	<format> [output-file] [options]	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 information
• Layer data (if requested)

TexturePacker Format:

• Industry standard
• Widely supported
• Works with many game frameworks
• Good for cross-platform projects

Unity Format:

• Direct Unity import
• Includes pivot points
• Sprite Atlas compatible
• C# scripts can parse directly

Godot Format:

• Godot Engine native format
• SpriteFrames resource compatible
• AnimatedSprite node ready
• GDScript friendly

Error Handling

No sprite open:

Error: No sprite open. Create or open a sprite first.

Invalid format:

Error: Invalid format 'xyz'. Use: png, gif, sheet, or json

Invalid scale:

Error: Scale must be 1, 2, 4, or 8

Export failed:

Error: Cannot export to /path/file.png
Check path and permissions.

Invalid layout:

Error: Invalid layout 'xyz'. Use: horizontal, vertical, grid, or packed

Tips

For game development:

• Use grid layout for balanced dimensions
• Export JSON metadata for frame data
• Scale by 2x or 4x for HD displays
• Use packed layout for optimal texture memory

For web/social media:

• Export GIF at 10-15 FPS for smooth playback
• Optimize GIF to reduce file size
• Use transparent background
• Scale by 2x for better visibility

For print/high-res:

• Scale by 4x or 8x
• Export PNG for lossless quality
• Use white background for printing
• Maintain aspect ratio

For pixel art portfolios:

• Export PNG at original size (1x)
• Show pixel-perfect version
• Also provide scaled versions
• Include spritesheet to show animation frames

Notes

• Scaling uses nearest-neighbor to preserve pixel art look
• GIF optimization reduces file size without quality loss
• JSON metadata helps game engines load sprites correctly
• Spritesheet layouts optimize for different use cases
• Transparent backgrounds preserved by default
• All formats support frame-based animation
• Output path can be relative or absolute
• Files overwrite existing files without warning