scenario-sprite-animation

场景精灵动画

概览

向通用图像模型输入一句简单提示词“a sprite sheet, walk cycle, 8 frames”，返回的只会是一张图片；而在遵循度高的图像模型上提供书面网格规格，则会返回精灵表（下方的单表行）。帧序列应根据任务所需的控制方式选择不同路径，而不只是看精灵尺寸。此技能负责在不同路径间分流并处理帧的计算；更深入的内容由相关技能负责：scenario-video（视频模型系列）、scenario-consistency 和 scenario-model-training（让同一角色贯穿一组动作）、scenario-game-assets（静态素材、像素清理、放大；由同一角色的多个帧组成的单张精灵表仍归此技能处理）、scenario-refine-loop（迭代直至符合需求）。连接和核心流程请参阅 scenario 技能。如果可用技能中缺少此处提及的相关技能，请让用户安装 （npx skills add scenario-labs/skills --skill <name>）；无人值守时，根据工具架构继续操作，并指出这一缺失。

快速参考

需求	路径
像素动画或 VFX、风格锁定画布	专门训练的动画模型（用用户自己的措辞通过 recommend 提出精灵动画需求，选择未弃用的方案）：GIF 预览、使用相同种子重新运行精灵图、切片
精确网格、指定帧数、脚本化节拍	高遵循度通用图像模型（用用户自己的措辞通过 recommend 提出网格规格；预期与专门训练的方案进行 ask_user）：运行一次 model_run、切片、逐个图块对齐、拼合
从静帧生成无缝循环	首尾帧视频模型（通过 recommend 提出循环要求）：两端使用相同的扁平化静帧并明确描述运动，提取、检查接缝
指定时刻的姿势	关键帧视频模型（通过 recommend 提出关键帧固定需求）：将姿势静帧固定到帧索引或时间戳，提取
动画化这个精灵，放大或更改风格	对扁平化静帧使用图像转视频，提示词以精灵动画风格为核心并包含脚本化运动节拍；按 scenario-video 选择模型
同一角色的一组动作	按 scenario-consistency 使用转面图和参考图转视频；为每个动作重复使用参考图和设置
一个角色、多个朝向、一组循环、一张图集	根据用户的作品制作姿势图集或转面图，然后针对每个朝向和循环分别制作一个首尾帧图像转视频片段，最后在本地使用随附的循环脚本完成处理（方向循环）
帧转图集、图集转帧	通过 model_run 使用工具模型：model_scenario-video-to-image-seq、model_scenario-grid-maker、model_scenario-image-slicer、model_scenario-image-seq-to-video（固定的第一方 ID：每个都是 Scenario 对应步骤中唯一的确定性工具）

模式是契约，应针对所选模型通过 model_schema_get 读取：每个会话都要重新发现生成相关成员，而不是将其硬编码（上述工具 ID 是固定的）。各路径的模式说明涵盖像素路径上的 Retro Diffusion 画布锁定和 returnSpritesheet 种子配对、单图集模式结构和价格、视频路径的控制界面、alpha 路径，以及如何解读弃用标签：references/lane-schemas.md。 单张图集通道放弃了像素通道原生像素、锁定画布和种子配对的优势，改为严格遵循指定网格；像素风格由模型模拟，因此吸附处理是该通道的一部分。在无人值守时，任务会根据表格前两行决定：如果需求说明中指定了精确网格、帧数或脚本化节拍，就优先选用排名最高的通用模型，而不是 specialty.model_id；其 when_general_better 列出的正是这些需求。请为将读取规格的流水线编写规格：行列数须在切片器的 6x6 范围内（16 帧应排成 4x4，不能排成 2 by 8，因为这是本地裁切）；画布须能被网格整除；统一比例、镜头、朝向和地面基线；指定每帧的节拍范围，并确保末帧与首帧匹配；留出充足边距，不加标签。不要写 GIF 制作步骤：图像模型会返回静帧，而保持帧就是在额外帧中重复同一姿势。background 枚举没有颜色选项，因此纯色背景需用提示词描述；已有角色应通过参考图字段输入；没有 seed 时，重新运行就会生成新角色，因此应通过样本数量参数生成候选图，并在切片前批准其中一张图集。切片前先检查交付的图集：清点单元格、辨认单元格边缘，并统计不同姿势的数量，因为节拍范围即使指定了单一结束状态，生成结果也可能是一个保持姿势。然后进行切片，按步骤 5 检查图块接缝，对齐各图块中的角色身体位置，使用相同的颜色数量和种子吸附每个保留的图块，确认吸附后的图块尺寸一致，再进行组装。对齐属于后处理，而不是提示词：角色身体会在不同行之间漂移（有一次运行中，最后一行落地的脚比第一行高出 87 px；锚定措辞和作为参考图传入的布局模板都未能改变这一点），因此要测量每个图块中角色身体的边界框，将其平移到统一基线和水平中心，并放到更宽的画布上，避免内容被裁切；然后上传重新排布的图集并进行切片，因为本地编辑的帧永远不会成为资源。

