Video2dsprite(仅限 Grok Build)
使用 Grok Build 原生视频工具将2D 角色基底图转换为密集动画精灵。
静态基底图 → image_to_video(原地运动)→ 抽取帧 → 色度抠图 → 采样/标准化 → 条状图 / 网格图 / GIF
平台限制(先读这里)
| 运行时 | 是否支持 |
|---|---|
| Grok Build (xAI) | 是 — 需要 image_gen / image_edit + image_to_video(或 reference_to_video) |
| Codex / Claude / 其他代理 | 否 — 它们没有 Grok 视频工具。请告知用户本技能仅限 Grok Build,并提供 $generate2dsprite 作为替代 |
如果工具列表中缺失 image_to_video,请停止并解释原因。不要使用代码绘制的帧来伪造运动。
本技能是一条可选的密集运动路径。它不替代 $generate2dsprite:
何时使用 $generate2dsprite | 何时使用 $video2dsprite |
|---|---|
| 需要清晰的像素图、固定网格、对角色特征要求严格 | 用户希望获得更密集的中间姿态 / 更流畅的循环效果 |
| 攻击/动作体型表、道具包、引擎图集 | 尝试基于视频的跑动/行走/待机动作 |
| 多数游戏精灵的默认生产方案 | 用户明确要求视频 → 帧 → 精灵 |
视频会软化像素、导致角色特征漂移并产生色度边缘残留。请务必进行质量控制;对于用于生产的角色,除非用户明确需要视频效果,否则优先使用 $generate2dsprite。
参数
根据用户请求推断:
subject:角色/生物描述,或现有静态图的路径action:run|walk|idle|attack| 自定义动作短语view:通常为side(横版卷轴)。topdown较困难 — 请警告并保持摄像机锁定duration:6(默认)或10秒frame_counts:需要导出的密集帧集合,默认8,16,24,48cell_size:输出精灵单元格尺寸,默认128anchor:feet(侧面移动的默认值)|centerbg:纯色#FF00FF(色度抠图必需)name:输出文件标识符out_dir:工作文件夹(默认./sprites/video2dsprite/<name>/或相对于项目的路径)
代理规则
- 仅限 Grok。 在非 Grok 运行时拒绝执行,附简短说明并提供
$generate2dsprite作为替代方案。 - 静态图 → 视频,不能仅使用文生视频。 先生成一个干净的静态图(通过
image_gen或根据参考图使用image_edit),然后再调用image_to_video。 - 原地运动。 提示生成在原地面向固定方向奔跑/行走的动作。无摄像机平移、无背景滚动、无场景变化。角色大致保持居中。
- 纯品红背景 应用于静态图并保留在视频提示中(
#FF00FF/ 纯品红)。对于泛洪填充式色度抠图是必需的。 - 不要使用 PIL/Canvas 凭空创造美术作品。 基础美术来自
image_gen/image_edit或用户/本地的静态图。脚本仅用于后期处理。 - 除非用户要求集成,否则不要将实验性输出放入游戏中。
- 优先为游戏使用一个运动循环。 对于预览,可以在整个 6 秒多循环片段上进行密集采样;对于引擎图集,在视觉质量控制后,可以选择重新采样一个单一循环(12–16 帧)。
- 完成后报告生成的视频、清理后的帧、精灵条状图和预览 GIF 的绝对路径。
工作流程
1. 规划
选择最小且最有用的执行方案:
- 侧面视角的奔跑/行走循环 → 使用本技能
- 多动作角色套件 → 每个动作仍使用
$generate2dsprite;仅在用户要求时才使用视频处理运动 - 特效 / 投射物 / 道具包 → 使用
$generate2dsprite,而非视频
创建目录结构:
<out_dir>/
base/
video/
frames-raw/
frames-clean/
sprite/ # 默认 8 帧集合 + 更密集的 x16/x24/x48 集合
prompt-used.txt
pipeline-meta.json
README.txt
2. 构建静态基底图
选项:
- A. 现有精灵: 使用图像工具打开/读取图像,如有需要合成到纯色
#FF00FF背景上 - B. 新角色: 使用
image_gen生成纯品红背景、全身、侧面视角、居中的图像 - C. 匹配参考: 根据用户提供的参考图,使用
image_edit在品红背景上进行编辑,保持角色特征
基底图要求:
- 完整身体可见,留有充足的品红边距
- 奔跑/行走的侧面视角(正侧面或 3/4 侧面),脚部靠近底部三分之一处
- 如有项目参考图,艺术风格需保持一致
- 无文本、UI、水印或第二个角色
保存为 <out_dir>/base/<name>-base.png。
将确切的图像提示写入 prompt-used.txt。
3. 使用 image_to_video 制作动画
调用 Grok 的 image_to_video:
image:静态基底图的路径duration:6(默认)或10resolution_name:480p(除非用户要求720p)prompt:一段简短的现在时镜头描述(参见 references/prompt-rules.md)
提示中的强制运动约束:
- 角色原地奔跑/行走(跑步机式)
- 摄像机锁定 — 无平移、缩放或环绕
- 背景保持纯品红平铺
- 在整个镜头中,角色特征、服装、调色板保持稳定
- 仅包含单一连续动作
将返回的视频复制到 <out_dir>/video/<name>-<duration>s.mp4。
如果视频工具不可用,请停止(平台限制)。
4. 抽取 + 色度抠图 + 采样(本地脚本)
运行处理器(ffmpeg + Pillow + numpy):
python skills/video2dsprite/scripts/video2dsprite.py process \
--video <out_dir>/video/<name>-6s.mp4 \
--out-dir <out_dir> \
--name <name> \
--frame-counts 8,16,24,48 \
--cell-size 128 \
--body-height 100 \
--foot-y 118 \
--fps 0
注意:
--fps 0= 提取每个解码帧(使用源帧率)- 从角落进行品红泛洪填充 + 去色边
- 对
--frame-counts中的每个计数进行均匀采样 - 脚部归一化的单元格、水平条状图、网格图、每个计数的循环 GIF
可选:仅从已有的清理帧中重新采样更密集的集合:
python skills/video2dsprite/scripts/video2dsprite.py sample \
--clean-dir <out_dir>/frames-clean \
--out-dir <out_dir> \
--frame-counts 16,24,48 \
--cell-size 128
5. 质量控制
目视检查:
- 预览 GIF 循环没有明显的跳动
- 品红已去除(无纯粉色块);允许有色边残留,或重新抠像
- 脚部保持在稳定的基准线上(不会因裁剪不当而跳动)
- 角色特征大致稳定(脸部/衣服不会每帧变形)
- 动作是原地进行的(不会滑出画面)
- 用于游戏时:选择一个计数(通常是 16 或 24)或剪裁出一个完整的周期
如果角色特征严重漂移或像素过于模糊,请回退到 $generate2dsprite 进行生产用图集,并将视频集仅作为运动参考。
6. 交付
仅报告路径(除非用户要求集成到游戏中):
- 视频:
video/*.mp4 - 密集精灵:
sprite/x16|x24|x48/ - 条状图 / 网格图 / GIF:
sprite/run-strip-N.png、run-grid-N.png、run-preview-N.gif - 元数据:
pipeline-meta.json
除非用户要求,否则不要修改游戏代码。
默认值
- 时长:6s
- 动作:侧面原地奔跑,面向右侧
- 导出帧计数:8, 16, 24, 48
- 单元格:128²,身体高度约 100,脚部在 y≈118
- 背景:#FF00FF
- 优先使用
image_to_video而非reference_to_video(如有需要,先用image_edit合成多参考图)
权衡(告知用户一次)
优点: 更密集的中间帧 → 通常比 4–8 个离散生成姿态更流畅。 缺点: 像素软化、角色特征漂移、色度边缘残留、多循环 6 秒片段并非一个完美的单循环、资源文件更大。 经验法则: 8→16→24 通常能提升流畅度;48 通常收益递减;145 个原始帧用于采样,并非全部用于运行时。
资源
- references/prompt-rules.md — 静态图 + 视频提示
- references/pipeline.md — 文件夹布局、ffmpeg、采样策略
- scripts/video2dsprite.py — 抽取、色度抠图、归一化、导出
与其他技能的关系
$generate2dsprite— 主要图集管线(Codex + 存在图像生成功能的 Grok)$generate2dmap— 地图;此处不使用$video2dsprite— Grok Build 独占的运动密集化路径