AHMADALIPARR/video2dsprite

Video2dsprite（Grok Build専用）

ベースとなる2Dキャラクター画像を、Grok Buildのネイティブビデオツールを使って密度の高いアニメーションスプライトに変換します。

App-builder / Grok環境

項目	値
スキルディレクトリ	.grok/skills/video2dsprite/
スクリプト	python3 .grok/skills/video2dsprite/scripts/video2dsprite.py …
ビデオツール	imagine_image_to_video — 1つのベース 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 を使用する場合…
鮮明なピクセルシート、固定グリッド、アイデンティティが重要なヒーロー	ユーザーがより密度の高い中間ポーズ / より滑らかなループを望む場合
攻撃/キャストボディシート、プロップパック、エンジンアトラス	ビデオソースの走り/歩き/待機モーションを実験する場合
ほとんどのゲームスプライトのプロダクションデフォルト	ユーザーが明示的にビデオ → フレーム → スプライトを要求した場合

動画はピクセルを柔らかくし、アイデンティティをドリフトさせ、クロマフリンジを残します。常に品質管理を行ってください。プロダクション用ヒーローには、ユーザーがビデオルックを望まない限り $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>/ またはプロジェクト相対）

エージェントルール

1. Grokのみ。 Grok以外のランタイムでは、簡単な説明と $generate2dsprite の代替案を提示して拒否する。
2. 静止画→動画、テキスト→動画のみは不可。 フレーム1を imagine_text_to_image（プロンプトから、または参照 file_path から）でクリーンな静止画としてステージングする。その後、その静止画の file_path で imagine_image_to_video を呼び出す。
3. その場での動作。 走り/歩きのプロンプトはその場で、固定された方向を向いて行う。カメラのパン、背景のスクロール、シーンの変更は禁止。被写体はおおよそ中央に留まる。
4. 無地のマゼンタ背景 をベースに設定し、ビデオプロンプトでも維持する（#FF00FF / 純粋なマゼンタ）。フラッドフィルクロマに必要。
5. PIL/Canvasでアートを捏造しない。 ベースアートは imagine_text_to_image またはユーザー/ローカルの静止画から取得する。スクリプトは後処理のみを行う。
6. ユーザーが統合を要求しない限り、実験的な出力をゲームに組み込まない。
7. ゲーム用途には1つの移動サイクルを推奨。 プレビューでは6秒のマルチサイクルクリップ全体から高密度サンプリングしてもよい。エンジンシート用には、ビジュアルQC後にオプションで単一サイクル（12～16フレーム）を再サンプリングする。
8. 完了時に、動画、クリーンアップされたフレーム、ストリップ、プレビュー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サイド）、足は下部3分の1付近
• 参照が存在する場合はプロジェクトの他の部分と同じアートスタイル
• テキスト、UI、透かし、2番目のキャラクターがないこと

返された 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: ユーザーが 720p を要求しない限り 480p
• prompt: 1つの短い現在形のショット（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. QC

視覚的に確認:

• プレビューGIFが大きなポップなしでループする
• マゼンタが除去されている（無地のピンクブロックなし）；フリンジは許容範囲か、再キーイング
• 足が安定したベースラインに留まっている（悪いクロップによるホップなし）
• アイデンティティがおおよそ安定している（顔/服が毎フレーム変化しない）
• アクションがその場で行われている（フレーム外に滑り出さない）
• ゲーム用途: 1つのカウントを選択（多くの場合16または24）または1つの真のサイクルをカット

アイデンティティが大きくドリフトするか、ピクセルが柔らかすぎる場合は、プロダクションシートには $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秒のマルチサイクルクリップは完全な1ループではない、アセットの肥大化。 経験則: 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 — ループ/フリップテスト/モーション法則およびエンジン対応デフォルト。サンドボックス実行には引き続きこのスキルのスクリプトを使用する（マゼンタ背景 + クロマ）。自由形式の背景色は使用しない。