spritecook-generate-sprites

SpriteCook 生成精灵图

此技能用于生成静态图像。请搭配 spritecook-workflow-essentials 使用，以了解积分、清单、安全下载和通用默认设置。

**需要：**已连接的 SpriteCook MCP 服务。如果未连接，请说明需要建立连接，并在获得授权后使用宿主的原生连接流程。请勿在美术任务中安装软件或更改身份验证设置。

如果需要完整的 UI 屏幕或协调一致的 UI 系统，请停止并改用 spritecook-build-ui-kits。UI 套件工作流会先创建一个统一的概念，再提取可复用的控件和状态。对于单个独立的图标、徽章、按钮、控件、分隔线、边框或装饰，请使用 generate_game_art(mode="ui")。

像素艺术模型默认设置

• 对于新建的像素艺术精灵图，除非用户要求使用其他设置，否则请使用 generate_game_art，并设置 model="gemini-nano-banana-2.1"、pixel=true 和 resolution="1K"。对于新建的基础角色，请使用 generate_character(model="gemini-nano-banana-2.1", ...)。
• 保留用户明确指定的选项和已保存预设中的模型。编辑时，除非用户要求更换模型，否则保留工具继承的源模型。
• 使用 list_generation_models 检查当前可用模型和价格。Nano Banana 2.1 发布时沿用了 NB2 在 1K / 2K / 4K 分辨率下的基础价格，即 12 / 18 / 30 积分。源分辨率与所请求的像素艺术尺寸相互独立，不能保证最终画布尺寸完全一致。
• 对于透明精灵图，继续使用 background="transparent"；SpriteCook 会在生成后移除背景。NB2.1 不会原生生成 Alpha 透明度。
• 遵守参考图数量限制：generate_game_art 接受的参考图总数最多为 14 张，计入 style_asset_ids 加上 reference_asset_id 或 edit_asset_id。具体限制取决于模型，可能更低；list_generation_models 会报告该限制。对于大多数模型，最多使用 10 张较为稳妥。
• 完整 UI 套件请遵循 spritecook-build-ui-kits 及其模型默认设置。

精确尺寸精灵图：Pixel Engine Image

当单个精灵图或 UI 元件必须以精确的小尺寸生成时，例如 32×32 的物品图标或 16×16 的拾取物，请使用 Pixel Engine Image（model="pixel-engine-image-v1"）。

• 生成尺寸精确为 width × height。边长范围为 16 至 128 px，最长边最多是最短边的 4 倍；最长边超过 64 px 后，两边都必须为偶数。超出范围的较大请求会缩小以适应限制。此模型的 resolved_parameters.size_behavior 为 "exact"，而不是 "hint"。
• 返回时背景已移除，因此无需单独执行移除步骤，也不会产生额外费用。此模型会忽略 smart_crop，且 resolution 始终为 1K。
• 此模型仅支持文本输入。请勿传入 style_asset_ids、reference_asset_id 或 edit_asset_id：包含任何参考图的请求都会被拒绝。它无法通过参考图匹配现有素材集，因此请将统一的视觉风格写入 theme 和 style，并在套组中的每张精灵图上复用相同措辞。如果结果必须与现有美术素材高度一致，请改用 Nano Banana 2.1 或 Pro，并提供风格参考图。
• 仅支持像素艺术：请使用 pixel=true 和 mode="assets" 或 mode="ui"。此模型不支持纹理、图块集或 UI 套件。使用 Pixel Engine Image 精灵图制作角色动画预备素材时，会使用默认模型。
• 每张图只绘制一个主体。请勿要求生成 3×3 图集；应为每个精灵图单独调用一次，或使用 variations 生成同一精灵图的替代方案。
• 编辑 Pixel Engine Image 素材时需要使用其他模型，因为此模型不接收输入图像。请通过 edit_asset_id 明确传入编辑模型。
• 使用 list_generation_models 查看当前价格；其条目包含 exact_output_size。

在网格中生成多个素材

当你需要多个相关道具、物品或装饰，或想制作更小的像素艺术时，通常建议将素材组合在 3×3 或 4×4 网格中生成。这样一次生成即可获得多个素材，与逐个生成相比可以节省用户额度，也有助于保持整组素材的视觉风格一致。

