Create, animate, and export pixel art using Aseprite through natural language and commands

GitHub stars
429

Install

/plugin install pixel-plugin@pixel-plugin

Run it inside Claude Code after adding the marketplace with /plugin marketplace add willibrandon/pixel-plugin.

Contents

Discovered from source

Skills 4

Pixel Art Animator

Overview

This Skill handles all animation-related tasks for sprites, including frame management, timing, animation tags (sequences), and linked cels for efficient animation.

When to Use

Use this Skill when the user:

  • Wants to "animate" a sprite or "add animation"
  • Mentions "frames", "keyframes", or "frame rate"
  • Describes motion: "walk cycle", "run cycle", "idle animation", "attack animation"
  • Asks about "animation tags", "loops", or "playback"
  • Wants to create "sprite sheets" for animation (coordinate with exporter Skill)

Trigger Keywords: animate, animation, frames, walk cycle, run, idle, attack, loop, movement, motion

Instructions

1. Understanding Animation Basics

Frame: A single image in an animation sequence. Sprites start with 1 frame.

Frame Duration: How long each frame displays (in milliseconds). Default: 100ms (10 FPS).

Animation Tag: Named sequence of frames (e.g., "walk" frames 1-4, "idle" frames 5-8).

Linked Cel: A cel that shares image data with another cel. Editing one updates all linked cels.

Playback Direction:

  • Forward: Frames play 1 → 2 → 3 → 4, then loop
  • Reverse: Frames play 4 → 3 → 2 → 1, then loop
  • Ping-pong: Frames play 1 → 2 → 3 → 4 → 3 → 2 → 1, then loop

2. Creating Animation Frames

Adding Frames: Use mcp__aseprite__add_frame to create new frames:

  • Frames are numbered starting from 1
  • New frames start as copies of the current frame (or blank)

Common Frame Counts:

  • Idle Animation: 2-4 frames (subtle movement)
  • Walk Cycle: 4-8 frames (legs alternate)
  • Run Cycle: 6-8 frames (faster, exaggerated)
  • Attack Animation: 3-6 frames (windup, strike, recovery)
  • Jump: 4-6 frames (crouch, ascend, peak, descend, land)

Duplicating Frames: Use mcp__aseprite__duplicate_frame to copy existing frames:

  • Useful for creating variations
  • Starting point for similar frames

Deleting Frames: Use mcp__aseprite__delete_frame to remove frames:

  • Cannot delete the last remaining frame
  • Frames are renumbered after deletion

3. Setting Frame Timing

Frame Duration: Use mcp__aseprite__set_frame_duration:

  • Duration in milliseconds (ms)
  • 100ms = 10 FPS
  • 50ms = 20 FPS
  • 33ms ≈ 30 FPS
  • 16ms ≈ 60 FPS

Common Timing Patterns:

Even Timing: All frames same duration. Simple and predictable.

  • Walk cycle: all frames 100ms (smooth 10 FPS)

Variable Timing: Different durations for emphasis.

  • Idle: slow frames (150ms) for breathing effect
  • Attack: fast strike (30ms), slower recovery (100ms)

Hold Frames: Longer duration for dramatic effect.

  • Jump peak: 200ms (hang time)
  • Impact: 50ms (quick flash)

4. Creating Animation Tags

Purpose: Organize frames into named sequences.

Use mcp__aseprite__create_tag:

  • Name: "walk", "idle", "attack", etc.
  • From Frame: starting frame (1-indexed)
  • To Frame: ending frame (inclusive)
  • Direction: "forward", "reverse", or "ping-pong"

Example Tags:

  • Tag "idle": frames 1-2, ping-pong direction
  • Tag "walk": frames 3-6, forward direction
  • Tag "attack": frames 7-10, forward direction

Benefits:

  • Export specific animations separately
  • Organize complex sprite sheets
  • Game engines can reference tags

5. Using Linked Cels

Purpose: Share image data across frames to save memory and maintain consistency.

Use mcp__aseprite__link_cel:

  • Useful when frame content doesn't change
  • Example: background layer stays same across animation
  • Editing one linked cel updates all

When to Use:

  • Static background elements
  • Character face in walk cycle (if body animates separately)
  • Repeated frames in animation

Workflow:

  1. Create frames with content
  2. Link cels that should share data
  3. Edit once, updates everywhere

6. Animation Workflows

Workflow 1: Walk Cycle (4 frames)

  1. Create base sprite (or use existing)
  2. Add 3 more frames (total 4)
  3. Edit each frame for walk positions:
    • Frame 1: Left foot forward
    • Frame 2: Contact (both feet touching)
    • Frame 3: Right foot forward
    • Frame 4: Contact (both feet touching)
  4. Set all frames to 100ms duration
  5. Create tag "walk": frames 1-4, forward direction

Workflow 2: Idle Animation (2 frames)

  1. Create base sprite
  2. Add 1 more frame (total 2)
  3. Slight variations:
    • Frame 1: Normal stance
    • Frame 2: Subtle movement (breathing, blinking)
  4. Set frames to 500ms duration (slow, subtle)
  5. Create tag "idle": frames 1-2, ping-pong direction

Workflow 3: Complex Multi-Animation Sprite

  1. Create base sprite
  2. Add enough frames for all animations:
    • Idle: 2 frames
    • Walk: 4 frames
    • Jump: 4 frames
    • Total: 10 frames
  3. Arrange frames sequentially
  4. Create separate tags:
    • Tag "idle": frames 1-2
    • Tag "walk": frames 3-6
    • Tag "jump": frames 7-10
  5. Set appropriate frame durations per animation

Examples

Example 1: Simple 2-Frame Idle

User Request:

"Add a simple idle animation to this sprite"

Approach:

  1. Add 1 frame (now have frame 1 and 2)
  2. On frame 2, make subtle change (move pixels up/down 1-2 pixels)
  3. Set both frames to 500ms duration
  4. Create tag "idle": frames 1-2, ping-pong direction
  5. Result: gentle back-and-forth idle motion

Example 2: 4-Frame Walk Cycle

User Request:

"Create a walk cycle animation for this character"

Approach:

  1. Add 3 frames (now have 1, 2, 3, 4)
  2. Edit each frame for walk poses
  3. Set all frames to 100ms duration
  4. Create tag "walk": frames 1-4, forward direction
  5. Result: looping walk animation at 10 FPS

Example 3: Variable Timing Attack

User Request:

"Add an attack animation with a fast strike"

Approach:

  1. Add 5 frames (total 6 frames, assuming frame 1 exists)
  2. Frame sequence:
    • Frame 2: Windup (slow)
    • Frame 3: Prepare (slow)
    • Frame 4: Strike (fast)
    • Frame 5: Follow-through (medium)
    • Frame 6: Recovery (slow)
  3. Set durations:
    • Frames 2-3: 150ms (slow windup)
    • Frame 4: 30ms (fast strike)
    • Frame 5: 80ms (medium follow-through)
    • Frame 6: 120ms (slow recovery)
  4. Create tag "attack": frames 2-6, forward direction

Example 4: Linked Background

User Request:

"Animate the character but keep the background static"

Approach:

  1. Assume 2 layers: "Background", "Character"
  2. Add frames for animation
  3. Edit "Character" layer on each frame for animation
  4. Link all cels on "Background" layer:
    • Link frame 2's background to frame 1
    • Link frame 3's background to frame 1
    • Link frame 4's background to frame 1
  5. Background stays identical, character animates

Technical Details

Frame Numbering

  • Frames are 1-indexed (first frame is frame 1)
  • Adding frame at position N inserts at that position
  • Deleting frame N renumbers subsequent frames

Frame Duration Limits

  • Minimum: 1ms (not recommended, too fast)
  • Maximum: 65535ms (65.5 seconds)
  • Practical range: 16ms (60 FPS) to 500ms (2 FPS)

Animation Tag Limits

  • No hard limit on number of tags
  • Tags can overlap frames
  • Tag names should be unique and descriptive

Linked Cel Behavior

  • Editing one linked cel updates all linked instances
  • Unlinking creates independent copy
  • Useful for memory optimization in large animations

Performance

  • Adding frame: <20ms
  • Duplicating frame: <30ms
  • Setting frame duration: <10ms
  • Creating tag: <15ms
  • Linking cel: <25ms

Common Patterns

Pattern: Breathing Idle

2 frames, ping-pong, slow timing (400-500ms)

  • Frame 1: Normal
  • Frame 2: Slight vertical shift (1-2 pixels)

Pattern: Basic Walk

4 frames, forward, even timing (100ms)

  • Frame 1: Left foot forward, right foot back
  • Frame 2: Both feet together (contact)
  • Frame 3: Right foot forward, left foot back
  • Frame 4: Both feet together (contact)

Pattern: Run Cycle

6-8 frames, forward, faster timing (60-80ms)

  • More exaggerated poses than walk
  • Longer strides
  • Leaning forward

Pattern: Jump Sequence

5-6 frames, forward, variable timing

  • Frame 1: Crouch (100ms)
  • Frame 2: Launch (50ms)
  • Frame 3: Ascend (80ms)
  • Frame 4: Peak (200ms) - hang time
  • Frame 5: Descend (80ms)
  • Frame 6: Land (100ms)

Integration with Other Skills

  • Start with pixel-art-creator to create base sprite before animating
  • Use pixel-art-professional for polish (shading, antialiasing) after animation
  • Hand off to pixel-art-exporter when user wants to export spritesheet or GIF

Error Handling

Cannot delete last frame:

  • Sprites must have at least 1 frame
  • Inform user if they try to delete last frame

Invalid frame numbers:

  • Frame numbers must be 1 to N (where N is total frames)
  • Check bounds before operations

Tag frame range errors:

  • "From" frame must be ≤ "To" frame
  • Both must be valid frame numbers

Success Indicators

You've successfully used this Skill when:

  • Frames added/modified correctly
  • Frame durations set appropriately for desired FPS
  • Animation tags created with correct ranges
  • User understands animation will loop or play as specified
  • Animation is ready for export or further refinement

