AHMADALIPARR/video2dsprite

Video2dsprite（僅限 Grok Build）

使用 Grok Build 的原生影片工具將基礎 2D 角色圖像轉換為密集動畫 Sprite。

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；此技能為密集動作路徑

基礎靜態圖 → imagine_image_to_video（原地動作） → 提取影格 → 色鍵去背 → 取樣/正規化 → 條狀圖 / 網格 / 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…
清晰的像素遊戲素材、固定網格、身份關鍵的角色	使用者想要更密集的中間姿勢 / 更流暢的循環感
攻擊/施法角色素材、道具包、引擎圖集	嘗試從影片來源的跑步/行走/待機動作
大多數遊戲 Sprite 的生產預設	使用者明確要求 影片 → 影格 → Sprite

影片會使像素模糊、導致角色身份飄移，並留下色鍵殘邊。務必進行品質控管；對於正式遊戲角色，除非使用者想要這種影片效果，否則請優先使用 $generate2dsprite。

參數

根據使用者請求推斷：

• subject：角色/生物描述，或現有靜態圖的路徑
• action：run | walk | idle | attack | 自訂動作短語
• view：通常為 side（橫向捲軸）。topdown 較困難 — 請警告並保持攝影機鎖定
• duration：6（預設）或 10 秒
• frame_counts：要匯出的密集幀數集合，預設為 8,16,24,48
• cell_size：輸出 Sprite 單元大小，預設為 128
• anchor：feet（側向移動的預設值） | center
• bg：純色 #FF00FF（色鍵所需）
• name：輸出代號
• out_dir：工作資料夾（預設為 ./sprites/video2dsprite/<name>/ 或相對於專案的路徑）

代理規則

1. 僅限 Grok。 在非 Grok 執行環境中拒絕執行，並簡短說明後提供 $generate2dsprite 替代方案。
2. 靜態圖 → 影片，絕不能只有文字轉影片。 先使用 imagine_text_to_image（根據提示或參考 file_path）將影格 1 製作成乾淨的靜態圖。然後使用該靜態圖的 file_path 呼叫 imagine_image_to_video。
3. 原地動作。 提示跑步/行走時，須指定原地進行，並面向固定方向。無攝影機平移、無背景滾動、無場景變化。主體大致保持居中。
4. 純洋紅色背景 用於基礎圖並在影片提示中保留（#FF00FF / 純洋紅）。這是進行泛洪填充色鍵所必需的。
5. 不要使用 PIL/Canvas 憑空創作美術資源。 基礎美術資源來自 imagine_text_to_image 或使用者/本機的靜態圖。腳本僅進行後處理。
6. 除非使用者要求整合，否則不要將實驗性輸出放入遊戲中。
7. 偏好單一移動循環供遊戲使用。 基於完整 6 秒多循環片段進行密集取樣可用於預覽；對於引擎素材，可在視覺品質確認後，選擇性地重新取樣單一循環（12–16 幀）。
8. 完成時回報 影片、清理後的影格、條狀圖和預覽 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. 現有 Sprite： 讀取圖片，如有需要則合成到純色 #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（預設）或 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 = 提取每個解碼後的影格（使用來源幀率）
• 從角落進行洋紅泛洪填充 + 去溢色
• 對 --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：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 — 循環/翻轉測試/動作法則和引擎準備就緒的預設值；仍使用此技能的腳本在沙箱環境中執行（洋紅底色 + 色鍵），而非使用自由形式的背景顏色