dsh-sprite-gen

Sprite Sheet Generator with AI Image Generation for DeepSeek Harness.

Features

• ?? AI Image Generation - Generate sprites directly with AI
• ?? 4 Providers - Gemini Flash, Stable Diffusion, Agnes AI, ComfyUI (local)
• ?? Auto-crop - Automatically remove transparent edges
• ?? Grid Arrangement - Configurable sprite sheet layouts
• ?? Cutout + Validation - Distance-threshold background removal with bbox crop, scale, and quality checks
• ?? Animation Sequences - Multi-frame walk/jump/attack/idle with reference consistency
• ??? Parallax Backgrounds - 3-layer side-scroller backgrounds (sky/mid/foreground)
• ?? Effects Generation - Bullets, fire, explosions, smoke, sparks
• ?? Weapon/Equipment Sprites - Guns, swords, armor, helmets
• ?? Batch Generation - Generate multiple assets in one call
• ?? GIF Export - Export sprite sheets to animated GIF for preview

Supported Providers

Provider	Model	Limits	API Key
Gemini Flash	gemini-2.0-flash-exp	60/day	Required
Stable Diffusion	sdxl	100/day	Required
Agnes AI	agnes-image-2.1-flash	Free forever	Required
ComfyUI	sdxl (local)	Unlimited	Not needed

Installation

# From GitHub
dsh plugin --profile web add github:randomix777/dsh-sprite-gen

# Manual
cd ~/.dsh/profiles/web
pnpm add file:/path/to/dsh-sprite-gen

Available Tools

Core Tools

Tool	Description
sprite_config	Manage API keys, providers, and defaults
sprite_generate_image	Generate image + convert to sprite sheet
sprite_sheet	Process existing image into sprite sheet
sprite_cutout	Background cutout with validation
sprite_info	View plugin info and configuration

Animation & Effects

Tool	Description
sprite_animation_sequence	Generate multi-frame animation from reference
sprite_animation_list	List available animation types
sprite_generate_effect	Generate effect sprites (bullets, fire, etc.)
sprite_effect_list	List available effect types
sprite_generate_weapon	Generate weapon/equipment sprites
sprite_weapon_list	List available weapon types

Advanced

Tool	Description
sprite_batch_generate	Batch generate multiple AI sprites
sprite_batch_process	Batch process multiple images
sprite_generate_background	Generate 3-layer parallax backgrounds
sprite_gif_export	Export sprite sheet PNG to animated GIF
sprite_tiled_export	Export sprite sheet to Tiled editor JSON
sprite_aseprite_import	Import .aseprite files to sprite sheets/frames
sprite_tileset_batch	Slice terrain atlas into per-terrain tile variants
sprite_video2dsprite	Extract frames from video → sprite sheets + GIF
sprite_palette_quantize	Quantize to retro palettes (GameBoy, NES, Pico-8, etc.)
sprite_detect	Auto-detect sprite grid layout from PNG sheet

Character Consistency

Tool	Description
sprite_character_create	Create persistent character identity (name, description, ref image, seed)
sprite_character_get	Get character identity by ID
sprite_character_list	List all saved character identities
sprite_character_delete	Delete a character identity
sprite_character_generate	Generate sprite with character consistency (strength tuning, fixed seed)
sprite_character_sheet	Multi-view character sheet (front/side/back) with consistent appearance
sprite_character_views	List available view types for character sheet

Props & Scene Objects

Tool	Description
sprite_generate_prop_pack	Generate + extract a batch of related props (rock, barrel, torch, chest…) from a sheet
sprite_extract_prop_pack	Chroma-key extract individual props from an existing prop sheet
sprite_scene_object	Generate/extract a single game-ready scene object with collision bbox metadata
sprite_scene_object_batch	Batch-extract multiple scene objects from a multi-object sheet
sprite_anchor_layout	Build fixed-scale anchor template from accepted master frame for multi-view consistency

Terrain & Platforms