推荐设置

• 多对象生成优先使用 Nano Banana 2.1（gemini-nano-banana-2.1）或 Nano Banana Pro（gemini-3-pro-image）。尊重用户明确的选择和已保存的预设，并通过 list_generation_models 查看当前可用模型及费用。
• 使用 pixel=true 和 mode="assets"。
• 将像素艺术的宽度和高度设置为每个单独素材的目标尺寸。例如，若目标是约 32×32 的精灵图，请使用 width=32 和 height=32，而不要将其增大到 256×256 来表示整张素材表。这种设置适合作为生成引导；请检查提取出的精灵图，而不要假定其尺寸完全准确。
• resolution 设置（1K、2K 或 4K）单独控制源图像分辨率。此工作流建议从 1K 开始。
• 在提示词中描述 3×3 或 4×4 网格。variations 控制生成的素材表数量，而不是每张素材表中的对象数量。
• 提取单个精灵图时，建议使用 Pro 背景移除，以获得最佳效果，尤其是在处理精细细节和对象边缘时。估算批量生成费用时，请将其额外额度成本计算在内。如果工作流提供该设置，请选择 Pro；如果连接的工具没有提供 Pro 参数，则不要在 generate_game_art 或 remove_background 上虚构此类参数。背景移除是工作流设置，不是图像提示词指令。

编写素材表提示词

• 按行顺序列出对象，每个单元格放置一个完整对象。
• 要求对象之间留出充足空白，不重叠、不加标签，也不显示网格线。
• 指定所有对象使用一致的透视角度、调色板、光照、轮廓和像素比例。
• 若要匹配一组素材的风格，请使用现有素材作为风格参考。

提示词示例：

九个中世纪酒馆道具，排列在规则的 3×3 网格中。第 1 行：木桶、木箱、麻袋。第 2 行：马克杯、瓶子、蜡烛。第 3 行：凳子、水桶、炖锅。每个单元格居中放置一个完整对象，留出充足空白，采用一致的四分之三视角和比例。低分辨率像素艺术，适合约 32×32 的精灵图，轮廓清晰易辨，使用有限的暖色调，边缘清晰，光线方向一致且来自左上方。不要文字、标签、网格线、重叠或场景背景。

将此提示词与 32×32 的像素艺术尺寸、1K 源图像分辨率、Nano Banana 2.1 或 Pro，以及可用时的 Pro 背景移除搭配使用。

先切片，再制作动画

• 切片或制作动画前，先使用 spritecook-polish-sprites 检查轮廓和透明度。如果清理过程移除了边缘像素，请在本地对比保留的 Alpha 源图，并在生成衍生图前保存最佳阈值。
• 切片前检查生成的图集；网格排布可能不均匀。
• 如果依赖规则网格边界，请使用 smart_crop=false 保留外部布局，然后核实实际单元格边界。
• 使用可用的图像处理工具切成独立 PNG，并检查每个精灵图的边界是否完整、透明区域是否干净、比例是否一致，以及在预期尺寸下是否清晰易辨。
• auto_slice_asset 会按连通的 Alpha 区域，将自有图集拆分成自有资源。它适用于紧凑物体（对于间隙较小的精灵图，可稍微调高 merge_distance）。带有分离部件的物体（例如分开的翼尖或闪光效果）可能会被拆成额外碎片；这类情况应改为在本地按网格单元切片。
• 即使来自同一张图集，切出的单元格尺寸也可能不同。需要尺寸一致时，请在本地将整组图像统一到同一画布大小。
• 如果需要调整尺寸，请使用最近邻采样，并重新检查结果；尽可能采用整数倍缩放。
• 保留原始图集，并记录每个命名资源对应的裁剪来源。
• 如果提取出的精灵图需要制作动画，请通过 spritecook-upload-assets 上传单独的 PNG，然后使用 spritecook-animate-assets 为其返回的 asset_id 制作动画。
• 对于起始姿势合适的动作，请重复使用同一提取源资源。若起始状态不同，请先准备一个引用的姿势或编辑后的姿势，再按照 spritecook-animate-assets 的说明操作。

