spritecook-animate-assets

SpriteCook 动画资源

将此技能用于动画工作流。搭配 spritecook-workflow-essentials 使用，以了解额度、清单、安全下载和通用默认设置。

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

工具

开始动画前，请检查源图的轮廓和透明度。适用时，使用 spritecook-polish-sprites 从保留了 Alpha 通道的源图中恢复边缘像素，然后使用润色后资源的 ID 制作动画。检查已完成的动画是否有边缘闪烁；润色工作流可针对受支持的动画，对所有帧使用同一截断值进行比较。

animate_game_art

将现有 SpriteCook 资源制作成简短的像素艺术或精细动画。此工具会立即返回一个任务；请按照其 poll.tool 和 poll.arguments 继续查询，不要让请求一直保持打开状态。

参数	类型	默认值	描述
asset_id	string（必需）	-	要制作动画的现有 SpriteCook 资源 ID
prompt	string（必需）	-	描述随时间变化的具体动作。如果 auto_enhance_prompt=true，则可以使用“Idle”或“Attack”之类的简单提示词
auto_enhance_prompt	bool	true	检查源资源，并将简短提示词扩展为更完整的动画提示词
edge_margin	int	6	动画构图前添加的间距。像素艺术以底边作为地面线，因此间距会加在左右两侧和顶部
vertical_align	string	null	仅限像素艺术。对于飞行、漂浮或弹跳的主体，设为 "center"，这样 edge_margin 也会在下方留出空间。省略则保留地面线
pixel	bool	null	可选的模式覆盖值。省略时，SpriteCook 会根据资源推断模式
model	string	模式默认值	pixel-engine-v1.1、frame-engine-v1.1 或 pixel-engine-v1.5。省略时采用 v1.1 默认值
output_frames	int	8	v1.1 使用偶数帧（像素艺术为 2-16 帧，精细艺术为 2-24 帧）；v1.5 接受 3-16 的整数帧数
output_format	string	"webp"	"webp"、"gif" 或 "spritesheet"
negative_prompt	string	null	可选的动作/内容排除项。pixel-engine-v1.5 不支持此参数；使用该模型时不要传入
matte_color	string	"#808080"	处理透明度前使用的十六进制哑光颜色
removebg	string	"Basic"	"None"、"Basic" 或 "Pro"。Pro 会产生逐帧费用
colors	int	24	像素调色板大小，会强制应用于输出。仅当 pixel=true 时有效

动画大约需要 1-5 分钟。只有当工具的架构列出了 wait_seconds 时，才传入有上限的等待时间；否则，请适当间隔调用 check_job_status。animate_game_art 不接受 project_id；需要时，使用 assign_assets_to_project 移动结果。

准备起始帧

动画模型会对输入图像制作动画。请将该图像视为起始帧：它应已呈现所请求动作开始时所需的姿势、状态和朝向。动作提示词或 auto_enhance_prompt 无法替代对合适源图的准备。

• 制作动画前检查源图。如果其起始姿势符合动作要求，请重复使用。
• 如果所需状态需要不同的姿势，请先使用 generate_game_art 和 edit_asset_id 准备该姿势，或使用 reference_asset_id 根据已确立的角色生成。保持角色的设计、调色板、比例和美术风格。
• 检查准备好的静态图，然后将其返回的 asset_id 传给 animate_game_art。

示例：睡眠循环与入睡动作

下面说明如何为同一角色的不同动作选择起始帧：

• 对于睡眠循环，先制作一张同一角色躺下或蜷缩着、闭着眼睛的静态图。然后在保持睡姿的同时，为角色添加轻柔的呼吸动画。不要将站立、清醒状态的待机精灵图用作此循环的输入。
• 对于入睡过渡动作，可以使用清醒状态的起始姿势，因为躺下和闭眼都是所请求动作的一部分。应选择动作开始时的状态作为素材，而不是最终状态。

