精灵熔炉 是做什么的?
精灵熔炉利用本机 GPU(底层基于 ComfyUI,会自动启动)将文字描述转换为可直接用于游戏的 2D 素材。整个过程不会向任何付费服务发送数据。每个结果都会被干净地裁切、裁剪、调整大小、检查并保存为清单文件;系统会生成多个候选结果,只保留最佳的一个。
调用方式
当 sprite-forge MCP 工具可用时,优先使用它们:
list_profiles, generate_sprite, create_character, animate_pixel, make_normal_map, get_job, check_image, models, forge_status。
否则,从精灵熔炉文件夹使用命令行;每条命令输出一个 JSON 对象:
python forge.py profiles
python forge.py sprite <name> "<prompt>" -p sprite --project <game folder>
python forge.py sprite <name> "<prompt>" -p pixel_sprite --set grid=32 --set palette=project --project <game folder>
python forge.py character <id> "<who, outfit, colours, props>" --project <game folder>
python forge.py sprite <name> -p turnaround --character <id> --set directions=8 --project <game folder>
python forge.py sprite <name> -p animation --character <id> --set action=walk --set facing=right --project <game folder>
python forge.py animate <name> <sprite.png> "<the motion>" --pose "<frame 1>" --pose "<frame 2>" ...
python forge.py normal <sprite.png>
python forge.py check <file.png> --kind sprite
退出码 0 = 成功,2 = 完成但结果未通过检查,1 = 错误。
选择配置档案
| 档案 | 用途 | 输出 |
|---|---|---|
sprite | 道具、物品、拾取物、武器、家具、UI 元素 | 透明 PNG,已裁剪,在方形画布上居中 |
icon | 技能/物品图标、徽章、按钮 | 方形 PNG,附带 256/128/64 像素版本 |
pixel_sprite | 真实像素艺术:角色、物品、敌人 | 真实像素网格(例如 32 像素)、硬边缘透明、有限或命名的调色板,附带 8 倍预览 |
character | 可复用的角色参考图 | 全身透明 PNG,脚底对齐地面线 |
pixel_character | 同上,但以像素艺术风格绘制 | 像素艺术角色表的参考图 |
turnaround | 角色朝向 4 或 8 个方向 | 帧序列 + <name>_sheet.png + <name>.atlas.json |
animation | 行走、奔跑、待机、攻击、跳跃、受伤、死亡、施法 | 帧序列 + 图集 + 包含动画标签的图集 |
tile | 地面、墙壁、地板、水面、植被 | 无缝方形纹理 + 3×3 平铺预览(可选像素版本) |
portrait | 对话头像、卡牌、关键艺术图 | 全分辨率图像 |
vfx | 爆炸、烟雾、魔法爆发、击中火花 | 帧序列 + 图集 + 图集;亮度作为透明度 |
animate_pixel (工具) | 根据描述为已有像素精灵制作动画 | 使用精灵自身网格和调色板的帧 + 图集 + GIF |
每个图集还会生成 <name>.gif(循环播放),方便用户查看。
每个配置档案有三种预设:fast(一次快速生成)、standard(默认)、max(使用更大模型或更多候选次数;转向/动画使用 Qwen-Image-Edit)。请说明你使用的预设。
工作流程
- 始终传递游戏项目文件夹(
project_dir/--project)。其中的spriteforge.json提供了风格、输出文件夹、角色文件夹以及每个配置档案的设置,从而保证游戏素材风格一致。如果项目没有该文件,主动提议创建一个(forge.py init <dir>)。 - 按照配置档案的
prompt_guide编写提示词(list_profiles会返回它)。描述物品本身,而非画面:不要写“一个精灵的”,不要写背景,不要在提示词中使用摄像机术语——通过params.view设置角度(front view、side view、top-down view、isometric view)。 - 多次出现的角色:先创建角色。 使用
create_character(或设置character的character档案)保存一个参考图;转向和动画都是基于它的编辑版本,从而保证角色外观一致。对于像素艺术角色表,使用profile: "pixel_character"并向角色表传递params.pixel_grid(例如 32)。 - 耗时较长的作业是异步的。 如果工具返回了作业 ID,请调用
get_job(设置wait_seconds: 50)直到状态不再是queued或running。一次只处理一个作业。 - 查看预览。 每个结果都会附带预览图像(精灵显示在棋盘格背景上)。在确定素材完成前务必检查:是否主题错误、部分被裁断、出现第二个物体、有光晕、帧与角色不匹配。报告文件名、文件大小、任何
problems,并提及.spriteforge/<name>/中的其他候选结果。
像素艺术
- 图像模型只能绘制像素艺术风格;精灵熔炉使其变为真实像素艺术:它会找到模型的像素网格(或强制指定
grid),取每个单元格的主色,去除孤立像素,将 Alpha 通道设为完全开关状态,并限制调色板。没有经过这一步,永远不要声称一个精灵是像素艺术。 grid:精灵最长边的像素数(16、24、32、48、64)。"auto"保留模型绘制时的像素尺寸。palette:pico8、gameboy、nes、endesga32、sweetie16、十六进制颜色列表,或"project"——为整个游戏冻结一个调色板(第一个像素素材在项目中保存为palette.hex,后续所有素材复用该文件)。对于一款游戏,使用"project"。outline: true添加 1 像素深色轮廓;canvas: 32将精灵放置到 32×32 网格上。- 不应用抖动(因为动画时会产生闪烁)。
为已有像素精灵制作动画
当用户已经有一个像素精灵(自己的,或通过 pixel_sprite 创建的)并描述一个动作时,使用 animate_pixel:“让史莱姆弹跳”,“让骑士挥剑”。它会在每一帧保持精灵的精确像素尺寸和调色板。
image:PNG(原始大小不超过 256 像素,或者是放大后保持硬边缘的副本)。description:动作描述。walk / run / idle / attack / jump / hurt / death / cast 使用内置的关键帧。- 对于其他动作,请自行编写
poses:每帧用一行简短的描述说明变化,例如对于挥剑:["将剑高举过头", "剑举到最高处,身体后仰", "将剑向前劈下", "挥击后剑放低"]。3-6 帧效果最佳。这些是关键帧,不是补间帧。 params.include_original: true将原始未修改的精灵作为第 0 帧;params.fps。- 查看 GIF / 预览:如果某一帧丢失了精灵的一部分或发生了改变,请使用新的
seed或preset: "max"(每帧更多候选次数)重新运行。
法线贴图(2D 光照)
对于使用 2D 光照的游戏(Godot 的 CanvasTexture + Light2D、Unity 2D 光照、Phaser 的 light2d),向 sprite、icon、pixel_sprite、character、turnaround、animation 或 animate_pixel 传递 params.normal_map: true,或对任何现有 PNG 调用 make_normal_map。
- 生成
<name>_normal.png(或<name>_sheet_normal.png,与图集相同的布局)以及<name>_lit_preview.png(精灵从左侧、顶部、右侧和底部受光的效果预览)——请向用户展示预览。 - 像素艺术会保留其像素网格,并生成清晰、对齐的法线。
- 默认约定为 OpenGL(绿色=上方),Godot 和 Unity 均采用此约定;对于 DirectX 使用
normal_y: "down"/y: "down"。normal_strength0.5 为微妙,2 为强烈。 - 隆起效果是从画面(轮廓、色彩区域、高光)推断出来的,而非建模生成:在动态光照下效果良好,但并非真正的深度扫描。
当结果提示 failed_check
文件已写入,但不应直接使用。problems 说明了原因。
| 问题 | 修复方法 |
|---|---|
cut off | 使用新的 seed 重新运行;添加“小的、居中的、周围留出空间”或提高 params.padding。 |
several objects | 只命名一个物体;使用新种子重新运行。 |
background not removed / empty | 描述一个实心物体;保持 background 为纯色;重新运行。 |
may not look like the character(图集) | 使用新种子或 preset: "max" 重新运行该图集;保持角色提示词简洁。 |
may not have turned(转向) | 使用 preset: "max" 重新运行(Qwen-Image-Edit 能更好地跟随视角变化)。 |
no clear pixel grid found | 图片未以像素艺术风格绘制:设置 grid 为一个数值,或重新运行。 |
visible seam(瓦片) | 使用有机表面或提高 params.blend;重新运行。 |
much smaller than the original(animate_pixel) | 该帧丢失了精灵的一部分:使用新种子重新运行,或给出更清晰的姿势。 |
flat: almost a single colour | 模型绘制了一个剪影:使用新种子重新运行;加上“使用全彩色”。 |
使用相同的 name 和相同的设置会返回已有文件;更改设置、种子或传递 force: true 将生成新文件。
自定义
- 项目级别:
spriteforge.json(style、style_preset、output_dir、characters_dir、profiles.<id>.params,例如{"pixel_sprite": {"params": {"grid": 32, "palette": "project"}}})。 - 单次调用:
params,例如{"size": 256, "candidates": 6, "view": "side view", "directions": 4, "action": "attack", "facing": "down"}。list_profiles会列出每个参数及其说明。 - 新配置档案:在项目的
spriteforge_profiles/中放置一个小的 JSON 文件,并extends一个现有档案。 - 模型和硬件:
models工具会报告每个配置档案和预设需要哪些模型、缺少哪些模型。下载文件较大——请在安装前询问用户。 - 许可证:精灵熔炉安装的每个模型均允许商业使用您生成的资产(FLUX.2 Klein 4B、Z-Image Turbo、Qwen-Image-Edit 2511 及像素 LoRA:Apache 2.0;BiRefNet 和 CLIP:MIT)。部分商店(例如 Steam、itch.io)要求您声明使用了 AI 生成的资产。