如果某项资源需要专门控制，请单独生成；在适用时，继续使用专门的角色、图块集和 UI 套件工作流。

工具

generate_game_art

根据文本提示词生成游戏美术资产。支持像素美术和精细／高清风格。默认情况下会立即返回一个任务；请按照返回的 poll.tool 和 poll.arguments 轮询，直到资产就绪。仅在明确需要设置等待时限时传入 wait_seconds。

参数	类型	默认值	说明
prompt	string（必填）	-	要生成的内容。请具体描述主体、姿势和视角
width	int	64	像素宽度提示（16-512）；使用 pixel-engine-image-v1 时为精确值（16-128）。参见下文“输出尺寸”
height	int	64	像素高度提示（16-512）；使用 pixel-engine-image-v1 时为精确值（16-128）。参见下文“输出尺寸”
variations	int	1	变体数量（1-4）
pixel	bool	true	像素美术设为 true，精细／高清美术设为 false
bg_mode	string	"transparent"	"transparent"、"white" 或 "include"
theme	string	null	美术主题背景，例如 "dark fantasy medieval"
style	string	null	风格方向，例如 "16-bit SNES style"
aspect_ratio	string	"1:1"	"1:1"、"16:9" 或 "9:16"
smart_crop	bool	true	自动裁剪至内容边界
smart_crop_mode	string	"tightest"	默认使用 "tightest"。仅在明确要求时使用 "power_of_2"
model	string	null	可选的生成模型。调用 list_generation_models 获取当前可选项和费用。
mode	string	"assets"	"assets"、"texture" 或 "ui"。仅当生成单个独立 UI 资产时使用 "ui"；生成屏幕或系统请使用 spritecook-build-ui-kits。
resolution	string	"1K"	"1K"、"2K" 或 "4K"
quality	string	"medium"	GPT-Image-2 质量级别："low"、"medium" 或 "high"。质量越高，消耗的点数越多。
colors	string[]	null	十六进制调色板指导，最多 64 个。用于指导颜色；输出不是索引调色板
style_asset_ids	string[]	null	用作环境风格参考图的自有资产 ID；根据模型不同，最多可参考 14 个；大多数情况下 10 个以内较为稳妥
project_id	string	null	要将新资产放入的自有项目
reference_asset_id	string	null	用作特定视觉／上下文参考的资产 ID
edit_asset_id	string	null	要根据新提示词编辑／修改的资产 ID
wait_seconds	int	0	可选的有限等待时长（0-90 秒），用于在返回轮询约定前等待

引用的资产必须属于用户的账户。style_asset_ids 可与 reference_asset_id 或 edit_asset_id 一起使用。不要同时使用 reference_asset_id 和 edit_asset_id。

如果用户提供了这些参考图的本地文件路径，请先使用 spritecook-upload-assets，再将其返回的资产 ID 传入相应的参考字段。

参考角色

• 对于风格指南图像，请使用 style_asset_ids：用于提供环境风格、调色板、比例、渲染方式和美术指导背景。生成与现有素材集相关的新素材时，通常应选择此项，例如在要求生成一种新建筑类型前，先提供三个现有建筑作为风格指南。SpriteCook 已将这些图像视为风格参考；只有当用户希望特别指出某种特征时，才在提示词中提及它们。
• 当某个特定素材是提示词的来源或背景时，请使用 reference_asset_id，例如 make a building in a similar style to this one、give me just the door sprite 或 use this character as the visual reference。
• 当用户希望直接修改某个现有素材时，请使用 edit_asset_id，例如 make this roof red、remove the sign 或 change the helmet color。
• 参考图也会带上其中的瑕疵，例如噪点或杂散像素。重新使用前，请先清理参考图。
• 风格参考还会设定像素比例。新作品会更多地遵循参考图的像素密度，而不是 width 和 height，因此，以一个全尺寸角色为指导生成的网格图可能会包含非常小的物品。
• reference_asset_id 会尽可能贴近参考图的像素尺寸；使用相似参考图生成多个变体时，结果可能与参考图近乎相同。使用 variations=1 或 2 进行参考图重绘，并在提示词中说明需要更改的内容。

输出尺寸