对于可复用布局，请阅读网格清单和模板使用指南。通过 scenario 技能的共享资源生命周期解析上传的资源并发布新版本。如果没有可用资源，由维护者或需要本地几何处理的 Agent 运行网格构建器，为 MCP 上传生成所选预设；它不会生成动画。无论使用哪种预设，都要优先保留用户指定的帧数和画布。模板不能替代上述对齐、边缘和循环检查。

对于需要多个朝向（等距斜视、侧视或俯视），并包含行走、奔跑、待机和攻击动作行的角色，请遵循方向循环通道：其中涵盖用户自己的美术素材、键色检查、镜像、武器手持方式以及引擎导入。该通道中的三个脚本由 Agent 运行，只负责本地几何处理，同时确保 MCP 步骤仍在通道内：cycle_prompts.py 会生成与模型无关的请求，以便映射到发现的模式；cycle_frames.py 会根据任意美术素材生成首帧；cycle_sheets.py 会为角色的动画片段抠色、搜索循环、注册并像素化成图集，随后通过 upload_asset 上传。 帧处理流水线由使用 model_run 运行的工具模型组成，而非独立的 MCP 工具：视频转图像序列提取器（extractAllFrames，或通过 frameInterval 提取每 N 帧；帧的顺序必须核验，绝不可假定，详见下文）、网格生成器（images，最多 100 张，按输入顺序保留；columns 默认为 3，未设置时根据数量计算 rows，因此，交付的 2×8 网格表示完成帧的 columns: 8；backgroundColor 接受十六进制字符串、transparent、black 或 white）、网格切片器（使用 image 以及 xSubdivisions 和 ySubdivisions，两者均为 1 到 6，省略时默认为 2，因此上限为 6×6；没有输出尺寸参数；切片按行优先顺序返回，但尺寸不一定等于网格单元大小，所以要用 asset_get 检查一张；若切片已缩放，或网格超过 6×6，则需按你计算的网格在本地切割网格图）、序列转视频组装器（model_scenario-image-seq-to-video，这是一个足够稳定、可以直接命名的第一方 ID；fps 为 1 到 120，支持 loopCount、pingpong，以及 outputFormat gif 或 mp4），以及像素对齐器（重新检测图稿网格，并量化为指定颜色数，这是清理流程中唯一的调色板控制项；按切片计费，因此先试一张再处理整组）。GIF 帧延迟以 10 ms 为单位量化，因此应让组装器使用可整除 100 的 fps（10、20 或 25；8 会得到 125 ms，12 会得到 83 ms，二者都不符合该间隔），否则它会重新计时并复制帧以保持时长。生成后，fps 是唯一的时间控制手段，因此要预先规划帧数，并清点返回的帧数。本地分析没有问题：差分、接缝计算、边缘读取和窗口搜索都需要磁盘上的像素数据。

帧顺序必须核验，绝不可假定。提取的帧具有相同的 createdAt，且 metadata 中没有索引，因此其顺序仅保存在任务行的 assetIds 中，而这个列表返回时曾出现时间顺序错乱（这是撰写本文时已确认的缺陷）。在进行任何步长计算、切片或组装之前，按返回顺序将这些 ID 传给网格生成器，并将联系人表与剪辑的免费 firstFrame 和 lastFrame（使用 asset_get 获取）以及其运动情况进行比对：破坏连续性的帧就是顺序错位的帧，此后应使用你自行维护的 ID 列表作为修正后的顺序。切勿根据列表、时间戳或 search 重建顺序。

示例：用静帧制作无缝待机循环

