video2dsprite（仅限 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 镜像中预装）
输出根目录	`/workspace` 下的 `assets/sprites/video2dsprite/<name>/`
默认	对于生产级主角，优先使用 `generate2dsprite`；此路径用于更密集的运动

base still → imagine_image_to_video (in-place motion) → extract frames → chroma key → sample/normalize → strip / grid / GIF

平台限制（请先阅读）

运行时	是否支持？
Grok Build (xAI)	是 — 需要图像生成器 + 图像转视频工具
Codex / Claude / 其他代理	否 — 缺乏 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,48
cell_size: 输出精灵单元，默认 128
anchor: feet（侧向移动的默认值）| center
bg: 纯色 #FF00FF（色度处理必需）
name: 输出标识符
out_dir: 工作文件夹（默认为 ./sprites/video2dsprite/<name>/ 或项目相对路径）

代理规则

仅限 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；仅在用户要求时才为移动使用视频
特效/投射物/道具包 → $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. 匹配参考： 使用 imagine_image_to_image 与参考 file_path，将其移至品红背景上并保持身份一致性

基础要求：

全身可见，有足够的品红边距
跑步/行走采用侧视图（侧面或 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：

source path: <base still file_path>（由 T2I / I2I 返回的沙盒路径）
duration: 6（默认）或 10
resolution_name: 480p，除非用户要求 720p
prompt: 一个简短的现在时镜头（参见 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 = 提取每个解码帧（使用源 fps）
从角落进行品红泛洪填充 + 反色溢
对 --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

除非被要求，不要修改游戏代码。

默认值

时长：6秒
动作：侧向原地跑步，面向右侧
导出计数：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 — 循环/翻转测试/运动规律及引擎就绪默认值；仍使用此技能的脚本在沙盒中执行（品红基础 + 色度处理），而非使用任意自由格式背景颜色

video2dsprite（仅限 Grok Build）