示例：将待机状态的兔子编辑为“同一只兔子蜷缩着熟睡，闭着眼睛，同时保留其设计和像素艺术风格”。检查这张静态图，然后使用“熟睡的兔子保持蜷缩姿势，闭着眼睛，轻柔呼吸，形成无缝循环”来制作新素材的动画。

示例：连续行走循环

制作循环行走动画时，先将待机精灵图编辑或改为行走中途的姿势，同时保持相同的角色设计和朝向。检查这张静态图，然后为动画使用其返回的素材 ID。从迈步中途的姿势开始，有助于让第一帧融入行走动作，避免每次循环重复时都出现尴尬的站立待机姿势。若要单独制作从站立到行走的过渡动画，仍可使用待机素材。

静态图提示词示例：“同一角色正在迈步，一条腿向前，另一条腿向后，双臂自然摆动，保持原有朝向、比例、调色板和像素艺术风格。”然后使用“原地连续行走，保持相同朝向和稳定节奏，平滑循环经过起始迈步姿势，不要停下或回到站立待机姿势。”检查循环边界，确认动作连贯。

工作流

1. 如果用户已有 SpriteCook 素材，请检查其起始姿势。只有在该姿势符合所请求的动作时才直接使用；否则，请按上述说明准备起始帧。
2. 如果用户只有本地图片文件路径，请使用 spritecook-upload-assets 调用 create_asset_upload，上传字节数据，然后调用 finalize_asset_upload。
3. 如果用户提供了较小的数据 URL 或原始 base64 值，请先调用 import_asset，并使用返回的 asset_id。
4. 也要根据起始帧指南检查上传或导入的图片。必要时准备不同的姿势，然后在 animate_game_art 中使用该准备好的静态图的 asset_id。
5. 除非需要强制指定模式，否则不要填写 pixel。

上传／导入步骤是源图片进入 SpriteCook 的环节，并非动画调用本身。可用时请使用 MCP 素材上传工具。

一致性规则

• 在不同动作中保持同一套既定角色设计。
• 对于起始姿势合适的动作，重复使用相同的 asset_id。如果某个动作需要不同的起始状态、姿势或朝向，请准备一张引用或编辑后的静态图，然后单独为该静态图制作动画。
• 保留原始角色素材，并记录准备好的姿势素材 ID 以便复用；避免生成无关且未引用的角色素材。

源素材规则

• 小尺寸源图应使用像素动画：v1.1 像素动画支持最大 256x256 的素材；v1.5 像素动画支持最大 320x320 的素材。
• 尺寸介于 256x256 和 2048x2048 之间的素材应使用精细动画。
• 不要强行将小于 256 的源图设为精细模式。
• 源图宽高比必须介于 1:2 和 2:1 之间。
• 默认保持 edge_margin=6。这有助于避免像素艺术素材过于贴近画布边缘。该值以百分比表示，因此对非常小的精灵图只会增加一两个像素；对于向外伸展的动作，例如打开盖子或大幅挥动，应调高此值。对于离开地面的主体，例如飞行的蝙蝠或弹跳的史莱姆，请传入 vertical_align="center"，并为大幅伸展或跳跃调高 edge_margin。

选择引擎

• pixel-engine-v1.1（默认）适合循环动画、行走循环和待机动画。
• pixel-engine-v1.5 适合精确或不寻常的动作，以及孤立主体。对于单个透明角色或道具，它通常也能生成更平稳、更忠实的动作。
• 不同主体的结果各不相同。对质量有要求时，可使用两个引擎处理同一张静态图，并保留效果更好的结果。
• 引导式角色动画（generate_character_animations）仅使用 v1.1。若使用 v1.5，请对同一张静态图使用 animate_game_art 分别制作每种动作。

输出画布

