视频转精灵 V2 (仅限 Grok Build) 是做什么的?
利用 Grok Build 的原生视频工具,将 基础 2D 角色图像 转换为 密集动画精灵。
App-builder / Grok 环境
| 项目 | 值 |
|---|---|
| 技能目录 | .grok/skills/video2dsprite/ |
| 脚本 | python3 .grok/skills/video2dsprite/scripts/video2dsprite.py … |
| 视频工具 | imagine_image_to_video — 对单个 file_path 进行动画处理(确认文件存在) |
| 检查 | 用 read_file 检查静态帧/帧文件;报告视频路径 |
| 依赖 | ffmpeg + Pillow + numpy(已在 app-builder 镜像中预装) |
| 输出目录 | assets/sprites/video2dsprite/<name>/ ,位于 /workspace 下 |
| 默认 | 对于生产级核心角色,优先使用 generate2dsprite;此技能是更密集动作的实现路径 |
基础静态图 → imagine_image_to_video (原地运动) → 提取帧 → 色度抠图 → 采样/归一化 → 精灵条 / 网格 / GIF
平台限制(先阅读)
| 运行时 | 是否支持? |
|---|---|
| Grok Build (xAI) | 是 — 需要图像生成器 + 图像转视频工具 |
| Codex / Claude / 其他 Agent | 否 — 它们缺少 Grok 视频工具。告知用户此技能仅适用于 Grok Build,并推荐 $generate2dsprite 替代方案 |
基于能力进行限制,而非确切的工具名称。 图像生成可能以 imagine_text_to_image / imagine_image_to_image 形式出现;视频生成以 imagine_image_to_video 或(旧版)generate_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>/或项目相对路径)
Agent 规则
- 仅限 Grok。 在非 Grok 运行时上拒绝执行,并附带简短说明 + 推荐
$generate2dsprite替代方案。 - 静态图 → 视频,不能单独使用文本转视频。 先通过
imagine_text_to_image(根据提示或参考file_path)生成一张清晰的静态图作为第一帧。然后使用该静态图的file_path调用imagine_image_to_video。 - 原地运动。 提示要求角色朝向固定方向原地奔跑/行走。无相机平移、无背景滚动、无场景变化。角色大致保持在画面中心。
- 纯色品红色背景 应用于基础图并保留在视频提示中(
#FF00FF/ 纯品红色)。这是泛洪填充色度抠图的必需条件。 - 不要用 PIL/Canvas 捏造美术资源。 基础美术来自
imagine_text_to_image或用户/本地的静态图。脚本仅进行后处理。 - 除非用户要求集成,否则不要将实验性输出放入游戏。
- 对于游戏使用,优先采用一个移动循环。 对于预览,可以从整个 6 秒多周期剪辑中进行密集采样;对于引擎贴片,可选地在视觉质量检查后对一个周期(12–16 帧)进行重新采样。
- 完成后报告视频、清理后的帧、精灵条和预览 GIF 的绝对路径。
工作流程
1. 规划
选择最小可用的运行方式:
- 侧视奔跑/行走循环 → 使用本技能
- 多动作核心角色工具包 → 仍然每个动作使用
$generate2dsprite;仅当用户要求时才使用视频生成移动动画 - FX / 抛射物 / 道具包 → 使用
$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背景上,然后将该沙盒路径传递给imagine_image_to_image/imagine_image_to_video - B. 新角色: 使用
imagine_text_to_image生成纯品红色背景、全身、侧视图、居中的图像 - C. 匹配参考: 使用参考
file_path调用imagine_image_to_image,将其迁移到品红色背景上并保持角色身份
基础图要求:
- 全身可见,品红色边缘充足
- 侧视图用于奔跑/行走(侧面或 3/4 侧),脚部接近底部三分之一处
- 当存在参考时,艺术风格与项目其余部分一致
- 无文字、UI、水印或第二个角色
复制返回的 file_path 并保存为 <out_dir>/base/<name>-base.png;保留基础图的 file_path 用于视频调用。
将确切的图像提示写入 prompt-used.txt。
3. 使用 imagine_image_to_video 制作动画
调用 Grok 的 imagine_image_to_video:
- 源路径:
<基础静态图 file_path>(由 T2I / I2I 返回的沙盒路径) duration:6(默认)或10resolution_name:480p,除非用户要求720pprompt:一个简短的现在时态镜头描述(参见 references/prompt-rules.md)
提示中强制包含的运动约束:
- 角色原地奔跑/行走(类似跑步机效果)
- 相机锁定 — 无平移、缩放或环绕
- 背景保持纯色品红色
- 角色的身份、服装、调色板在整个镜头中保持稳定
- 仅包含一个连续动作
将返回的视频 file_path 复制到 <out_dir>/video/<name>-<duration>s.mp4。
如果视频工具不可用,则停止(平台限制)。
4. 提取 + 色度抠图 + 采样(本地脚本)
运行处理器(ffmpeg + Pillow + numpy):
python3 .grok/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
可选:仅从已有的清理帧中重新采样更密集的帧集:
python3 .grok/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
- 优先使用单个资源的
imagine_image_to_video,而不是多参考(如果需要多参考,先用imagine_text_to_image合成)
权衡(向用户说明一次)
优点: 更密集的中间姿态 → 通常比 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 独占的动作密集化路径$game-asset-core/$game-animation-frames— 循环/翻转测试/运动规律和引擎就绪默认值;仍然使用本技能的脚本在沙盒中执行(品红色基础图 + 色度抠图),而不是使用自由形式的背景颜色