perfectpixel

PerfectPixel — AI アニメーションスプライト生成

インストール型デスクトップアプリと同じ生成パイプライン（プロンプト → AI 画像生成 → 背景除去 → フレーム抽出 → 品質チェック → 補正再生成 → ピクセル量子化）をヘッドレス CLI（ppgen）で実行し、ゲームですぐに使えるスプライトバンドルを作成します。

このスキルを使う場面

• ユーザーがキャラクター／動作アニメーション／スプライトシート／8方向セットの生成を依頼したときに使用します。
• god-tibo-imagen（Codex ChatGPT バックエンド）または gemini（Google AI Studio）モデルを使って、高品質で一貫性のあるスプライトを生成したいときに使用します。
• 1行のテキスト説明でキャラクターを定義し、100種類以上の動作プリセットを適用してアニメーションを生成するときに使用します。
• 5方向を AI で生成し、3方向を水平反転することで、効率的に8方向のスプライトセットを構築したいときに使用します。

手順

Step 0 — 事前準備（実行のたびに最初に行う手順）

ppgen バイナリを確認／インストールします。この SKILL.md があるディレクトリ（＝スキルルート）でインストールスクリプトを実行します。成功したら、バイナリの絶対パスを最終行に出力します。

# SKILL_DIR = 이 SKILL.md 파일이 있는 디렉토리의 절대경로로 치환할 것.
PPGEN="$(bash "$SKILL_DIR/scripts/install.sh" 2>/tmp/ppgen-install.log | tail -1)"
echo "$PPGEN"   # 이후 모든 ppgen 호출에 이 경로를 사용

Step 1 — API キーとプロバイダーの設定

ppgen は次の順序でキーを探します：config.json（インストール型アプリの設定）→ 作業ディレクトリ／実行ファイルの隣にある .env・.env.local → OS 環境変数 → CLI の -key フラグ。

• Gemini：GEMINI_API_KEY（または GOOGLE_API_KEY）を設定します。デフォルトモデル：gemini-3-pro-image
• GodTiboImagen：god-tibo-imagen プロバイダーはローカルの ~/.codex/auth.json を使用するため、別途 API キーは不要ですが、CLI を実行するには -key dummy のようにダミーキーを渡す必要があります。デフォルトモデル：gpt-5.4

Step 2 — リクエストの解釈 → フラグへのマッピング

ユーザーの自然言語によるリクエストから次の情報を取り出し、ppgen フラグに割り当てます。

• キャラクターの説明 → -desc "..."（英語のプロンプトを推奨）
• スタイル → -style のいずれか：pixel（デフォルト）、chibi、cartoon、retro16
• 作成する動作 → -states "idle,walk,attack"（カンマ区切り）。動作名は英語のプリセットキーです。
• プロバイダーの指定 → -provider god-tibo-imagen または -provider gemini
• モデルの指定 → -model gpt-5.4 または -model gemini-3-pro-image
• 出力フォルダー → -out ./output-dir（デフォルトは ./perfectpixel-out）

Step 3 — 実行

機械可読な要約を受け取るため、必ず -json を付けて実行します。

"$PPGEN" \
  -provider god-tibo-imagen \
  -desc "a small knight with silver armor and a blue plume" \
  -style pixel \
  -states "idle,walk,run,attack" \
  -out ./knight-sprites \
  -key dummy \
  -json

例

例 1：god-tibo-imagen を使った基本キャラクターと idle アニメーションの生成

"$PPGEN" \
  -provider god-tibo-imagen \
  -desc "a tiny blue slime" \
  -states "idle" \
  -out ./slime-sprites \
  -key dummy \
  -json

例 2：gemini を使った8方向の歩行アニメーションの生成

"$PPGEN" \
  -provider gemini \
  -desc "a red wizard with a staff" \
  -dirset "walk" \
  -out ./wizard-walk-8dir \
  -key "$GEMINI_API_KEY" \
  -json

ベストプラクティス

1. 試験実行：コストと時間を節約するため、まず1つの状態で試験実行（-states idle）してスタイルと品質を確認し、ユーザーの承認後にすべての状態を生成してください。
2. 背景色の指定を守る：AI モデルがマゼンタ（#FF00FF）の単色背景を完璧に塗るよう、プロンプトで背景色を明確に指定します。また、マッティング時にキャラクターが消えないよう、キャラクターのデザインにはマゼンタ／ピンク／紫系の色を避けてください。
3. 品質補正ループ：-attempts フラグ（デフォルトは3回）を活用し、フレーム数の不一致やキャラクターのアイデンティティの変化（identity drift）が検出されたときに、補正ヒントを自動で挿入して再生成するようにしてください。

参考資料

• gykim80/perfectpixel-studio
• NomaDamas/god-tibo-imagen
• PerfectPixel 動作プリセットカタログ
• PerfectPixel プロバイダー／モデル／設定