• 输出帧通常为方形且带有留白。非正方形源图会居中放入方形画布（180x320 的源图会返回 320x320 的帧），小型精灵图也可能会略微缩放。响应中不会报告偏移量。
• 要将动画放回场景或与静态图对齐，请在本地将第 0 帧与源图匹配以找出偏移量，并检查缩放比例。
• 不同任务的帧尺寸可能不同。若一组帧必须共用一条地面线，请在本地计算一个共用的帧边界框，然后重新放置每一帧。
• 帧数偶尔会与 output_frames 相差一帧；在假设循环长度之前，请先从结果元数据中读取 frame_count。
• 使用 output_format="spritesheet" 时，sprite_url 仍然是动画 WebP；PNG 条带则由 spritesheet_url 提供。

质量检查

• 动画制作前先清理静态图：轮廓上的杂散像素、部件之间残留的背景和噪点都会被重绘到每一帧中。请先使用 spritecook-polish-sprites。
• 尺寸低于约 32 px 时，轮廓可能会变得模糊，眼睛等小特征也可能在帧间漂移。此尺寸下应简化面部，并检查每一帧。
• 待机动画可能会闪烁：孤立像素在某一帧发生变化，随后又变回来。使用平静的提示词并设置 auto_enhance_prompt=false 可以减少整体动作。对于剩余的单帧变化，可在相邻前后帧一致时于本地恢复该像素。
• 明确说明必须保持静止的部分（“双脚保持不动”“面部不变”），并检查是否遵守；引擎并不总会遵循这些要求。
• 检查发光效果附近和脚部是否有灰色或偏色的斑点，并检查循环是否能够闭合（比较最后一帧与第一帧）。

动画化场景的一部分

动画化整个场景会重绘整帧：天空和石头等静态区域会在帧间偏移，循环也很少能闭合。应单独动画化移动部分：

1. 使用 generate_game_art(edit_asset_id=<scene>, prompt="Remove the X ...") 编辑场景，生成干净的背景底图。
2. 在本地通过原图与底图之间的差异抠出 X，上传后仅对该素材制作动画。
3. 将各帧按匹配的偏移量合成回底图。

对于瀑布等属于背景的效果，请使用 removebg="None" 和 edge_margin=0 对底图裁剪区域制作动画，然后使用运动遮罩将移动区域混合回去。

提示词编写

• 编写提示词前，先检查源图像中的实际角色。
• 对于像素艺术，仅为检查而使用最近邻插值将源图像放大至约 1024x1024。
• 首先识别可见的角色细节：轮廓、盔甲、面罩、武器、盾牌、姿势和朝向。
• 仅提及源图像中实际可见的细节。
• 用一段简短的普通文字描述，不要写成标签或关键词列表。
• 描述什么在移动、如何移动、什么保持稳定，以及可见的道具或武器如何使用。
• 让动作符合现有角色，不要凭空添加装备或特效。
• 避免使用 idle animation 之类的通用提示词，除非 auto_enhance_prompt=true。

待机提示词示例： 身穿紫色战术装备的装甲士兵保持稳定的战斗姿势，随着有节奏的呼吸待机动作轻微上下起伏。他的黄色面罩反射着光线，步枪在握持中略微移动，始终保持高度戒备。

攻击提示词示例： 身穿紫色战术装备的装甲士兵举起步枪并连续射击数发，枪管前端出现黄色枪口闪光。他的身体随每次射击向后顿挫，头部和面罩则始终朝向前方，整个射击过程中保持稳定的战斗姿势。

如果 auto_enhance_prompt=true，则 Idle、Attack 或 Walk 这类简单提示词也有效，因为 SpriteCook 可以检查源素材并自动扩展提示词。

check_job_status

将 animate_game_art 返回的 job_id 与 check_job_status 配合使用。成功后，使用 asset_id 和规范的 sprite_url；仅在存在 spritesheet_url 时使用它。如果响应报告 warning.code="asset_output_unavailable"，请执行提供的 warning.recovery 工具调用。