width 和 height 是参考值（在 resolved_parameters 中为 size_behavior: "hint"），而非固定画布尺寸。唯一的例外是 Pixel Engine Image（pixel-engine-image-v1），它会严格按请求尺寸返回；请参阅上文“精确尺寸精灵图”。像素模式下，最终画布会根据检测到的像素网格和内容裁切范围生成，因此可能与请求尺寸相差很大。同一任务生成的变体也可能尺寸各异。

• 规划布局前，请读取 resolved_parameters.output_dimensions 或每个素材的 width/height。不要假定会采用请求的尺寸。
• 小尺寸请求通常会得到更大的图像：针对细节丰富主体的 16-48 px 请求，通常会返回 40-90 px 的图像。也请在提示词中描述尺寸，例如“非常小的低分辨率精灵图，高约 32 像素”。
• aspect_ratio 和 smart_crop 不能保证画布形状。透明主体可能会出现在带有空白边带的正方形画布中；如果需要精确的边界框，请在本地裁切。
• 编辑可能会改变尺寸。切换 edit_asset_id 使用的模型，可能会让 44 px 的精灵图落在不同的网格上。进行小幅像素编辑时，请沿用源素材的模型，并在编辑后检查尺寸。
• generate_character 的目标尺寸约为 64 px，但根据模型和主体不同，返回的画布通常为 56-170 px。

要获取指定小尺寸的精灵图：

• 如果不需要参考图，请使用 Pixel Engine Image（model="pixel-engine-image-v1"），并将 width 和 height 设为目标尺寸。输出尺寸会与目标尺寸完全一致。
• 如果精灵图必须遵循参考图或匹配现有作品，请改用以下重绘流程：

1. 按模型的自然尺寸生成，并选出最佳设计。
2. 在本地使用最近邻算法将其缩小到目标尺寸（例如缩小一半），然后通过 spritecook-upload-assets 上传。
3. 调用 generate_game_art，将上传的素材设为 reference_asset_id，将 variations=1 或 2，并使用类似“以相同的粗颗粒像素尺寸，对这张低分辨率精灵图进行干净的精确重绘，保持设计和调色板不变”的提示词。重绘会保留参考图的像素尺寸，并清理缩小后的图像。

要匹配现有素材集的像素比例，请将该素材集传入 style_asset_ids。风格参考能很好地传递像素密度；与仅依赖尺寸提示相比，新道具或生物更可靠地匹配既有比例。

经实践验证的技巧

统一的系列。 对于一组图标、徽章、等级或物品，在一次调用中将整组内容生成为一张 3×3 或 4×4 拼图。这样可以让整组内容保持相同的尺寸、轮廓粗细和光照效果，效果胜过连续编辑或分开调用。将完成的拼图用作下一组内容的 style_asset_ids。

场景中位置和尺寸精准的物体。 若要从生成的场景中提取道具，请使用 edit_asset_id 编辑场景，并输入类似这样的提示词：“只保留火把、宝箱和旗帜，位置和尺寸完全不变。将其他所有内容填充为纯洋红色 #FF00FF。”然后在本地抠除洋红色。这样可以让每个物体保持在场景中的像素尺寸和位置。单独为某个道具生成参考图则做不到这一点。

干净的背景底图。 在完整场景中执行“移除 X”编辑，可以让其余构图几乎逐像素保持不变。可用此方法制作背景底图和蒙版（原图减去底图）。这种方法比“只保留 X，背景填充纯绿色”更可靠。

细微的像素编辑。 对于细线、眼睛或装饰边缘等 1-2 px 的细节，请要求修改现有内容：“将现有的细暗色弓弦线重新着色为浅奶油色。其他内容不作任何改动。”使用“制作”或“绘制”细节之类的提示词，反而可能擦除原内容。

调色板。 colors 可以引导调色板，但像素图输出仍会包含数百或数千种近似的颜色。如果用户需要严格的索引调色板（例如 4 或 16 种颜色），请在本地下载精灵图后使用最近颜色映射进行量化，不启用抖动。

透明背景上的白色部分。 bg_mode="transparent" 可能会抠除主体内部的大块白色区域，例如空白标签。请改用灰白色或彩色填充，或者使用 bg_mode="white"，再单独移除背景。