Tool	Description
sprite_tileset_batch_qc	Enhanced terrain tile bundle with edge_policy (isolated/seamless), contrast QC, pairwise PSNR variant-diff, material hints
sprite_platform_strip	Reusable side-scrolling platform strips (left/middle/right cap) with collision metadata

Preview

Tool	Description
sprite_preview_list	List recently generated sprite outputs with paths and timestamps
sprite_preview_image	Read a local image file and return as base64 data URL for client-side preview

Usage Examples

Generate Character with Animation

// 1. Generate base character
sprite_generate_image({
  prompt: "female survivor pixel art character, idle pose, detailed 32-bit pixel art",
  provider: "agnes",
  width: 1024, height: 1536,
  output_path: "./sprites/player_base.png"
})

// 2. Cutout and validate
sprite_cutout({
  image_path: "./sprites/player_base.png",
  output_path: "./sprites/player_clean.png",
  target_width: 512, target_height: 768
})

// 3. Generate walk cycle
sprite_animation_sequence({
  sequence: "player_run",
  reference_image_path: "./sprites/player_clean.png",
  output_path: "./sprites/player_run.png"
})

// 4. Generate jump animation
sprite_animation_sequence({
  sequence: "player_jump",
  reference_image_path: "./sprites/player_clean.png",
  output_path: "./sprites/player_jump.png"
})

// 5. Generate attack animation
sprite_animation_sequence({
  sequence: "player_shoot",
  reference_image_path: "./sprites/player_clean.png",
  output_path: "./sprites/player_shoot.png"
})

Generate Effects

// List available effects
sprite_effect_list()

// Generate bullet effects
sprite_generate_effect({ effect: "bullet_trail", output_path: "./effects/bullet.png" })
sprite_generate_effect({ effect: "bullet_impact", output_path: "./effects/impact.png" })
sprite_generate_effect({ effect: "fire_explosion", output_path: "./effects/explosion.png" })

Generate Weapons

// List weapons
sprite_weapon_list()

// Generate weapon sprites
sprite_generate_weapon({ weapon: "assault_rifle", output_path: "./weapons/rifle.png" })
sprite_generate_weapon({ weapon: "pistol_9mm", output_path: "./weapons/pistol.png" })

Batch Generation

// Generate multiple characters at once
sprite_batch_generate({
  provider: "agnes",
  items: [
    { prompt: "female survivor pixel art", output_path: "./sprites/female.png" },
    { prompt: "male raider pixel art", output_path: "./sprites/raider.png" },
    { prompt: "zombie enemy pixel art", output_path: "./sprites/zombie.png" },
  ]
})

Parallax Background

sprite_generate_background({
  character_prompt: "post-apocalyptic survivor in wasteland",
  character_image_url: "https://example.com/character.png",
  provider: "agnes"
})

Export to GIF

// Convert a sprite sheet PNG to animated GIF
sprite_gif_export({
  image_path: "./sprites/player_walk.png",
  output_path: "./sprites/player_walk.gif",
  fps: 12,
  grid_cols: 4,
  grid_rows: 1
})

ComfyUI (Local SD)

// Ensure ComfyUI is running on http://127.0.0.1:8188
sprite_generate_image({
  prompt: "pixel art character sprite",
  provider: "comfy",
  width: 512, height: 512
})

Configuration

// Set Agnes API key
sprite_sprite_config({
  action: "set_key",
  provider: "agnes",
  api_key: "your_key_here"
})

// Switch default provider
sprite_sprite_config({ action: "set_provider", provider: "agnes" })

// List providers
sprite_sprite_config({ action: "list" })

Godot Integration

1. Import the generated PNG into your Godot project
2. Add a SpriteFrames node
3. Create a new resource, import the PNG
4. Enable Region in the inspector
5. Set Region Rect to single cell size
6. Set H Frames and V Frames to grid dimensions

Requirements

• Node.js >= 18
• Python 3.8+
• Pillow + NumPy

pip install Pillow numpy

Development

# Install dependencies
npm install

# Build client bundle
npm run build-client

# Test
node scripts/validate.mjs

# Pack for publishing
npm pack

License

MIT