精灵图生成器 randomix777/dsh-sprite-gen

dsh-sprite-gen

为 DeepSeek Harness 打造的精灵图生成器，支持 AI 图像生成。

功能

- ?? AI 图像生成 —— 直接用 AI 生成精灵图
- ?? 4 个服务商 —— Gemini Flash、Stable Diffusion、Agnes AI、ComfyUI（本地）
- ?? 自动裁剪 —— 自动去掉透明边缘
- ?? 网格排列 —— 精灵图布局可配置
- ?? 抠图 + 校验 —— 按距离阈值去背景，配合 bbox 裁剪、缩放和质量检查
- ?? 动画序列 —— 多帧 walk/jump/attack/idle，保持参考一致
- ??? 视差背景 —— 3 层横版卷轴背景（天空/中景/前景）
- ?? 特效生成 —— 子弹、火焰、爆炸、烟雾、火花
- ?? 武器/装备精灵图 —— 枪、剑、护甲、头盔
- ?? 批量生成 —— 一次调用生成多个素材
- ?? GIF 导出 —— 把精灵图导出成动图 GIF 预览

支持的服务商

| 服务商 | 模型 | 限制 | 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 |

安装

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

可用工具

核心工具

| 工具 | 说明 |
| sprite_config | 管理 API key、服务商和默认值 |
| sprite_generate_image | 生成图像 + 转成精灵图 |
| sprite_sheet | 把现有图像处理成精灵图 |
| sprite_cutout | 抠背景并校验 |
| sprite_info | 查看插件信息和配置 |

动画与特效

| 工具 | 说明 |
| sprite_animation_sequence | 按参考图生成多帧动画 |
| sprite_animation_list | 列出可用动画类型 |
| sprite_generate_effect | 生成特效精灵图（子弹、火焰等） |
| sprite_effect_list | 列出可用特效类型 |
| sprite_generate_weapon | 生成武器/装备精灵图 |
| sprite_weapon_list | 列出可用武器类型 |

进阶

| 工具 | 说明 |
| sprite_batch_generate | 批量生成多个 AI 精灵图 |
| sprite_batch_process | 批量处理多张图像 |
| sprite_generate_background | 生成 3 层视差背景 |
| sprite_gif_export | 把精灵图 PNG 导出成动图 GIF |
| sprite_tiled_export | 把精灵图导出成 Tiled 编辑器 JSON |
| sprite_aseprite_import | 把 .aseprite 文件导入成精灵图/帧 |
| sprite_tileset_batch | 把地形图集切成各地形的瓦片变体 |
| sprite_video2dsprite | 从视频抽帧 → 精灵图 + GIF |
| sprite_palette_quantize | 量化到复古调色板（GameBoy、NES、Pico-8 等） |
| sprite_detect | 从 PNG 图集自动识别精灵网格布局 |

角色一致性

| 工具 | 描述 |
| sprite_character_create | 创建持久角色身份（名称、描述、参考图、种子） |
| sprite_character_get | 按 ID 获取角色身份 |
| sprite_character_list | 列出所有已保存的角色身份 |
| sprite_character_delete | 删除角色身份 |
| sprite_character_generate | 生成保持角色一致性的精灵（强度调节、固定种子） |
| sprite_character_sheet | 多视角角色表（正面/侧面/背面），外观保持一致 |
| sprite_character_views | 列出角色表可用的视角类型 |

道具与场景对象

| 工具 | 描述 |
| sprite_generate_prop_pack | 从图集生成并提取一批相关道具（石头、木桶、火把、宝箱……） |
| sprite_extract_prop_pack | 用色键从现有道具图集中提取单个道具 |
| sprite_scene_object | 生成/提取单个可直接用于游戏的场景对象，附带碰撞 bbox 元数据 |
| sprite_scene_object_batch | 从多对象图集中批量提取多个场景对象 |
| sprite_anchor_layout | 从已确认的主帧构建固定比例锚点模板，保证多视角一致 |

地形与平台

| 工具 | 描述 |
| sprite_tileset_batch_qc | 增强版地形瓦片包，支持 edge_policy（isolated/seamless）、对比度 QC、成对 PSNR 变体差异、材质提示 |
| sprite_platform_strip | 可复用的横版卷轴平台条带（左/中/右端盖），附带碰撞元数据 |

预览

| 工具 | 描述 |
| sprite_preview_list | 列出最近生成的精灵输出，含路径与时间戳 |
| sprite_preview_image | 读取本地图片文件，返回 base64 data URL 供客户端预览 |

用法示例

生成带动画的角色

// 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",javascript
reference_image_path: "./sprites/player_clean.png",
output_path: "./sprites/player_shoot.png"
})

生成特效 javascript // 列出可用特效
sprite_effect_list()

// 生成子弹特效
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" })

生成武器 javascript // 列出武器
sprite_weapon_list()

// 生成武器精灵图
sprite_generate_weapon({ weapon: "assault_rifle", output_path: "./weapons/rifle.png" })
sprite_generate_weapon({ weapon: "pistol_9mm", output_path: "./weapons/pistol.png" })

批量生成 javascript // 一次生成多个角色
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" },
]
})

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

导出为 GIF javascript // 把精灵图 PNG 转成动态 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（本地 SD） javascript // 确保 ComfyUI 已在 http://127.0.0.1:8188 上运行
sprite_generate_image({
prompt: "pixel art character sprite",
provider: "comfy",
width: 512, height: 512
})

配置 javascript // 设置 Agnes API key
sprite_sprite_config({
action: "set_key",
provider: "agnes",
api_key: "your_key_here"
})

// 切换默认服务商
sprite_sprite_config({ action: "set_provider", provider: "agnes" })

// 列出服务商
sprite_sprite_config({ action: "list" })

Godot 集成

1. 把生成的 PNG 导入你的 Godot 项目
2. 添加 SpriteFrames 节点
3. 新建资源，导入 PNG
4. 在检查器中启用 Region
5. 把 Region Rect 设为单个单元格尺寸
6. 把 H Frames 和 V Frames 设为网格尺寸

环境要求

- Node.js >= 18
- Python 3.8+
- Pillow + NumPy
bash
pip install Pillow numpy

开发 bash

安装依赖

npm install

构建客户端 bundle

npm run build-client

测试

node scripts/validate.mjs

打包发布

npm pack

许可证

MIT