Pixel Art Creator

Overview

This Skill enables creation of new pixel art sprites with full control over canvas properties, layers, and basic drawing operations. It's the foundational Skill for all pixel art workflows.

When to Use

Use this Skill when the user:

  • Wants to "create a sprite" or "make pixel art"
  • Mentions sprite dimensions (e.g., "64x64", "32 by 32", "128 pixels wide")
  • Asks to "draw" basic shapes (pixels, lines, rectangles, circles)
  • Needs to set up a canvas or layers
  • Mentions color modes (RGB, Grayscale, Indexed)

Trigger Keywords: create, sprite, canvas, draw, pixel art, dimensions, layer, new sprite

Instructions

1. Creating a Canvas

When the user requests a sprite, create the canvas first:

Color Modes:

  • RGB: Full color (24-bit), best for modern pixel art
  • Grayscale: Shades of gray only, for monochrome art
  • Indexed: Limited palette (1-256 colors), for retro game art

Recommended Sizes:

  • Icons: 16x16, 24x24, 32x32
  • Characters: 32x32, 48x48, 64x64
  • Tiles: 16x16, 32x32, 64x64
  • Scenes: 128x128, 256x256, 320x240 (retro resolution)

Use mcp__aseprite__create_canvas with parameters:

  • width: 1-65535 pixels
  • height: 1-65535 pixels
  • color_mode: "RGB", "Grayscale", or "Indexed"

2. Managing Layers

Adding Layers: Use mcp__aseprite__add_layer to organize sprite elements:

  • Background layer for solid colors or backgrounds
  • Character layer for main subject
  • Effects layer for highlights, shadows, outlines
  • Detail layer for accessories or fine details

Layer Workflow:

  1. Create canvas
  2. Add named layers (e.g., "Background", "Character", "Effects")
  3. Draw on specific layers
  4. Use layers for organization and editing flexibility

Important: Cannot delete the last layer in a sprite.

3. Drawing Primitives

