aldegad/sprite-gen

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

sprite‑gen とは？

sprite‑gen は、Python ベースのコマンドラインツール（および Codex/Claude スキル）で、ゲームキャラクターの単一の静的イラストを、すぐに使えるスプライトシートに変換します。仕組みは以下の通りです。

画像モデル（例: Grok Imagine、Codex、Claude）にプロンプトを送り、各アニメーション状態（待機、歩行、攻撃など）の一連のフレームを生成します。
背景のクロマキーを除去し、クリーンな透明 PNG フレームを抽出します。
それらのフレームをアトラス（sprite‑sheet‑alpha.png）にまとめ、機械可読なマニフェスト（manifest.json.frame_layout）を生成します。このマニフェストには、各フレームの正確な矩形、FPS、ループの有無が記録され、ゲームエンジンが利用できます。
オプションで、ビデオクリップからループを生成、パレットの再色付け、待機ループの追加、複数アセットからの簡単なシーン構築も可能です。

このツールは、手動で全フレームを描く時間やスキルがないインディー開発者やホビイストを対象としています。

主な機能（README より）

機能	説明	使用方法
アトラス行パイプライン (A)	1つのベース画像から、透明なスプライトシート＋マニフェストを生成。自動「呼吸」待機ループを含む。	`prepare → gen-set → extract → compose-atlas`（CLI コマンド）
ビデオからループ生成パイプライン (B)	ベース画像をビデオモデルに入力し、各モーション状態のシームレスな透明ループを生成。クリップを自然な周期で切り出します。	`video-set`（ジョブ作成）→ `video-canvas → video → video-frames → video-loop`
キュレーション Web ビュー	最終アトラスを焼き込む前に、生成フレームを比較、拒否、微調整できるインタラクティブ UI。	`sprite-gen curation --run-dir <run>`（オプション）
ユーティリティ (C)	単一画像の切り出し、マルチセルシートのスライス、既存アトラスのフレームへの展開。	`cutout`, `slice-sheet`, `unpack-atlas`
後処理 (D)	決定論的な再色付け、レイヤー合成、Aseprite/Phaser/Flame 形式へのエクスポート。	`recolor`, `compose-layers`, `export-aseprite`
アセットツール (E)	タイル背景の作成、投影シャドウの生成、モーションタイミングと接触点の検査。	`background-tile`, `shadow`, `inspect-motion`
シーン作成 (S)	複数のスプライトアトラスと他の PNG を組み合わせて、カメラとライティングメタデータ付きのシーン（PNG、MP4、GIF）をレンダリング。	`scene-render`, `scene-inspect`
向き/利き手の処理	横視点スプライトの左右の向きを検出または強制。間違っていればミラーリングまたは再生成。	`--facing`, `--facing-fix` フラグ（`gen`/`video-set`）
複数プロバイダーのサポート	Codex、Claude、Grok Imagine、およびサーバーサイド用の明示的な `openai` プロバイダーに対応。	`--provider codex` など
決定論的な出力	同じ入力 → 同一の出力バイト（バージョン管理に重要）。	`recolor-palette` + `recolor` パイプライン

誰に役立つか？

インディーゲーム開発者: ピクセルアートキャラクターが必要だが、全アニメーションフレームを手描きする時間やスキルがない。
ピクセルアート愛好家: AI 生成のモーションループを試しつつ、最終アセットを完全にコントロールしたい。
ツールビルダー: パイプライン（例: ゲームアセットの CI）用に、プログラム可能なスプライトアトラス生成が必要。

クイックスタート（README より）

# 1. クリーンな venv を作成し、パッケージをインストール
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. 単一のキャラクター画像からアトラスを生成
sprite-gen prepare --out-dir run --character-id hero --base-image base.png
sprite-gen gen-set --run-dir run --provider codex   # フレーム行を生成
sprite-gen extract --run-dir run                  # 透明 PNG を作成
sprite-gen compose-atlas --run-dir run            # sprite-sheet-alpha.png + manifest.json を生成

# 3. (オプション) キュレーション UI を開いてフレームを調整
sprite-gen curation --run-dir run

ビデオベースのループの場合、RIFE を一度インストール（sprite-gen rife install）し、video-set ワークフローを実行します。

制限と注意点（README より）

生成フレームの品質は基盤となる画像/ビデオモデルに依存します。ツールはフレームを微調整またはミラーリングするのみで、完璧な向きを保証するものではありません。
方向検出（--facing-fix）はデフォルトで記録のみで、高信頼度でも誤る可能性があります。
一部のパイプライン（例: ビデオループ）では、外部認証情報（grok CLI ログインまたは XAI_API_KEY）が必要です。
「walk/run」の循環ループは、モーション QA が通るまで実験的とされています。
Python 3.11 以上が必要です。3.10 はサポートされなくなりました。

ライセンス

Apache‑2.0 – 商用・非商用問わず無料で使用可能。

上記の情報はすべてリポジトリの README から直接引用したもので、外部の推測は一切加えていません。