1. 先创建专用集合（collection_create，工具目录），并在每个保留的输出生成后立即调用 collection_add_assets（collection_id、asset_ids）。如果手头没有静帧，先生成并审批一张：它是后续每一步的锚点，因此在制作动画前，要根据需求说明核对主体的关键细节，并将其预算与循环动画分开计算 （references/lane-schemas.md）。将角色合并到纯色背景上（可在本地编辑；假设视频输入会像参考输入一样丢失透明度），然后用 upload_asset 上传。与用户确认通道和预算；若无人值守，则从任务说明中获取，否则选择满足需求的最低价通道，并在每次付费运行前执行 dry_run。
2. 使用用户自己的措辞描述循环要求来调用 recommend，优先选择未弃用的推荐项，然后调用 model_schema_get。架构决定可调参数：时长和 fps 枚举、static 这类镜头锁定设置、音频开关，以及适用时的原生循环标志（它会替代末帧锚点）：切勿同时发送两者（dry_run 接受的组合在实际运行时仍可能失败）。
3. 调用 model_run，将同一张静帧设为首帧和末帧，并在提示词中明确描述动作（“重心移动，斗篷摆动；角色留在原地”）。作业运行期间，使用 pending_job_ids 重新调用 jobs_wait。
4. 如果精灵需要 alpha，预期没有视频通道能直接输出 alpha，因此要预留一次去除处理的预算；批量处理前，先检查下载帧上的 alpha 是否保留：内嵌显示会将其合成掉，而要求透明背景返回的容器也可能不含 alpha （references/lane-schemas.md）。使用视频转图像序列工具提取帧，并先核对帧顺序（见上文）。计算步长前，先确认实际交付内容（请求不一定会被遵从）：asset_get 会报告 properties.duration、frameRate、nbFrames、width 和 height；计算需要的是实际交付的帧数 nbFrames，因此读取这些值即可，其余记录保持不变。编写时，提取器只提供 extractAllFrames 和 frameInterval，因此要用 model_schema_get 确认：没有起始偏移、结束位置或范围参数。任何非均匀选择（裁剪窗口、从偏移处开始取步长、手动挑选子集）都意味着设置 extractAllFrames: true，然后按资源 ID 筛选；frameInterval 无法表示所需窗口，绝不是离开该平台的理由。帧数计算：提取帧数 = 实际交付帧数 / frameInterval，包含端点；如果架构提供 fps，按精灵节奏（8 到 12 fps：一个循环通常需要 8 到 16 帧）生成，优于事后抽帧。
5. 根据序列自身的运动检查接缝，而非只凭肉眼判断：接缝是否像循环，取决于帧本身的运动幅度。计算相邻帧之间的平均绝对像素差（运动基线），以及接缝处的差值；当接缝差值不高于循环窗口的基线时，循环才算闭合。应使用循环窗口而非整个序列的基线，因为场景循环中每步的差值可能相差几个数量级。对于几乎静止的待机动画，只需用 asset_display 查看首帧和末帧；对于移动动画（跳跃、行走、攻击），仅凭肉眼检查会放过明显断裂的循环。如果接缝差值较大，不要先重新运行：图生视频模型会根据输入静帧重新渲染，因此第 0 帧往往与后续所有帧都不同（0 到 1 的差值较大就是迹象），重新运行无法修复锚定于该帧的循环。在模型自身的渲染结果中搜索起始帧和结束帧的配对，排除第 0 帧，并选择闭合最紧且仍保留真实运动的窗口。裁剪到有运动的部分：时长超过动作时会留下静止尾帧，步长应根据活动窗口而非实际交付长度计算。只有在窗口搜索失败后，才值得重新运行（架构提供 seed 时使用新的值，否则改写动作措辞），因为这会消耗额度。无人值守时，最多允许重新运行一次，然后标记问题并停止。
6. 收尾并打包：像素艺术目标需要像素对齐处理，但这也有自身的陷阱，有时并不适合这么做 （references/lane-schemas.md）。使用网格制作工具生成精灵表；背景设为 transparent，或者在需求说明要求不透明背景时设为某种颜色；通过序列转视频工具以 GIF 形式预览。组装器没有背景参数，因此交付的 GIF 需要使用已铺在背景上的不透明帧。使用 format="png" 调用 asset_download 下载帧，使用 format="gif" 下载预览；对于视频资源，不要传入 format，因为它不接受 mp4。

常见错误

• 只用一个简单的提示词，且首帧与末帧相同：这要求的是静止画面，而不是循环；必须明确说明动作。
• 把留白或措辞当作移动效果的边界：越过单元格边缘的部分就会消失；留白也会被填满并越过，而边界限制措辞会抵消抛掷效果。保留传递后边缘带看起来为空的帧；分离出来的投射物是独立精灵图。
• 以为每个模型都有 seed：许多视频模式和一些高遵循度图像模式都没有，因此这类模式的可复现性是按资源计算，而非按运行计算。
• 指望插值滤镜：目录中没有这类滤镜，fps 才是控制时序的手段。将非像素图像像素化，与清理像素艺术是不同的任务：目录提供了用于前者的 pixelate 工具（网格大小、调色板）和用于后者的 snapper；两者都可通过 search 找到（target: "models"、public: true、filters tags: ["tool"]、query: "pixel" 会返回两者；查看描述即可区分）。
• 在像素帧上使用照片放大工具：它们会凭空生成纹理；请使用 scenario-game-assets 中保留像素的路径。
• 不分步处理就交付图集：逐帧处理会返回新的 id，顺序只存在于你传入的列表中，因此要保留帧到输出的映射（切勿根据列表或时间戳重新构建），然后在交付前比较图集与预览。
• 因为帧已在磁盘上，就在本地组装交付内容：分析会下载片段，本地组装看起来不费事，但帧不会成为资源，导致集合中只有一张其他人无法访问的图集。
• 未检查就设置 ping-pong 或循环标记：查看下载的 GIF，并让组装器与其一致。
• 一次启动所有帧、方向或片段：超过团队并发上限（scenario 技能中的 parallel-custom-jobs 行）后，启动会被拒绝并返回该 429 错误，且不会创建任务；而在某些视频通道中，突发请求会被接受，但随后会以失败并退款的任务返回（方向循环）。无论哪种情况，都要分批启动，并在下一批中重新启动所有被拒绝或失败的项目，而不是丢弃它们。
• 因审核拦截而弱化攻击简报：过滤机制由提供方决定，因此请先按照 scenario-moderation 尝试其他通用图像模型，网格规格保持不变；重新措辞动作会失去该通道存在的意义。