单张完整的 UI 画面。 对于样稿、缩略图或营销美术等不需要可复用部件的场景，generate_game_art(mode="ui") 也适用于生成单张完整画面或 HUD 图像。在这种尺寸下，GPT 图像模型渲染可读 UI 文本的可靠性高于 Gemini。如需可复用部件，请使用 spritecook-build-ui-kits。

list_generation_models

列出可用的静态图像生成模型、像素艺术支持、参考图数量限制、支持的质量选项，以及 SpriteCook 每张图像的积分消耗。选择模型时，或用户询问当前可用的模型或费用时，请调用此工具。

list_character_workflows

列出引导式像素艺术角色视角、默认动画 ID、源视图和准备要求、帧数以及预计积分消耗。

视角和预设动画：

视角	默认值	预设
platformer	idle、walk、jump	idle、walk、jump、run、attack、hurt、death
isometric	idle、walk_down、walk_right	idle、idle_back、walk_down、walk_right、jump_back、jump_front、run_down、run_right、attack、hurt、death
topdown	idle、walk_up、walk_right、walk_down	idle、idle_back、idle_right、walk_up、walk_down、walk_right、attack、hurt、death

generate_character

使用 SpriteCook 推荐的角色设置生成基础像素画角色：64x64 尺寸提示、透明背景、1K 正方形、紧凑智能裁剪，以及针对视角改写的角色提示词。最终画布通常为 56-170 px，因此请检查返回的尺寸。默认情况下会立即返回一个任务；完成后，第一个生成的资源即为 character_id。此工具没有 project_id；如果结果属于某个项目，请使用 assign_assets_to_project 移动结果。

参数	类型	默认值	描述
prompt	string（必填）	-	角色描述
perspective	string（必填）	-	platformer、isometric 或 topdown
model	string	null	可选的生成模型。调用 list_generation_models 查看当前选项和费用。
quality	string	"medium"	GPT-Image-2 质量级别："low"、"medium" 或 "high"
wait_seconds	int	0	可选的有限等待时间，范围为 0-90 秒，之后返回轮询约定

generate_character_animations

为基础角色资源生成预设动画和/或自定义动画。默认情况下会立即返回角色动画运行；根据返回的轮询约定继续轮询，直到规范的 assets 条目就绪。

参数	类型	默认值	描述
character_id	string（必填）	-	基础角色资源 ID：generate_character 的结果，或任何仍归你所有的角色静态图，包括已编辑、上传或切片的精灵图
perspective	string（必填）	-	与基础角色相同的视角
animation_ids	string[]	视角默认值	来自 list_character_workflows 的预设 ID
custom_animations	object[]	null	自定义动画，包含 { id, label, prompt, source_view, output_frames }
bg_removal_provider	string	"basic"	basic 或 photoroom
wait_seconds	int	0	可选的有限等待时间，范围为 0-90 秒，之后返回轮询约定

角色动画运行使用 pixel-engine-v1.1；此工具没有 model 参数。对于 pixel-engine-v1.5，请在同一张静态图上使用 animate_game_art 分别为每个动作制作动画（参见 spritecook-animate-assets）。运行输出使用独立画布，通常比基础静态图更大，且不会与其对齐；如果交接时不能有跳动，请在本地将第 0 帧与静态图匹配。快速跳跃和头顶挥击可能触及画布边缘，请检查这些帧。一起发送的两个相同调用可能会返回同一个运行；每次想要生成一个版本时，请单独发送一次调用。

将任何归你所有的静态图作为 character_id 传入，通常是生成与现有美术风格一致的角色动画的最佳方式。上传或切片的资源应先使用 update_asset_label 添加描述性标签，因为该标签可能会用于自动生成动画提示词。

自定义动画使用自定义提示词作为最终动画提示词，并跳过预设提示词增强。source_view 默认为 front_idle；如果其他源视图需要预处理，SpriteCook 会使用该视角对应工作流的预处理依赖项。source_view 用于选择受支持的工作流输入，而不是任意新状态，例如蜷缩睡觉。对于需要不同起始姿势的自定义状态，请先使用 generate_game_art 准备静态图，然后在该准备好的资源上使用 animate_game_art。

自定义动画示例：

