zhongwei/gh-willibrandon-pixel-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:06:21 +08:00
commit 4de211b5a8
23 changed files with 8919 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
commands/README.md Normal file
View File

@@ -0,0 +1,139 @@
# 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:
```yaml
---
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.

357
commands/pixel-export.md Normal file
View File

@@ -0,0 +1,357 @@
---
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:**
```json
{
"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:**
```json
{
"frames": {
"sprite_0.png": {
"frame": {"x": 0, "y": 0, "w": 32, "h": 32},
"sourceSize": {"w": 32, "h": 32}
}
}
}
```
**Unity Format:**
```json
{
"sprites": [
{
"name": "sprite_0",
"rect": {"x": 0, "y": 0, "width": 32, "height": 32},
"pivot": {"x": 0.5, "y": 0.5}
}
]
}
```
**Godot Format:**
```json
{
"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

296
commands/pixel-help.md Normal file
View File

@@ -0,0 +1,296 @@
---
description: Show help for pixel art commands and skills
argument-hint: [command-name]
allowed-tools: Read, Bash
---
## /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

190
commands/pixel-new.md Normal file
View File

@@ -0,0 +1,190 @@
---
description: Create a new pixel art sprite with optional size and palette presets
argument-hint: [size] [palette]
allowed-tools: Read, Bash, mcp__aseprite__create_canvas, mcp__aseprite__set_palette
---
## /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!
```

246
commands/pixel-palette.md Normal file
View File

@@ -0,0 +1,246 @@
---
description: Manage sprite palettes - set, optimize, or load preset palettes
argument-hint: <action> [palette-name|color-count]
allowed-tools: Read, Bash, mcp__aseprite__set_palette, mcp__aseprite__get_palette, mcp__aseprite__quantize_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

272
commands/pixel-setup.md Normal file
View File

@@ -0,0 +1,272 @@
---
description: Configure pixel-mcp server and verify Aseprite installation
argument-hint: [aseprite-path]
allowed-tools: Read, Write, Bash
---
## /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:**
```json
{
"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
```