Draw Individual Pixels: Use mcp__aseprite__draw_pixels for precise pixel placement:

  • Supports batch operations (multiple pixels at once)
  • Accepts colors in hex format (#RRGGBB) or palette indices
  • Can snap to nearest palette color (for Indexed mode)

Example:

Draw pixels at coordinates:
- (10, 10) in red (#FF0000)
- (11, 10) in red (#FF0000)
- (12, 10) in red (#FF0000)

Draw Lines: Use mcp__aseprite__draw_line:

  • Straight lines between two points
  • Useful for outlines, edges, connecting points

Draw Rectangles: Use mcp__aseprite__draw_rectangle:

  • Filled or outline mode
  • Perfect for backgrounds, UI elements, platforms

Draw Circles/Ellipses: Use mcp__aseprite__draw_circle:

  • Filled or outline mode
  • For round objects, planets, effects

Draw Contours (Polylines/Polygons): Use mcp__aseprite__draw_contour:

  • Connect multiple points
  • Useful for complex shapes, terrain, irregular outlines

Flood Fill: Use mcp__aseprite__fill_area:

  • Fill connected pixels of the same color
  • Like a paint bucket tool
  • Great for filling large areas quickly

4. Working with Colors

Setting Colors:

  • Hex Format: #RRGGBB (e.g., #FF0000 for red)
  • RGB: Specify red, green, blue values (0-255)
  • Palette Index: For Indexed mode (0-255)

Common Colors:

  • Red: #FF0000
  • Green: #00FF00
  • Blue: #0000FF
  • Yellow: #FFFF00
  • Cyan: #00FFFF
  • Magenta: #FF00FF
  • Black: #000000
  • White: #FFFFFF

Color Palettes: For Indexed color mode, set the palette first:

  • Use mcp__aseprite__set_palette with array of hex colors
  • Example: ["#000000", "#FFFFFF", "#FF0000", "#00FF00"]

5. Workflow Best Practices

Typical Creation Workflow:

  1. Understand Requirements

    • What size sprite?
    • What color mode?
    • What style (modern vs retro)?
  2. Create Canvas

    • Choose appropriate dimensions
    • Select color mode (RGB for modern, Indexed for retro)
  3. Set Up Layers (optional but recommended)

    • Add layers for organization
    • Name layers descriptively
  4. Set Palette (for Indexed mode)

    • Define limited color palette
    • Use retro-appropriate palettes (NES: 16 colors, Game Boy: 4 colors)
  5. Draw Basic Shapes

    • Start with outline
    • Fill with colors
    • Add details
  6. Verify Result

    • Use mcp__aseprite__get_sprite_info to check properties
    • Describe what was created to user
  7. Prepare for Export (if requested)

    • Hand off to pixel-art-exporter Skill

Examples

Example 1: Simple Sprite

User Request: "Create a 32x32 sprite with a red circle"

Approach:

  1. Create 32x32 RGB canvas
  2. Draw filled circle in center (radius 12) in red
  3. Confirm creation

Example 2: Layered Sprite

User Request: "Make a 64x64 sprite with a blue background and a yellow character"

Approach:

  1. Create 64x64 RGB canvas
  2. Add layer "Background"
  3. Fill entire canvas with blue (#0000FF) on Background layer
  4. Add layer "Character"
  5. Draw yellow (#FFFF00) rectangle or shape on Character layer
  6. Confirm layers and contents

Example 3: Indexed Color Sprite

User Request: "Create a 48x48 Game Boy style sprite"

Approach:

  1. Create 48x48 Indexed canvas
  2. Set Game Boy palette: ["#0F380F", "#306230", "#8BAC0F", "#9BBC0F"]
  3. Draw using 4-color palette
  4. Use pixel-perfect drawing

Example 4: Complex Shape

User Request: "Draw a pixelated tree on a 64x64 canvas"

Approach:

  1. Create 64x64 RGB canvas
  2. Draw brown (#8B4513) rectangle for trunk (using draw_rectangle)
  3. Draw green (#228B22) irregular shape for foliage (using draw_contour or multiple rectangles)
  4. Add details with individual pixels
  5. Describe the tree to user

Technical Details

Canvas Properties

  • Width/Height: 1-65535 pixels (practical limit usually <1024)
  • Color Modes:
    • RGB: 24-bit color (16.7 million colors)
    • Grayscale: 8-bit (256 shades of gray)
    • Indexed: 1-256 colors from palette

Drawing Coordinates

  • Origin (0, 0) is top-left corner
  • X increases rightward
  • Y increases downward

Performance

  • Batch pixel operations when possible
  • Drawing operations complete in <100ms typically
  • Large canvases (>512x512) may take slightly longer

Limitations

  • Cannot create canvas smaller than 1x1
  • Cannot create canvas larger than 65535x65535 (practical limit much lower)
  • Cannot delete last layer
  • Indexed mode palette limited to 256 colors maximum

Common Patterns

Pattern: Quick Sprite

For simple requests like "create a sprite":

  • Default to 64x64 RGB canvas
  • Add basic shape or placeholder
  • Ask user for refinements

Pattern: Retro Game Sprite

For retro-style requests:

  • Use Indexed color mode
  • Set appropriate palette (NES, Game Boy, C64, etc.)
  • Use limited colors and pixel-perfect drawing

Pattern: Icon Creation

For icon requests:

  • Use 16x16, 24x24, or 32x32 dimensions
  • RGB mode for modern icons
  • Simple, recognizable shapes
  • High contrast colors

Integration with Other Skills

  • Hand off to pixel-art-animator when user mentions "animation", "frames", or "movement"
  • Hand off to pixel-art-professional when user asks for "dithering", "shading", or "palette refinement"
  • Hand off to pixel-art-exporter when user asks to "export", "save", or mentions file formats

Error Handling

If canvas creation fails:

  • Check dimensions are valid (1-65535)
  • Verify color mode is spelled correctly
  • Suggest alternative dimensions if too large

If drawing fails:

  • Verify coordinates are within canvas bounds
  • Check color format is valid hex (#RRGGBB)
  • For Indexed mode, ensure palette is set first

If layer operations fail:

  • Cannot delete last layer (inform user)
  • Layer names should be descriptive strings

Success Indicators

You've successfully used this Skill when:

  • Canvas created with correct dimensions and color mode
  • Drawing operations complete without errors
  • User can see or understand what was created
  • Sprite is ready for next steps (animation, export, refinement)

Pixel Art Exporter

Overview

The Pixel Art Exporter Skill enables exporting pixel art sprites from Aseprite to various formats optimized for different use cases. This includes single images (PNG), animated GIFs, spritesheets, and JSON metadata for game engines.

Core Capabilities:

  • Export single frames or entire animations as PNG images
  • Generate animated GIFs with customizable timing and looping
  • Create spritesheets in multiple layouts (horizontal, vertical, grid, packed)
  • Generate JSON metadata for game engines (Unity, Godot, Phaser, generic)
  • Scale exports with pixel-perfect upscaling (1x, 2x, 4x, etc.)
  • Handle transparency, background colors, and frame-specific exports

Export Formats Supported:

  • PNG: Single images or frame sequences with transparency
  • GIF: Animated GIFs with frame timing and loop control
  • Spritesheet: Texture atlases with various packing algorithms
  • JSON: Frame metadata, animation tags, layer information

This Skill works with the pixel-mcp server tools to produce production-ready assets for web, games, and applications.

When to Use

Invoke this Skill when the user:

  • Wants to export or save: "export this sprite", "save as PNG", "generate a spritesheet"
  • Mentions file formats: "PNG", "GIF", "spritesheet", "sprite sheet", "texture atlas", "JSON"
  • Prepares for game engines: "export for Unity", "Godot spritesheet", "Phaser animation"
  • Needs specific outputs: "export just frame 3", "create a tileset", "save each layer separately"
  • Requests scaling: "export at 2x size", "scale up 4x", "upscale for retina displays"
  • Wants animation exports: "make this into a GIF", "export the animation", "save all frames"
  • Needs metadata: "include JSON data", "export with coordinates", "frame information"

Example Triggers:

  • "Can you export this character sprite as a PNG?"
  • "I need a spritesheet for my game engine"
  • "Save this animation as an animated GIF"
  • "Export at 4x scale for high-resolution displays"
  • "Generate a texture atlas with JSON metadata"
  • "Export just the 'run' animation tag"

Instructions

1. Exporting Single Images (PNG)

For static sprites or single frames:

  1. Get Sprite Information First

    Use mcp__aseprite__get_sprite_info to understand:
    - Current dimensions
    - Number of frames
    - Available layers
    - Color mode and transparency settings
    
  2. Export PNG with Transparency

    Use mcp__aseprite__export_png:
    - file_path: Absolute path (e.g., "/path/to/output/sprite.png")
    - frame_number: Specific frame (0-indexed) or omit for current frame
    - layer: Specific layer name or omit for merged output
    - scale: Scaling factor (1, 2, 4, etc.) - default is 1
    
  3. Export Options

    • Transparent background: Default behavior, preserves alpha channel
    • Specific background: Use layer visibility or flatten before export
    • Single frame from animation: Specify frame_number parameter
    • Specific layer only: Provide layer name to export just that layer

Example Workflow:

1. Get sprite info to verify dimensions and frame count
2. Export PNG: mcp__aseprite__export_png with desired frame and scale
3. Confirm file creation and report dimensions to user

2. Exporting Animated GIFs

For animations intended for web or presentations:

  1. Verify Animation Setup

    Use mcp__aseprite__get_sprite_info to check:
    - Frame count (needs 2+ frames)
    - Frame durations (timing information)
    - Animation tags (if specific tag requested)
    - Sprite dimensions
    
  2. Export GIF

    Use mcp__aseprite__export_gif:
    - file_path: Output path (e.g., "/path/to/animation.gif")
    - animation_tag: Optional - specific tag name to export
    - loop: true (infinite loop) or false (play once)
    - scale: Upscaling factor if needed
    
  3. GIF Optimization Considerations

    • GIF format has 256-color limit - ensure palette is optimized
    • Frame timing is preserved from Aseprite frame durations
    • Transparency is supported but may have edge artifacts
    • File size increases with dimensions and frame count

Example Workflow:

1. Verify sprite has multiple frames
2. Export GIF with appropriate loop setting
3. Report file size and frame count to user
4. Suggest optimization if file is large (>1MB)

3. Creating Spritesheets

For game engines and texture atlases:

  1. Understand Layout Requirements

    Layout Types:

    • Horizontal: All frames in a single row (good for scrolling animations)
    • Vertical: All frames in a single column (good for CSS animations)
    • Grid: Frames arranged in rows and columns (balanced dimensions)
    • Packed: Optimized packing to minimize texture size (engine-specific)
  2. Export Spritesheet

    Use mcp__aseprite__export_spritesheet:
    - file_path: Output PNG path (e.g., "/path/to/spritesheet.png")
    - layout: "horizontal", "vertical", "grid", or "packed"
    - animation_tag: Optional - export specific animation only
    - scale: Upscaling factor
    - padding: Pixels between frames (default 0, common: 1-2)
    - include_json: true to generate metadata file
    
  3. JSON Metadata Structure

    When include_json: true, creates a .json file with:

    {
      "frames": [
        {
          "filename": "frame_0.png",
          "frame": {"x": 0, "y": 0, "w": 32, "h": 32},
          "spriteSourceSize": {"x": 0, "y": 0, "w": 32, "h": 32},
          "sourceSize": {"w": 32, "h": 32},
          "duration": 100
        }
      ],
      "meta": {
        "app": "Aseprite",
        "version": "1.3.x",
        "format": "RGBA8888",
        "size": {"w": 256, "h": 32},
        "scale": "1"
      }
    }
    
  4. Layout Selection Guidelines

    • Horizontal: Best for web/CSS sprite animations, simple scrolling
    • Vertical: Mobile-friendly, vertical scrolling animations
    • Grid: Unity, Godot - balanced texture dimensions (power-of-2)
    • Packed: Advanced engines with atlas support (Phaser, LibGDX)

Example Workflow:

1. Ask user about target platform if not specified
2. Recommend layout based on use case
3. Export spritesheet with JSON metadata
4. Report texture dimensions and frame count
5. Provide integration code sample for their engine

4. Generating JSON Metadata

For game engine integration:

  1. Metadata Formats by Engine

    Unity:

    • Use "grid" layout for Unity's Sprite Editor
    • JSON provides frame coordinates for slicing
    • Include padding to prevent texture bleeding

    Godot:

    • Use "horizontal" or "grid" layout
    • JSON maps to AnimatedSprite frames
    • Frame duration converts to FPS

    Phaser:

    • Use "packed" layout for optimal performance
    • JSON follows Texture Packer format
    • Supports trimmed sprites and rotation

    Generic/Custom:

    • Standard frame array with x, y, w, h coordinates
    • Duration in milliseconds per frame
    • Animation tag groupings
  2. Export with Metadata

    Always include JSON when exporting for game engines:
    - Set include_json: true in export_spritesheet
    - JSON file created with same name as PNG (different extension)
    - Contains frame positions, durations, and sprite metadata
    
  3. Metadata Usage Examples

    Parsing in JavaScript (Phaser):

    this.load.atlas('sprite', 'spritesheet.png', 'spritesheet.json');
    this.add.sprite(x, y, 'sprite', 'frame_0.png');
    

    Parsing in C# (Unity):

    // Import spritesheet.png with Multiple sprite mode
    // Use JSON to set sprite rectangles in Sprite Editor
    

5. Scaling Exports

Pixel-perfect upscaling for high-resolution displays:

  1. When to Scale

    • Retina/HiDPI displays: Use 2x or 4x
    • Modern game engines: Export at native size, let engine scale
    • Web: Export 2x and use CSS to scale down (sharper rendering)
    • Print/marketing: Use 4x or higher
  2. Scaling Best Practices

    • Always use integer scaling (1x, 2x, 3x, 4x, not 1.5x)
    • Maintain pixel-perfect sharpness with nearest-neighbor
    • Scale before export, not after (prevents blurring)
    • Consider file size vs. quality tradeoffs
  3. Apply Scaling

    Add scale parameter to any export:
    - mcp__aseprite__export_png: scale: 2
    - mcp__aseprite__export_gif: scale: 4
    - mcp__aseprite__export_spritesheet: scale: 2
    
  4. Resolution Recommendations

    • 1x: Original pixel art size, retro aesthetic
    • 2x: Standard for modern displays, good balance
    • 4x: High-resolution, marketing materials
    • 8x+: Ultra-high-resolution, print, large displays

Export Workflows for Different Use Cases

Static Sprite for Web

1. Get sprite info to verify single frame
2. Export PNG at 2x scale with transparency
3. Optimize PNG with compression tools if needed
4. Provide HTML/CSS example for display

Character Animation for Game

1. Verify animation has multiple frames and tags
2. Export spritesheet with "grid" layout
3. Include JSON metadata (include_json: true)
4. Set appropriate padding (1-2 pixels)
5. Scale if needed (typically 1x for engines)
6. Provide code snippet for target engine

Icon Set Export

1. If multiple layers, export each separately
2. Use PNG format with transparency
3. Scale to multiple sizes (16x16, 32x32, 64x64)
4. Batch export all sizes
5. Organize in output directory structure

Social Media GIF

1. Verify frame timing is appropriate (100-200ms typical)
2. Export GIF with loop: true
3. Scale to 2x or 4x for visibility
4. Check file size (optimize if >2MB)
5. Suggest hosting platforms if needed

Tileset for Game Engine

1. Verify tiles are uniform size (e.g., 16x16, 32x32)
2. Export as grid spritesheet
3. Set padding to 0 or 1 (depends on engine)
4. Include JSON for tile coordinates
5. Provide tile size and grid dimensions

Game Engine Integration

Unity Integration

Export Settings:

  • Layout: "grid"
  • Include JSON: true
  • Padding: 1-2 pixels (prevents bleeding)
  • Scale: 1x (Unity handles scaling)

Import Steps:

  1. Import spritesheet.png into Assets
  2. Set Texture Type to "Sprite (2D and UI)"
  3. Set Sprite Mode to "Multiple"
  4. Open Sprite Editor and use JSON coordinates to slice
  5. Create Animator Controller with sprite animation

Code Example:

SpriteRenderer renderer = GetComponent<SpriteRenderer>();
renderer.sprite = sprites[frameIndex];

Godot Integration

Export Settings:

  • Layout: "horizontal" or "grid"
  • Include JSON: true
  • Scale: 1x
  • Padding: 0-1 pixels

Import Steps:

  1. Import spritesheet.png to project
  2. Create AnimatedSprite node
  3. Create SpriteFrames resource
  4. Add frames from spritesheet
  5. Use JSON durations to set FPS

Code Example:

$AnimatedSprite.play("run")
$AnimatedSprite.speed_scale = 1.0

Phaser Integration

Export Settings:

  • Layout: "packed" or "horizontal"
  • Include JSON: true (Texture Packer format)
  • Scale: 1x or 2x depending on game resolution

Import Steps:

  1. Place spritesheet.png and .json in assets
  2. Load as atlas in preload()
  3. Create sprite with atlas key
  4. Create animations from frame names

Code Example:

this.load.atlas('player', 'spritesheet.png', 'spritesheet.json');

this.anims.create({
  key: 'run',
  frames: this.anims.generateFrameNames('player', {
    prefix: 'frame_',
    suffix: '.png',
    start: 0,
    end: 7
  }),
  frameRate: 10,
  repeat: -1
});

Generic/Custom Engine

Export Settings:

  • Layout: Based on engine capabilities
  • Include JSON: true
  • Provide simple frame array format

JSON Structure:

{
  "frames": [
    {"x": 0, "y": 0, "w": 32, "h": 32, "duration": 100}
  ],
  "meta": {
    "frameWidth": 32,
    "frameHeight": 32,
    "frameCount": 8
  }
}

Integration Pattern:

  1. Load PNG texture
  2. Parse JSON to get frame rectangles
  3. Create sub-textures/sprites from coordinates
  4. Use duration for animation timing

Technical Details

PNG Export Format

Specifications:

  • Color Mode: RGBA (8-bit per channel)
  • Transparency: Full alpha channel support
  • Compression: PNG lossless compression
  • Color Space: sRGB
  • Bit Depth: 32-bit (8-bit per channel RGBA)

When to Use:

  • Static sprites with transparency
  • Individual frames from animations
  • High-quality source files
  • Layer-specific exports

GIF Export Format

Specifications:

  • Color Palette: Maximum 256 colors
  • Transparency: Binary (on/off), no partial alpha
  • Animation: Frame-based with per-frame timing
  • Loop Control: Infinite or play-once
  • Compression: LZW compression

Limitations:

  • Color limit may require palette optimization
  • No partial transparency (alpha is binary)
  • Larger file sizes than video formats
  • Limited to 8-bit color depth

When to Use:

  • Web animations without video player
  • Social media posts
  • Email-compatible animations
  • Simple looping animations

Spritesheet Layouts

Horizontal Layout:

[Frame0][Frame1][Frame2][Frame3]...
  • Dimensions: width = frameWidth * frameCount, height = frameHeight
  • Best for: CSS animations, simple scrolling

Vertical Layout:

[Frame0]
[Frame1]
[Frame2]
[Frame3]
...
  • Dimensions: width = frameWidth, height = frameHeight * frameCount
  • Best for: Mobile-optimized, vertical scrolling

Grid Layout:

[Frame0][Frame1][Frame2][Frame3]
[Frame4][Frame5][Frame6][Frame7]
[Frame8][Frame9][Frame10][Frame11]
  • Dimensions: Balanced to create near-square texture
  • Best for: Game engines, power-of-2 textures, Unity, Godot

Packed Layout:

[Frame0][Frame2][Frame5]
[Frame1][Frame3][Frame6]
    [Frame4][Frame7]
  • Dimensions: Optimally packed to minimize wasted space
  • Best for: Advanced engines with atlas support (Phaser, LibGDX)
  • Requires JSON metadata for frame positions

Metadata Structures

Standard Frame Format:

{
  "filename": "frame_0.png",
  "frame": {"x": 0, "y": 0, "w": 32, "h": 32},
  "rotated": false,
  "trimmed": false,
  "spriteSourceSize": {"x": 0, "y": 0, "w": 32, "h": 32},
  "sourceSize": {"w": 32, "h": 32},
  "duration": 100
}

Fields Explained:

  • filename: Logical frame identifier
  • frame: Position and size in spritesheet (pixels)
  • rotated: Whether frame is rotated 90° (packed layouts)
  • trimmed: Whether transparent pixels were removed
  • spriteSourceSize: Position within original canvas if trimmed
  • sourceSize: Original canvas size before trimming
  • duration: Frame duration in milliseconds

Meta Information:

{
  "app": "Aseprite",
  "version": "1.3.x",
  "format": "RGBA8888",
  "size": {"w": 256, "h": 128},
  "scale": "1",
  "frameTags": [
    {"name": "idle", "from": 0, "to": 3, "direction": "forward"},
    {"name": "run", "from": 4, "to": 11, "direction": "forward"}
  ]
}

Common Export Patterns

Pattern 1: Single Frame Export

Scenario: User wants just one frame as PNG

1. mcp__aseprite__get_sprite_info (verify frame exists)
2. mcp__aseprite__export_png:
   - file_path: "/output/frame.png"
   - frame_number: 0 (or user-specified)
   - scale: 1 (or user-specified)
3. Confirm export with dimensions

Pattern 2: Full Animation GIF

Scenario: User wants animated GIF of entire sprite

1. mcp__aseprite__get_sprite_info (verify frames > 1)
2. mcp__aseprite__export_gif:
   - file_path: "/output/animation.gif"
   - loop: true
   - scale: 2
3. Report frame count and file size

Pattern 3: Game-Ready Spritesheet

Scenario: User wants spritesheet for Unity/Godot

1. mcp__aseprite__get_sprite_info (check dimensions and frames)
2. Ask about target engine if not specified
3. mcp__aseprite__export_spritesheet:
   - file_path: "/output/spritesheet.png"
   - layout: "grid"
   - include_json: true
   - padding: 1
   - scale: 1
4. Provide integration instructions for target engine

Pattern 4: Specific Animation Tag

Scenario: User wants to export just one animation (e.g., "run")

1. mcp__aseprite__get_sprite_info (verify tag exists)
2. mcp__aseprite__export_spritesheet or export_gif:
   - animation_tag: "run"
   - Other settings as appropriate
3. Confirm only tagged frames exported

Pattern 5: Multi-Resolution Export

Scenario: User wants multiple scales (1x, 2x, 4x)

1. Export PNG/spritesheet at scale: 1
2. Export PNG/spritesheet at scale: 2
3. Export PNG/spritesheet at scale: 4
4. Organize files: sprite_1x.png, sprite_2x.png, sprite_4x.png
5. Report all outputs with dimensions

Pattern 6: Layer-Specific Export

Scenario: User wants individual layers as separate files

1. mcp__aseprite__get_sprite_info (get layer names)
2. For each layer:
   - mcp__aseprite__export_png:
     - layer: "LayerName"
     - file_path: "/output/layerName.png"
3. Report all exported layers

Integration with Other Skills

Pixel Art Creator Integration

Workflow: Create → Export

1. User creates sprite with Pixel Art Creator Skill
2. Automatically offer export options when creation complete
3. Suggest appropriate format based on sprite type (static vs animated)
4. Use this Skill to handle export

Pixel Art Animator Integration

Workflow: Animate → Export

1. User creates animation with Pixel Art Animator Skill
2. When animation complete, offer export formats:
   - GIF for web/social
   - Spritesheet for games
3. Use this Skill for export with animation metadata

Pixel Art Professional Integration

Workflow: Optimize → Export

1. User applies professional techniques (dithering, palette optimization)
2. Export with optimized settings:
   - Preserve palette for GIF export
   - Use appropriate compression for PNG
3. This Skill handles format-specific optimization

Error Handling

File Path Issues

Problem: Invalid or inaccessible output path

Solution:

1. Verify directory exists (create if needed using Bash)
2. Check write permissions
3. Use absolute paths, not relative
4. Suggest valid path if user provides invalid one

Missing Frames or Tags

Problem: User requests frame/tag that doesn't exist

Solution:

1. Use get_sprite_info to verify available frames and tags
2. List available options to user
3. Ask user to clarify which frame/tag they want
4. Don't attempt export until valid selection made

Large File Warnings

Problem: Export will create very large file (GIF >5MB, PNG >10MB)

Solution:

1. Calculate approximate size based on dimensions and frame count
2. Warn user before export if size exceeds thresholds
3. Suggest alternatives:
   - Reduce scale factor
   - Export fewer frames
   - Use spritesheet instead of GIF
   - Optimize palette

Format Limitations

Problem: User requests feature not supported by format (e.g., GIF transparency)

Solution:

1. Explain format limitation clearly
2. Suggest alternative format or approach
3. Proceed with export noting the limitation
4. Examples:
   - GIF binary transparency → suggest PNG for partial alpha
   - GIF 256-color limit → suggest palette optimization first

Scale Factor Issues

Problem: Non-integer scale or excessive scaling

Solution:

1. Only accept integer scale factors (1, 2, 3, 4, etc.)
2. Warn if scale >4 (may create very large files)
3. Explain pixel-perfect scaling benefits
4. Suggest appropriate scale for user's use case

Success Indicators

Export completed successfully when:

  1. File Created: Output file exists at specified path
  2. Correct Format: File extension matches requested format (.png, .gif)
  3. Expected Dimensions: Scaled dimensions are correct (originalSize * scale)
  4. Frame Count Match: Spritesheet or GIF contains expected number of frames
  5. JSON Generated: Metadata file created if include_json was true
  6. User Confirmation: User can open and verify exported file

Report to User:

✓ Export complete: /path/to/output.png
  - Format: PNG with transparency
  - Dimensions: 64x64 (2x scale from 32x32 original)
  - Frames: 1 (static image)
  - File size: ~8KB

[For spritesheets, also include:]
  - Layout: Grid (4x2)
  - Frame dimensions: 32x32 each
  - Total frames: 8
  - JSON metadata: /path/to/output.json
  - Integration: Ready for Unity/Godot import

[Provide relevant integration code snippet if applicable]

Post-Export Guidance:

  • Suggest next steps (import to engine, optimize file size, create additional scales)
  • Offer integration code for target platform
  • Explain how to use JSON metadata
  • Recommend testing in target environment

Pixel Art Professional

Overview

This Skill provides advanced pixel art techniques for refining and polishing sprites. It handles dithering patterns, palette optimization, color theory, shading techniques, and antialiasing for professional-quality pixel art.

When to Use

Use this Skill when the user:

  • Wants to apply "dithering" or mentions dither patterns
  • Asks about "palette optimization" or "color reduction"
  • Mentions "shading", "highlights", "shadows", or "lighting"
  • Requests "antialiasing", "smoothing", or "edge refinement"
  • Talks about "color ramps", "gradients", or "color theory"
  • Wants to "polish" or "refine" existing pixel art
  • Mentions specific techniques like "Bayer dithering" or "Floyd-Steinberg"

Trigger Keywords: dithering, palette, shading, antialiasing, smooth, gradient, color ramp, polish, refine, color theory, quantize

Instructions

1. Understanding Dithering

Dithering creates the illusion of additional colors by mixing pixels of available colors in patterns.

When to Use Dithering:

  • Reducing color count (e.g., 256 colors → 16 colors)
  • Creating smooth gradients with limited palettes
  • Simulating textures (fabric, metal, stone)
  • Retro aesthetic (classic games used dithering extensively)

Dithering Algorithms:

Ordered Dithering (Bayer Matrix):

  • Uses fixed pattern matrix (2x2, 4x4, 8x8)
  • Predictable, regular pattern
  • Best for: textures, backgrounds, retro look
  • Fast and consistent

Error Diffusion (Floyd-Steinberg):

  • Distributes color error to neighboring pixels
  • More organic, less regular pattern
  • Best for: gradients, natural images, smooth transitions
  • Slower but higher quality

Common Dithering Patterns:

  • Checkerboard: Simple 2-color alternating pattern
  • Bayer 2x2: Basic ordered dithering
  • Bayer 4x4: More subtle ordered dithering
  • Bayer 8x8: Very subtle, near-gradient appearance
  • Floyd-Steinberg: Error diffusion for smooth gradients

2. Palette Management

Color Quantization: Use mcp__aseprite__quantize_palette to reduce sprite colors intelligently:

  • Analyzes sprite colors
  • Finds optimal limited palette
  • Remaps pixels to new palette
  • Preserves visual quality

Palette Optimization Workflow:

  1. Get current sprite info and palette
  2. Decide target color count (4, 8, 16, 32, 64, 256)
  3. Apply quantization with optional dithering
  4. Review and adjust palette if needed

Common Palette Sizes:

  • 4 colors: Game Boy, ZX Spectrum per-sprite
  • 8 colors: CGA, early arcade
  • 16 colors: NES, Master System, early VGA
  • 32 colors: SNES per-background, Amiga OCS
  • 64 colors: Genesis, PC Engine
  • 256 colors: VGA, SNES full palette, Amiga AGA

Palette Theory:

  • Color Ramps: Gradual transitions from dark to light for shading
  • Hue Shifting: Changing hue slightly in shadows/highlights for vibrant look
  • Saturation: Higher saturation in midtones, lower in shadows/highlights
  • Contrast: Ensure sufficient contrast between key elements

3. Shading Techniques

Types of Shading:

Flat Shading (No Shading):

  • Single color per surface
  • Simple, iconic look
  • Best for: UI icons, simple sprites, minimalist style

Cell Shading (Hard Shading):

  • Distinct color bands with hard edges
  • 2-3 colors per surface (base, shadow, highlight)
  • Best for: cartoon style, bold graphics, readable sprites

Soft Shading (Dithered Shading):

  • Gradual transitions using dithering
  • Smooth appearance with limited colors
  • Best for: realistic look, smooth surfaces, gradients

Pixel Clusters:

  • Manual dithering with strategic pixel placement
  • Organic, hand-crafted appearance
  • Best for: metal, fabric textures, custom look

Shading Workflow:

  1. Identify light source direction
  2. Determine base color
  3. Create darker shade for shadows (hue shift toward blue/purple)
  4. Create lighter shade for highlights (hue shift toward yellow/white)
  5. Apply shadows on surfaces away from light
  6. Apply highlights on surfaces toward light
  7. Add reflected light in deep shadows (subtle)

Common Shading Mistakes:

  • Pure black shadows (use dark hue-shifted colors instead)
  • Pure white highlights (use light tinted colors instead)
  • No hue shifting (shadows/highlights same hue as base)
  • Pillow shading (shading around edges instead of from light source)

4. Antialiasing

Purpose: Smooth jagged edges and diagonal lines by adding intermediate colors.

When to Use Antialiasing:

  • Diagonal lines look jagged
  • Curves appear stepped
  • Edges need smoothing
  • Higher resolution sprites (64x64+)

When NOT to Use Antialiasing:

  • Very small sprites (16x16 or smaller)
  • Intentional pixelated aesthetic
  • High-contrast situations (AA reduces contrast)
  • Limited palette (need intermediate colors)

Manual Antialiasing Technique:

  1. Identify jagged edge
  2. Find intermediate color between edge and background
  3. Place intermediate pixels at edge "steps"
  4. Use 1-pixel wide AA (avoid thick fuzzy edges)
  5. AA selectively (not every edge needs it)

Automated Antialiasing:

  • Some tools offer automatic edge smoothing
  • Use with caution (can blur intended sharpness)
  • Manual AA gives better control

5. Color Theory for Pixel Art

HSV/HSB Model:

  • Hue: Color type (red, blue, green, etc.)
  • Saturation: Color intensity (vivid vs. gray)
  • Value/Brightness: Lightness (dark vs. light)

Creating Color Ramps:

  1. Start with base color (midtone)
  2. Create shadow: lower value, optionally shift hue toward cool (blue/purple)
  3. Create highlight: raise value, optionally shift hue toward warm (yellow/white)
  4. Create midtone between base and shadow
  5. Create midtone between base and highlight
  6. Result: 5-color ramp (deep shadow, shadow, base, highlight, bright highlight)

Hue Shifting:

  • Shadows: shift toward blue, purple, or complementary color
  • Highlights: shift toward yellow, orange, or light source color
  • Creates vibrant, lively colors instead of flat gradients

Contrast:

  • Ensure important elements have high value contrast
  • Background should contrast with foreground
  • Silhouette should be readable in solid black

Color Harmony:

  • Monochromatic: Variations of single hue
  • Analogous: Adjacent hues on color wheel
  • Complementary: Opposite hues on color wheel
  • Triadic: Three evenly spaced hues

6. Professional Workflows

Workflow 1: Palette Reduction with Dithering

User Request: "Reduce this sprite to 16 colors with dithering"

Approach:

  1. Get current sprite info
  2. Check current palette size
  3. Use mcp__aseprite__quantize_palette with:
    • target_colors: 16
    • algorithm: "median_cut" or "kmeans"
    • dither: true (enables Floyd-Steinberg dithering)
  4. Review result and adjust if needed

Workflow 2: Adding Shading to Flat Sprite

User Request: "Add shading to this sprite with light from top-left"

Option A - Automatic Shading (Quick):

  1. Use mcp__aseprite__apply_auto_shading with:
    • light_direction: "top_left"
    • intensity: 0.3-0.7 (adjust to preference)
    • style: "smooth", "hard", or "pillow"
    • hue_shift: true (for vibrant results)
  2. Tool automatically detects regions and adds shading
  3. Review and manually refine if needed

Option B - Manual Shading (Precise):

  1. Analyze sprite structure
  2. Identify base colors
  3. Create shadow colors (darker, hue-shifted)
  4. Create highlight colors (lighter, hue-shifted)
  5. Update palette with new colors
  6. Draw shadows on bottom-right surfaces
  7. Draw highlights on top-left surfaces
  8. Add subtle reflected light in deep shadows

Workflow 3: Smoothing Jagged Edges

User Request: "Smooth out the edges on this character"

Approach:

  1. Identify jagged diagonal lines and curves
  2. Find edge color and background color
  3. Create intermediate colors (1-2 shades between)
  4. Place AA pixels at edge steps
  5. Review and refine (avoid over-smoothing)

Workflow 4: Converting to Retro Palette (Full Palette Conversion)

User Request: "Convert this to NES palette"

Approach:

  1. Use mcp__aseprite__quantize_palette with retro palette colors
  2. Specify target palette (e.g., 54 NES colors, 4 Game Boy colors, 16 C64 colors)
  3. Algorithm maps each pixel to nearest palette color
  4. Pixels are remapped to new palette indices
  5. Optionally apply dithering for smoother transitions
  6. Verify all colors match target palette

IMPORTANT: Use quantize_palette, NOT set_palette. The set_palette tool only replaces the color table without remapping pixel data, which will produce incorrect colors in indexed mode.

Example:

quantize_palette(
  sprite_path: "sprite.aseprite",
  target_colors: 54,  # NES full palette
  algorithm: "median_cut",
  convert_to_indexed: true,
  dither: false  # or true for Bayer dithering
)

7. Dithering Patterns Reference

2-Color Patterns:

Checkerboard (50% mix):

A B A B
B A B A
A B A B
B A B A

25% Pattern:

A A B A
A A A A
B A A A
A A A A

75% Pattern:

B B A B
B B B B
A B B B
B B B B

Bayer 2x2:

Threshold matrix:
0 2
3 1

If pixel value > threshold, use lighter color

Bayer 4x4:

 0  8  2 10
12  4 14  6
 3 11  1  9
15  7 13  5

Note: See dithering-patterns.md for comprehensive pattern library.

8. Technical Details

Quantization Parameters:

  • Target colors: 2-256
  • Dithering: optional, specify algorithm
  • Alpha handling: preserve transparency or flatten

Palette Constraints:

  • RGB mode: No palette constraints
  • Indexed mode: Max 256 colors
  • Grayscale: 256 shades of gray

Performance:

  • Quantization: ~100-500ms depending on sprite size
  • Dithering: ~200-800ms depending on algorithm and size
  • Manual pixel operations: <50ms per operation

9. Common Patterns

Pattern: Quick Polish For "make this look better" requests:

  1. Check palette (reduce if too many colors)
  2. Add basic shading (light source from top-left)
  3. Add selective antialiasing on curves
  4. Adjust contrast if needed

Pattern: Retro Conversion For "make this look retro" requests:

  1. Reduce to appropriate palette (4, 8, or 16 colors)
  2. Apply ordered dithering (Bayer)
  3. Remove antialiasing (make edges sharp)
  4. Ensure pixel-perfect alignment

Pattern: Smooth Gradient For "smooth out the colors" requests:

  1. Analyze color distribution
  2. Apply Floyd-Steinberg dithering
  3. Optional: slight quantization to clean up palette
  4. Verify smooth transitions

Integration with Other Skills

  • Start with pixel-art-creator for base sprite before polishing
  • Use pixel-art-animator for animation, then polish with this Skill
  • Hand off to pixel-art-exporter when refinement is complete

Error Handling

Quantization fails:

  • Target color count must be 2-256
  • Sprite must have content (not blank)

Dithering issues:

  • Requires sufficient color depth
  • May not work well with very limited palettes
  • Some algorithms better for certain content

Palette conflicts:

  • Indexed mode has strict limits
  • Converting to indexed may require quantization first

Success Indicators

You've successfully used this Skill when:

  • Dithering applied produces smooth gradients or textures
  • Palette reduced while preserving visual quality
  • Shading adds depth and dimension
  • Antialiasing smooths edges without blurring
  • Colors follow good color theory principles
  • Sprite has professional, polished appearance

Commands 6

Commands

This directory contains slash commands that users invoke directly in Claude Code.

Available Commands

/pixel-new

Create a new pixel art sprite with optional size and palette presets.

Usage: /pixel-new [size] [palette]

Size presets:

  • icon - 32x32
  • small - 48x48
  • medium - 64x64 (default)
  • large - 128x128
  • tile - 16x16
  • gameboy - 160x144
  • nes - 256x240

Palette presets:

  • retro - 16-color generic palette
  • nes - 54-color NES palette
  • gameboy - 4-color Game Boy palette
  • c64 - 16-color Commodore 64 palette
  • cga - 4-color CGA palette
  • snes - 256-color SNES palette

Examples:

/pixel-new
/pixel-new icon
/pixel-new 128x128 nes
/pixel-new gameboy gameboy

/pixel-palette

Manage sprite color palettes.

Usage: /pixel-palette <action> [args]

Actions:

  • set <preset> - Apply a preset palette
  • optimize <colors> - Reduce palette to N colors
  • show - Display current palette
  • export <file> - Save palette to file

Examples:

/pixel-palette set nes
/pixel-palette optimize 16
/pixel-palette show
/pixel-palette export my-palette.pal

/pixel-export

Export sprite to various formats.

Usage: /pixel-export <format> [file] [options]

Formats:

  • png - Single frame PNG
  • gif - Animated GIF
  • sheet - Spritesheet
  • json - Metadata file

Options:

  • scale=N - Pixel-perfect scaling (1, 2, 4, 8)
  • fps=N - Frame rate for GIF
  • layout=type - Spritesheet layout (horizontal, vertical, grid, packed)
  • format=type - JSON format (aseprite, unity, godot, phaser)

Examples:

/pixel-export png sprite.png
/pixel-export gif animation.gif fps=12
/pixel-export sheet characters.png layout=grid
/pixel-export png icon.png scale=4

/pixel-setup

Configure the Aseprite MCP server.

Usage: /pixel-setup [path]

Auto-detects Aseprite installation or accepts manual path.

Platform paths:

  • macOS: /Applications/Aseprite.app/Contents/MacOS/aseprite
  • Linux: /usr/bin/aseprite
  • Windows: C:\Program Files\Aseprite\Aseprite.exe

Examples:

/pixel-setup
/pixel-setup /usr/local/bin/aseprite

/pixel-help

Display help information.

Usage: /pixel-help [topic]

Topics:

  • palettes - Available color palettes
  • export - Export formats and options
  • animation - Animation features
  • shortcuts - Common workflows

Examples:

/pixel-help
/pixel-help palettes
/pixel-help export

Command Structure

Each command is a markdown file with YAML frontmatter:

---
description: Brief description shown in /help
argument-hint: [arg1] [arg2]
allowed-tools: Tool1, Tool2, mcp__aseprite__*
---

Commands use $ARGUMENTS to access user input and can execute MCP tools to interact with Aseprite.

MCP Tools Used

Commands use these pixel-mcp tools:

  • mcp__aseprite__create_canvas - Create new sprites
  • mcp__aseprite__set_palette - Set color palettes
  • mcp__aseprite__export_sprite - Export to files
  • mcp__aseprite__get_sprite_info - Query sprite properties

See the pixel-mcp documentation for the full list of available tools.

/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

/pixel-help - Plugin Help

Display help information for the Aseprite Pixel Art Plugin.

Usage

/pixel-help [command-name]

Arguments

command-name (optional): Specific command or topic

  • If not provided, shows general overview
  • If provided, shows detailed help for that command/skill

Examples

/pixel-help
→ Shows general plugin overview and command list

/pixel-help pixel-new
→ Shows detailed help for /pixel-new command

/pixel-help palettes
→ Shows information about available palettes

/pixel-help export
→ Shows export formats and options

General Help Output

When called without arguments:

# Aseprite Pixel Art Plugin

Create, edit, and export pixel art using natural language or commands.

## Quick Start

1. Setup (first time only):
   /pixel-setup

2. Create a sprite:
   /pixel-new 64x64
   or: "Create a 32x32 pixel art sprite"

3. Add content:
   "Draw a red circle in the center"
   "Add a walk cycle animation with 4 frames"

4. Export:
   /pixel-export png sprite.png

## Commands

/pixel-new [size] [palette]      - Create new sprite with presets
/pixel-palette <action> [args]   - Manage color palettes
/pixel-export <format> [file]    - Export sprite
/pixel-setup [path]              - Configure plugin
/pixel-help [topic]              - Show this help

## Skills (Natural Language)

The plugin responds to natural language requests:

- **Creation**: "Create a 64x64 sprite", "Make a new canvas"
- **Animation**: "Add 4 frames", "Create a walk cycle"
- **Advanced**: "Apply dithering", "Optimize palette to 16 colors"
- **Export**: "Export as GIF", "Create a spritesheet"

## Topics

/pixel-help palettes            - Available color palettes
/pixel-help export              - Export formats and options
/pixel-help animation           - Animation features
/pixel-help shortcuts           - Common workflows

## Examples

"Create a 32x32 Game Boy style sprite"
"Add a simple idle animation"
"Export as a horizontal spritesheet"
"Apply NES palette and dither"

## Documentation

See ~/.claude-plugins/pixel-plugin/ for full documentation.

Topic-Specific Help

For command names (pixel-new, pixel-palette, etc.):

  1. Read corresponding command file from commands/
  2. Extract usage, examples, and options
  3. Display in readable format

For "palettes" topic:

# Color Palettes

## Retro Console Palettes

NES (54 colors)        - Nintendo Entertainment System
Game Boy (4 colors)    - Original Game Boy green palette
Game Boy Gray (4)      - Grayscale Game Boy Pocket
C64 (16 colors)        - Commodore 64
CGA (4 colors)         - IBM CGA
SNES (256 colors)      - Super Nintendo

## Modern Palettes

PICO-8 (16 colors)     - Fantasy console palette
Sweetie 16             - Popular 16-color palette by GrafxKid
DB16                   - DawnBringer's 16-color palette
DB32                   - DawnBringer's 32-color palette

## Usage

/pixel-palette set nes
/pixel-palette set gameboy
/pixel-new 64x64 pico8

## Custom Palettes

/pixel-palette set custom #000000,#ffffff,#ff0000,#00ff00

See /pixel-help pixel-palette for more details.

For "export" topic:

# Export Formats

## Formats

PNG       - Single frame or current frame
GIF       - Animated GIF with all frames
Sheet     - Spritesheet (multiple layouts)
JSON      - Metadata for game engines

## Layouts (Spritesheet)

horizontal  - All frames in a row
vertical    - All frames in a column
grid        - Optimal grid layout
packed      - Space-optimized layout

## Scaling

scale=1     - Original size (1x)
scale=2     - 2x size (pixel-perfect)
scale=4     - 4x size
scale=8     - 8x size

## Examples

/pixel-export png sprite.png scale=4
/pixel-export gif animation.gif fps=12
/pixel-export sheet spritesheet.png layout=grid
/pixel-export json sprite.json format=unity

See /pixel-help pixel-export for more details.

For "animation" topic:

# Animation Features

## Natural Language

"Add 4 frames for a walk cycle"
"Create an idle animation with 2 frames"
"Set frame duration to 100ms"
"Create animation tag 'walk' for frames 1-4"

## Frame Management

- Add frames
- Delete frames
- Duplicate frames
- Set frame duration (timing)

## Animation Tags

Tags organize frames into named sequences:
- "idle" (frames 1-2)
- "walk" (frames 3-6)
- "jump" (frames 7-10)

## Linked Cels

Share image data across frames for efficiency:
- Static background layers
- Repeated frames
- Memory optimization

## Common Animations

Idle (2-4 frames)       - Subtle breathing/bobbing
Walk (4-8 frames)       - Left-right foot alternation
Run (6-8 frames)        - Faster, exaggerated walk
Jump (4-6 frames)       - Crouch, ascend, peak, descend, land
Attack (3-6 frames)     - Windup, strike, recovery

See pixel-art-animator skill documentation for details.

For "shortcuts" topic:

# Common Workflows

## Quick Sprite Creation

/pixel-new icon gameboy
→ Creates 32x32 sprite with Game Boy palette

## Retro Game Sprite

1. /pixel-new 64x64 nes
2. "Draw a character"
3. "Add a 4-frame walk cycle"
4. /pixel-export sheet spritesheet.png layout=horizontal

## Modern Pixel Art

1. /pixel-new large
2. "Draw detailed portrait"
3. "Apply soft shading from top-left"
4. /pixel-export png portrait.png scale=2

## Optimize Existing Sprite

1. "Open sprite.png"
2. /pixel-palette optimize 16
3. "Apply Floyd-Steinberg dithering"
4. /pixel-export png optimized.png

## Animated GIF

1. /pixel-new 64x64
2. "Create 8-frame run cycle"
3. "Set all frames to 80ms duration"
4. /pixel-export gif running.gif fps=12

## Game Engine Export

1. Create and animate sprite
2. /pixel-export json sprite.json format=unity
3. Import sprite.png and sprite.json into Unity

Implementation

Parse $ARGUMENTS:

If no arguments:

  1. Display general help (command list, quick start, examples)
  2. Show all available commands
  3. List help topics
  4. Provide documentation links

If command name provided:

  1. Check if matches slash command (pixel-new, pixel-palette, etc.)
  2. If yes, read command file and display usage/examples
  3. If no, check if matches topic (palettes, export, animation, shortcuts)
  4. If topic, display topic-specific help
  5. If neither, suggest similar topics or show general help

Reading command files:

  1. Use Read tool to load commands/{command-name}.md
  2. Extract description, usage, examples sections
  3. Format for display

Formatting:

  • Use clear headings and sections
  • Include code examples with syntax highlighting
  • Show command usage patterns
  • Provide related commands and topics

Notes

  • Help is context-aware (shows relevant examples)
  • Command help extracted from actual command files
  • Topics provide grouped information
  • Examples are actionable (copy-paste ready)
  • Links to full documentation files when available

/pixel-new - Quick Sprite Creation

Creates a new pixel art sprite with optional presets for size and palette.

Usage

/pixel-new [size] [palette]

Arguments

size (optional): Canvas dimensions or preset name

  • Presets: icon, small, medium, large, tile, gameboy, nes
  • Custom: WIDTHxHEIGHT (e.g., 64x64, 128x96)
  • Default: 64x64

palette (optional): Color palette preset

  • retro, nes, gameboy, c64, cga, snes, custom
  • Default: RGB (no palette limit)

Examples

/pixel-new
→ Creates 64x64 RGB canvas

/pixel-new icon
→ Creates 32x32 RGB canvas

/pixel-new gameboy gameboy
→ Creates 160x144 canvas with Game Boy 4-color palette

/pixel-new 128x128 nes
→ Creates 128x128 canvas with NES palette

/pixel-new tile retro
→ Creates 16x16 canvas with retro 16-color palette

Size Presets

  • icon: 32x32 (for icons, small sprites)
  • small: 48x48 (characters, items)
  • medium: 64x64 (default, versatile)
  • large: 128x128 (detailed sprites, portraits)
  • tile: 16x16 (tilemap tiles)
  • gameboy: 160x144 (Game Boy screen resolution)
  • nes: 256x240 (NES screen resolution)

Palette Presets

  • retro: 16-color palette (generic retro aesthetic)
  • nes: 54-color NES palette
  • gameboy: 4-color Game Boy palette (#0f380f, #306230, #8bac0f, #9bbc0f)
  • c64: 16-color Commodore 64 palette
  • cga: 4-color CGA palette
  • snes: 256-color SNES-style palette
  • custom: Prompts for custom palette colors

Implementation

Parse arguments from $ARGUMENTS:

  1. Extract size argument (first arg)
  2. Extract palette argument (second arg)
  3. Map size preset to dimensions or parse WxH
  4. Create canvas with mcp__aseprite__create_canvas
  5. If palette specified, set palette with mcp__aseprite__set_palette
  6. Confirm creation with sprite info

Size Preset Mapping

icon     → 32x32
small    → 48x48
medium   → 64x64
large    → 128x128
tile     → 16x16
gameboy  → 160x144
nes      → 256x240

Palette Details

retro (16 colors):

  • Generic retro palette with balanced colors
  • Good for general pixel art without console constraints

nes (54 colors):

  • Official NES/Famicom palette
  • Use indexed color mode
  • Typically limit to 4 colors per sprite for authenticity

gameboy (4 colors):

  • #0f380f (darkest green)
  • #306230 (dark green)
  • #8bac0f (light green)
  • #9bbc0f (lightest green)

c64 (16 colors):

  • Commodore 64 fixed palette
  • Distinctive colors with high saturation

cga (4 colors):

  • Classic IBM CGA palette
  • High contrast, limited colors

snes (256 colors):

  • SNES-style palette with rich colors
  • Supports smooth gradients and detailed sprites

custom:

  • Prompts user for custom colors
  • Ask for number of colors and hex values

Validation

Size validation:

  • If preset name, map to dimensions
  • If WxH format, parse width and height
  • Ensure dimensions are 1-65535
  • Reject invalid formats

Palette validation:

  • Check if preset exists
  • For custom, validate hex color format
  • Ensure palette is appropriate for sprite size

Error Handling

Invalid size:

  • "Invalid size format. Use a preset (icon, small, medium, large, tile, gameboy, nes) or WIDTHxHEIGHT (e.g., 64x64)"

Invalid palette:

  • "Invalid palette. Choose from: retro, nes, gameboy, c64, cga, snes, custom"

Dimensions out of range:

  • "Dimensions must be between 1 and 65535 pixels"

Canvas creation fails:

  • Report MCP error and suggest checking Aseprite configuration

Notes

  • If no arguments, create default 64x64 RGB canvas
  • For retro palettes, use Indexed color mode
  • For RGB mode, no palette needed
  • Validate dimensions (1-65535)
  • Provide helpful error messages for invalid input
  • After creation, confirm canvas size and palette
  • Use mcp__aseprite__get_sprite_info to verify creation

Command Flow

  1. Parse $ARGUMENTS into size and palette
  2. If no size, use default (64x64)
  3. Map size preset to dimensions or parse WxH
  4. Validate dimensions
  5. Call mcp__aseprite__create_canvas with dimensions
  6. If palette specified:
    • Map palette preset to color list
    • Call mcp__aseprite__set_palette with colors
  7. Get sprite info to confirm
  8. Report success with canvas details

Example Outputs

Success with default:

Created 64x64 RGB canvas.
Ready for pixel art creation!

Success with presets:

Created 160x144 canvas with Game Boy palette (4 colors).
Perfect for Game Boy-style sprites!

Success with custom size and palette:

Created 128x128 canvas with NES palette (54 colors).
Canvas ready with retro NES colors!

/pixel-palette - Palette Management

Manage sprite color palettes with presets, optimization, and custom palettes.

Usage

/pixel-palette <action> [palette-name|color-count]

Actions

set - Set palette to a preset or custom colors

/pixel-palette set nes
/pixel-palette set gameboy
/pixel-palette set custom #000000,#ffffff,#ff0000

optimize - Reduce colors to optimal palette

/pixel-palette optimize 16
/pixel-palette optimize 32

show - Display current palette

/pixel-palette show

export - Export current palette to file

/pixel-palette export my-palette.gpl

Palette Presets

Retro Consoles:

  • nes: 54-color NES palette
  • gameboy: 4-color Game Boy palette (#0f380f, #306230, #8bac0f, #9bbc0f)
  • gameboy-gray: 4-shade grayscale Game Boy
  • c64: 16-color Commodore 64 palette
  • cga: 4-color CGA palette
  • snes: Rich 256-color SNES-style palette

Generic Palettes:

  • retro16: Generic 16-color retro palette
  • retro8: Generic 8-color palette
  • retro4: Generic 4-color palette
  • grayscale4: 4 shades of gray
  • grayscale8: 8 shades of gray
  • grayscale16: 16 shades of gray

Modern Palettes:

  • pico8: PICO-8 fantasy console 16-color palette
  • sweetie16: Popular 16-color palette by GrafxKid
  • db16: DawnBringer's 16-color palette
  • db32: DawnBringer's 32-color palette

Examples

/pixel-palette set nes
→ Sets sprite to NES 54-color palette (indexed mode)

/pixel-palette optimize 16
→ Reduces sprite to optimal 16 colors

/pixel-palette set custom #000000,#ffffff,#ff0000,#00ff00,#0000ff
→ Sets custom 5-color palette

/pixel-palette show
→ Displays current palette colors

/pixel-palette set pico8
→ Sets PICO-8 16-color palette

Palette Definitions

NES Palette (54 colors):

#7C7C7C, #0000FC, #0000BC, #4428BC, #940084, #A80020, #A81000, #881400,
#503000, #007800, #006800, #005800, #004058, #000000, #000000, #000000,
#BCBCBC, #0078F8, #0058F8, #6844FC, #D800CC, #E40058, #F83800, #E45C10,
#AC7C00, #00B800, #00A800, #00A844, #008888, #000000, #000000, #000000,
#F8F8F8, #3CBCFC, #6888FC, #9878F8, #F878F8, #F85898, #F87858, #FCA044,
#F8B800, #B8F818, #58D854, #58F898, #00E8D8, #787878, #000000, #000000,
#FCFCFC, #A4E4FC, #B8B8F8, #D8B8F8, #F8B8F8, #F8A4C0, #F0D0B0, #FCE0A8,
#F8D878, #D8F878, #B8F8B8, #B8F8D8, #00FCFC, #F8D8F8, #000000, #000000

Game Boy Palette:

#0f380f (darkest green)
#306230 (dark green)
#8bac0f (light green)
#9bbc0f (lightest green)

PICO-8 Palette:

#000000, #1D2B53, #7E2553, #008751, #AB5236, #5F574F, #C2C3C7, #FFF1E8,
#FF004D, #FFA300, #FFEC27, #00E436, #29ADFF, #83769C, #FF77A8, #FFCCAA

DawnBringer 16:

#140c1c, #442434, #30346d, #4e4a4e, #854c30, #346524, #d04648, #757161,
#597dce, #d27d2c, #8595a1, #6daa2c, #d2aa99, #6dc2ca, #dad45e, #deeed6

DawnBringer 32:

#000000, #222034, #45283c, #663931, #8f563b, #df7126, #d9a066, #eec39a,
#fbf236, #99e550, #6abe30, #37946e, #4b692f, #524b24, #323c39, #3f3f74,
#306082, #5b6ee1, #639bff, #5fcde4, #cbdbfc, #ffffff, #9badb7, #847e87,
#696a6a, #595652, #76428a, #ac3232, #d95763, #d77bba, #8f974a, #8a6f30

Commodore 64 Palette:

#000000 (black), #ffffff (white), #880000 (red), #aaffee (cyan),
#cc44cc (purple), #00cc55 (green), #0000aa (blue), #eeee77 (yellow),
#dd8855 (orange), #664400 (brown), #ff7777 (light red), #333333 (dark gray),
#777777 (gray), #aaff66 (light green), #0088ff (light blue), #bbbbbb (light gray)

CGA Palette:

#000000 (black), #00aaaa (cyan), #aa00aa (magenta), #aaaaaa (white)

Implementation

Parse $ARGUMENTS to determine action:

For "set" action:

  1. Check if argument is preset name
  2. If preset, load predefined palette colors
  3. If "custom", parse comma-separated hex colors
  4. Use mcp__aseprite__set_palette with color array
  5. Convert sprite to Indexed mode if needed
  6. Confirm palette set

For "optimize" action:

  1. Parse target color count from argument
  2. Use mcp__aseprite__quantize_colors with count
  3. Show before/after color counts
  4. Confirm optimization

For "show" action:

  1. Use mcp__aseprite__get_palette
  2. Display colors in readable format (hex codes)
  3. Show color count

For "export" action:

  1. Get palette with mcp__aseprite__get_palette
  2. Format as .gpl (GIMP Palette) or .pal file
  3. Write to specified file path
  4. Confirm export

GIMP Palette Format (.gpl)

GIMP Palette
Name: My Palette
Columns: 4
#
0   0   0   Black
255 255 255 White
255 0   0   Red

Validation

For set action:

  • Validate preset name exists
  • For custom, validate hex color format (#RRGGBB)
  • Ensure palette fits indexed mode limits (max 256 colors)

For optimize action:

  • Target color count must be 2-256
  • Cannot optimize blank/empty sprites

For export action:

  • Validate file path and permissions
  • Ensure output directory exists

Error Handling

Invalid action:

Invalid action. Use: set, optimize, show, or export

Invalid preset:

Unknown palette preset: xyz
Available: nes, gameboy, c64, pico8, db16, db32, etc.

Optimization failed:

Cannot optimize: sprite has no content or target color count invalid (2-256)

Export failed:

Cannot export palette to: /path/file.gpl
Check path and permissions.

Notes

  • Setting palette converts sprite to Indexed color mode
  • Optimize action reduces colors while preserving visual quality
  • Custom palettes: comma-separated hex colors (#RRGGBB)
  • Palette files use .gpl (GIMP) or .pal (Adobe) format
  • Maximum 256 colors for indexed mode
  • Show action displays colors in grid format
  • Export creates portable palette files

Tips

For retro authenticity:

  • Use NES palette with 4-color limit per sprite
  • Use Game Boy palette for monochrome green aesthetic
  • Use PICO-8 for modern retro/fantasy console look

For optimization:

  • Start with high color count (64+)
  • Gradually reduce with optimize action
  • Use quantization before dithering for best results

For custom palettes:

  • Start with base colors you need
  • Add shade variations (darker/lighter)
  • Keep count even for better organization
  • Test palette on actual sprite content

/pixel-setup - Plugin Configuration

Configure the pixel-mcp server and verify Aseprite installation.

Usage

/pixel-setup [aseprite-path]

Arguments

aseprite-path (optional): Path to Aseprite executable

  • If not provided, attempts auto-detection
  • If detection fails, prompts user for path

What This Command Does

  1. Detects Aseprite installation

    • Searches common installation paths for current platform
    • macOS: /Applications/Aseprite.app/Contents/MacOS/aseprite
    • Linux: /usr/bin/aseprite, /usr/local/bin/aseprite
    • Windows: C:\Program Files\Aseprite\Aseprite.exe
  2. Creates configuration file

    • Generates ~/.config/pixel-mcp/config.json (macOS/Linux)
    • Generates %APPDATA%\pixel-mcp\config.json (Windows)
    • Sets aseprite_path in configuration
  3. Validates configuration

    • Tests that Aseprite executable exists and is executable
    • Verifies pixel-mcp can communicate with Aseprite
    • Reports version information
  4. Tests MCP server

    • Runs health check on pixel-mcp server
    • Confirms tools are accessible
    • Reports success or errors

Examples

/pixel-setup
→ Auto-detects Aseprite installation and configures

/pixel-setup /Applications/Aseprite.app/Contents/MacOS/aseprite
→ Uses specified path for macOS

/pixel-setup "C:\Program Files\Aseprite\Aseprite.exe"
→ Uses specified path for Windows

/pixel-setup /usr/local/bin/aseprite
→ Uses specified path for Linux

Auto-Detection Paths

macOS:

  • /Applications/Aseprite.app/Contents/MacOS/aseprite
  • $HOME/Applications/Aseprite.app/Contents/MacOS/aseprite
  • /usr/local/bin/aseprite
  • $HOME/.local/bin/aseprite

Linux:

  • /usr/bin/aseprite
  • /usr/local/bin/aseprite
  • $HOME/.local/bin/aseprite
  • $HOME/bin/aseprite
  • /opt/aseprite/bin/aseprite
  • /snap/bin/aseprite

Windows:

  • C:\Program Files\Aseprite\Aseprite.exe
  • C:\Program Files (x86)\Aseprite\Aseprite.exe
  • %LOCALAPPDATA%\Aseprite\Aseprite.exe
  • %USERPROFILE%\AppData\Local\Aseprite\Aseprite.exe

Configuration File Format

Location:

  • macOS/Linux: ~/.config/pixel-mcp/config.json
  • Windows: %APPDATA%\pixel-mcp\config.json

Contents:

{
  "aseprite_path": "/path/to/aseprite",
  "temp_dir": "/tmp/pixel-mcp",
  "timeout": 30,
  "log_level": "info",
  "log_file": "",
  "enable_timing": false
}

Required Field:

  • aseprite_path: Path to Aseprite executable (only required field)

Optional Fields:

  • temp_dir: Temporary directory for MCP operations (default: system temp)
  • timeout: Command timeout in seconds (default: 30)
  • log_level: Logging level: "debug", "info", "warn", "error" (default: "info")
  • log_file: Path to log file (default: "" = no file logging)
  • enable_timing: Log operation timings for performance analysis (default: false)

Implementation

Step 1: Auto-Detection

  1. Check if aseprite-path argument provided
  2. If not, run detection script: config/detect-aseprite.sh
  3. Detection script checks common paths for current OS
  4. If found, use detected path; if not, prompt user for path

Step 2: Validate Path

  1. Check if file exists at specified path
  2. Check if file is executable
  3. Optionally run aseprite --version to verify

Step 3: Create Configuration

  1. Determine config directory based on OS
  2. Create directory if it doesn't exist: mkdir -p ~/.config/pixel-mcp
  3. Write config.json with aseprite_path and defaults
  4. Set appropriate permissions (readable/writable by user)

Step 4: Test MCP Server

  1. Run health check: ${CLAUDE_PLUGIN_ROOT}/bin/pixel-mcp --health
  2. Capture output and check for success
  3. Report Aseprite version and MCP status

Step 5: Report Results

  1. Display configuration summary
  2. Show config file location
  3. Show Aseprite path
  4. Confirm MCP server is ready
  5. Provide next steps or troubleshooting if failed

Success Output

✓ Aseprite detected at: /Applications/Aseprite.app/Contents/MacOS/aseprite
✓ Configuration created: ~/.config/pixel-mcp/config.json
✓ Aseprite version: v1.3.2
✓ MCP server ready

Plugin setup complete! You can now create pixel art with commands like:
  /pixel-new
  /pixel-palette set nes

Error Handling

Aseprite not found:

✗ Aseprite not found in common installation paths

Please install Aseprite from: https://www.aseprite.org/
Or specify the path manually: /pixel-setup /path/to/aseprite

Invalid path provided:

✗ Aseprite not found at: /invalid/path

Please check the path and try again, or run /pixel-setup without arguments for auto-detection.

Permission errors:

✗ Cannot create configuration directory: ~/.config/pixel-mcp
  Permission denied

Please check directory permissions or run with appropriate privileges.

MCP server health check failed:

✗ MCP server health check failed
  Error: [error details]

Please check that:
  1. Aseprite path is correct
  2. Aseprite is executable
  3. pixel-mcp binary has execute permissions

Troubleshooting Tips

Include in output if errors occur:

  1. Verify Aseprite is installed: https://www.aseprite.org/
  2. Check pixel-mcp binary permissions: chmod +x ${CLAUDE_PLUGIN_ROOT}/bin/pixel-mcp
  3. Manually edit config: Edit ~/.config/pixel-mcp/config.json
  4. Test Aseprite directly: Run aseprite --version in terminal
  5. Check logs: Set log_file in config for debugging

Platform-Specific Notes

macOS:

  • Aseprite.app is a bundle; executable is inside Contents/MacOS/
  • May need to grant Terminal/Claude Code permissions in System Preferences
  • If downloaded from website, may need to allow in Security & Privacy

Linux:

  • Installed via package manager: usually in /usr/bin/
  • Compiled from source: often in /usr/local/bin/
  • AppImage: specify full path to .AppImage file
  • Snap: usually in /snap/bin/

Windows:

  • Use quotes around path if it contains spaces
  • Backslashes in path are okay, or use forward slashes
  • May need to run as Administrator for some installation paths

Configuration Tips

For development:

  • Set log_level to "debug" for detailed output
  • Set log_file to save logs for troubleshooting
  • Enable enable_timing to see operation performance

For production:

  • Keep log_level at "info" (default)
  • Leave log_file empty unless debugging
  • Disable enable_timing (default)

For slow systems:

  • Increase timeout to 60 or more seconds
  • Check that Aseprite runs quickly from command line

Notes

  • Setup only needs to be run once
  • Re-run if Aseprite installation path changes
  • Configuration persists across Claude Code sessions
  • Can manually edit config.json if needed
  • Health check verifies MCP server can communicate with Aseprite
  • All subsequent commands depend on this configuration

Next Steps After Setup

Once setup is complete:

  1. Create your first sprite:

    /pixel-new 64x64
    
  2. Try natural language:

    "Create a 32x32 pixel art character"
    
  3. Explore palette presets:

    /pixel-palette set nes
    
  4. Export your work:

    /pixel-export png sprite.png scale=4
    
  5. Get help:

    /pixel-help
    

MCP servers 1

Sponsors

Details

Marketplace
willibrandon/pixel-plugin
Category
Community