{
  "label": "Spin Attack",
  "prompt": "Spin in place with a quick sword slash, looping cleanly.",
  "source_view": "right_walk",
  "output_frames": 8
}

check_character_animation_run

按 ID 检查引导式角色动画运行。返回运行状态、项目状态、规范生成的 assets、预处理状态、失败信息和点数。

异步结果约定

• 按原样使用返回的 poll.tool 和对应的 poll.arguments；对于作业，使用 check_job_status；对于角色动画运行，使用 check_character_animation_run。
• 将 operation_id 视为通用操作标识符，同时为对应的轮询工具保留 job_id 或 run_id。
• 成功时，使用每个资源的 asset_id 和 sprite_url。只有当动画也提供精灵图集时，才使用 spritesheet_url。
• 如果成功响应包含 warning.code="asset_output_unavailable"，请执行提供的 warning.recovery 工具调用，而不是搜索任意嵌套的 URL 字段。

工作方式

• 生成后，以原始尺寸和最近邻缩放检查结果。在交付或复用前，使用 spritecook-polish-sprites 修复轮廓破损、边缘像素缺失、光晕或背景杂屑；对于干净的结果，保持不变。
• 明确说明主体、姿势、相机／视角和关键材质。
• 涉及当前模型名称、像素艺术支持、质量选项或积分成本时，调用 list_generation_models。
• 用户要求使用已保存的预设时，先使用 list_presets 和 get_preset_settings，然后将返回的提示词、风格、模型、尺寸、颜色和参考指导映射到 generate_game_art。
• 用户需要可直接使用的动画角色套装时，使用 list_character_workflows、generate_character 和 generate_character_animations。
• 将菜单、HUD、物品栏、对话框、设置屏幕、叠加层及其他完整 UI 组合交由 spritecook-build-ui-kits 处理。
• 默认使用像素艺术，除非用户要求 HD、细致、平滑、写实或高分辨率输出。
• 用户需要同一角色或物品出现在多个输出中时，先确定一个规范设计，并将其作为来源或参考重复使用。制作动画时，如有需要，按照 spritecook-animate-assets 准备不同的起始姿势。
• 对于后续生成中需要保持相同视觉风格的情况，使用 style_asset_ids，尤其是预设返回 settings.reference.styleAssetIds 时。
• 当提示词依赖某个特定的视觉／上下文参考资源时，使用 reference_asset_id。
• 直接修改现有 SpriteCook 资源时，使用 edit_asset_id。
• 如果实际目标是创建一个一致的角色并为其制作后续动画，不要生成多个互不相关的静态变体。
• 除非用户明确要求 "power_of_2"，否则优先使用 smart_crop_mode="tightest"。

一致性规则

• 对于一组动作，只创建一次基础角色。当其起始姿势合适时，为同一个 asset_id 制作动画；否则，创建一个具有参考依据或经过编辑、姿势符合要求的静态图，检查后再为新资源制作动画。例如，先准备睡觉姿势的静态图，再生成睡眠循环动画。
• 对于需要保持设计辨识度一致的资源变体，优先使用 edit_asset_id 直接修改，或使用 style_asset_ids 提供风格指导，而不是全新生成一个无参考的资源。
• 只有当用户明确想探索不同设计时，才跳过参考。

像素艺术与精细艺术

像素艺术（pixel: true，默认）：

• 清晰锐利的硬边缘，无抗锯齿，可见像素网格
• 自动进行像素级后处理，确保网格对齐干净
• 最适合复古游戏、独立游戏和 8 位／16 位项目
• 强烈推荐 Gemini 模型，尤其是 Nano Banana 2.1（gemini-nano-banana-2.1）、Nano Banana Pro（gemini-3-pro-image）或更新的 Gemini 图像模型

精细／HD 艺术（pixel: false）：

• 平滑渐变、丰富细节、边缘带抗锯齿
• 不受像素网格约束，输出保真度更高
• 最适合 HD 2D 游戏、概念艺术和营销资源
• GPT 图像模型通常更擅长处理复杂的精细艺术，但 Gemini 和 GPT 模型在此方面都表现良好

根据游戏的美术方向进行选择。用户未指定时，默认使用像素艺术。