generate2dsprite

2D スプライトを生成する

ゲームに必要な最小限のアセットバンドルを、実際の表示サイズ、カメラ、スタイルに合わせて作成します。 ゲームロジック（当たり判定、ダメージ、タイミング）はアートから独立させます。

使用する場合

• キャラクター、クリーチャー、小道具、アイテム、アイコン、エフェクトを、マスター静止画、スプライトシート、またはクリップとして用意する必要がある場合。
• フレームがすでに存在し（生成済み、描画済み、コードで描画済み）、クリップ、パレット、またはエンジン向けの書き出しが必要な場合。

使用しない場合

• マップ、タイル、地形、視差効果、シーンプレート：generate2dmap。
• キャラクターのアニメーション：video2dspriteでアクションごとのクリップを作成する前に、ここでマスターを1つ承認します（video-handoff.md）。
• ユーザーが依頼したコード描画アート：codeart2d。API または CLI の呼び出しのみの場合：generate2dmedia。

機能の確認（セッションごとに1回）

python "<skill-dir>/../generate2dmedia/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.jsonを実行します。<tools>には、ご自身のツール一覧にあるメディアツール（image_gen、image_edit、image_to_video）を指定するか、noneを指定します。ROUTESブロックには、設定されているAPIキー（yes または no）、ローカル環境の準備状況、解決された優先順位が表示されます。encoding.stdoutでエラーが発生した場合は、PYTHONUTF8=1を設定します。

アートソース

キャラクター、クリーチャー、小道具、アイコン、エフェクトのアートソースには、画像生成をデフォルトで使用します。art_sourceとして（api、host_image、existing、または依頼があった場合に限りcode）を記録し、返信でルートを明記します。ユーザーが明示的に指定したルートが優先されます。

1. API：キーが設定されている場合は、OpenAI（OPENAI_API_KEY）、Google Gemini（GEMINI_API_KEY）、xAI（XAI_API_KEY）、BytePlus Seedream（ARK_API_KEY）、または fal.ai（FAL_KEY）を、環境またはユーザーの設定ファイルから使用します（route-media.md）。設定されたキーは所有者の同意を示すため、呼び出しごとに確認する必要はありません。
2. ローカル：利用可能であれば、ご自身の画像ツール（Codex image_gen、Grok のネイティブツール）を使用します。利用できない場合は、ユーザーがサインイン済みの Codex CLI、続いて Grok CLI を使用します。
3. codeart2d：コード描画アートをユーザーが明示的に依頼した場合、またはroute_media.pyがno-routeを出力した場合（終了コード3）に限り使用します。その場合は「コード描画、画像モデルなし」と伝えます。

すべての画像で、次のコマンドを使用します：python "<skill-dir>/../generate2dmedia/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1024x1024 --out-dir <new>。このコマンドは指定の優先順位でルートを選択し、route、artifact、sha256、estimateUsdを含むJSON行を1行出力します。resolve --kind imageを実行すると、どのルートが使われるか確認できます。ユーザー提供の既存アートはいつでも使用できます。実際に行っていない生成を行ったと主張してはいけません。プロンプトと仕様を保持し、機能が不足している場合はその旨を報告します。

• **仕上げ：**デフォルトはHDです。フルカラー、きれいなアルファ、登録点を1つに揃え、プリマルチプライド方式でゲーム内の高さに縮小します。ユーザーがピクセルアートを依頼した場合は、ピクセル仕上げ（共通パレット1つ、バイナリアルファ、ディザなし）を選択できます。論理ピクセルグリッドを画像モデルに指示してはいけません。ピクセルらしい見た目は仕上げによって作ります。
• **キャラクター：**キャラクターごとにマスター静止画を1つ承認してから、video2dspriteでアニメーション化します。すべてのアクションは、そのマスターからアクションごとに1つの画像から動画へのクリップとして作成します（sprite_set.py）。各アクションの胴体の高さは、マスターのレストポーズに合わせます。
• **スプライトシート：**エフェクト、アイコン、小道具、およびユーザー提供のフレームに使用します。キャラクターアニメーションには使用しません。

マスター静止画（すべてのキャラクターアニメーションはここから始まります）

キャラクターごとに承認済みのマスター静止画を1枚用意し、そこからアクションごとに1本の画像から動画を生成したクリップを作成します（video2dsprite）。シートはFX、アイコン、プロップ用です。文言についてはprompt-rules.md、コマンド、フレーミング、master.jsonについてはmaster-still.mdを参照してください。

1. 仕様（--spec <json>および／またはフラグ）：--name、--subject、--identity（詳細かつ正確に記述）、--facing left|right|front|back、--class hero|mob|boss|prop、--finish hd|pixel（デフォルトはHD。pixelは指定された場合のみ）、--identity-ref（1枚目の画像。内容をそのままコピー）、--style-ref（2枚目：承認済みの同系統スプライト。スタイルとフレーミングのみ）、--key（デフォルトは#FF00FF。紫やピンクのデザインには緑または青）。
2. 生成：python "<skill-dir>/scripts/master_still.py" generate --spec <json> --takes 3 --output-dir <new>を実行します。各テイクはgenerate2dmediaのroute_media.pyを経由して生成されます（まずAPIキーを使用し、次にローカルデーモンを使用）。takes.pngにはテイクが横並びで表示されます。終了コード3はルートがないことを意味します。その旨を伝えてください。フォールバックはcodeart2dです（「コードで描画。画像モデルは使用しない」）。ホスト独自の画像ツールを使う場合は、master_still.py promptを実行し、一覧にある参照画像をその順番で添付してください。
3. 見て選択します：アイデンティティ、向き、端に触れているものがないこと、テキストがないことを確認します。
4. 惜しい画像は、再生成ではなく編集で修正します：master_still.py edit --run <dir> --take N --change "<one change>" --output-dir <new>（または--master <dir>）。
5. 承認：master_still.py approve --run <dir> --take N --output-dir <new>を実行します（別の場所にある静止画の場合：--still <png> --route <what made it>）。静止画のキー処理を行い、6 pxの余白を付けて切り抜き、1024x1024上のクラス別フレーミングにLANCZOSで拡大縮小します（heroは高さ788 px、上余白138 px）。その後、master.png（不透明、純色のキー）、master_rgba.png、master.json（generate2dsprite.master.v1）を書き出します。
6. モーションの各ステップではmaster.json（identity_recap、facing、finish、class、framing、key、files、transform、route）を読み込み、静止画を再計測しません。すべてのクリップのプロンプトは「The same <identity_recap>」で始めます。

master.jsonのrouteに記載されたルートを報告してください。FORGE_ROUTE_MEDIA_FAKEの警告は、画像が実際に生成されたものではないことを意味します。

ホストに関する注意事項

• Codex： image_genは独自の画像ツールです。設定済みのキーがない場合はこれを使い、view_imageで結果を確認してください。このセッションで作成した画像がプロジェクト内にない場合は、python "<skill-dir>/../generate2dmedia/scripts/cli_media.py" adopt --codex-thread <thread-id> --output-dir <new>を実行し、その後generated.pngを処理してください。codeart2dとgenerate2dmediaは明示的に指定された場合のみ使用します。ここからそれらにルーティングされた場合は、該当するSKILL.mdを開いてください。
• Claude Code： 組み込みの画像生成機能はありません。route_media.pyはAPIまたはローカルCLIを使用します。作成したPNGはすべてReadで確認し、ツールはBashで実行してください。<skill-dir>は${CLAUDE_SKILL_DIR}です。
• Grok： ネイティブの画像・動画ツールは独自のツールです。実際のスキーマを使用してください。

コマンド

各ツールは、ユーザーのプロジェクトルートから1行で実行します：python "<skill-dir>/scripts/<tool>.py" ...。<skill-dir>はこのスキルのフォルダーです。兄弟スキルはその隣にあります（<skill-dir>/../video2dsprite）。入力と出力はプロジェクト内に保持してください。各ツールは新しい--output-dirに書き込みます。既存のディレクトリーは拒否され、隣にステージングした後、チェックが完了してから公開されます（--strict-qc／--strictでは、失敗時に何も公開されません）。成功時はJSONを1行出力し、エラー時はerror: ...を出力して終了コード1で終了します。使用法エラーは終了コード2です。Python 3.10以降、numpy、Pillowが必要です（scipyを推奨）。すべてのフラグは--helpに記載されています。

アセットを計画する

識別情報と参照画像、カメラと向き、スタイル、ゲーム内での表示サイズ、仕上がり（デフォルトはHD、希望があればピクセルアート）、アクションリストとフェーズ、ループかワンショットか、モーションの範囲、共通のルート位置、出力形式を記録します。キャラクターごとに、承認済みのマスターを1つ、ソースから表示サイズへのスケールを1つに保ちます。予定がない限り、モブはヒーローより背を高くしません。グリッド状に並べても滑らかになるとは限りません。ポーズ間隔、タイミング、ループのつなぎ目、接地のほうが重要です。ポーズ、NEAR/FAR の脚、タイミングについては、animation-planning.md を参照してください。

• アルファ：native_alpha は実際の透明度を保持します（描画された市松模様はアルファではありません）。chroma_key は、被写体に透明部分がない場合に限り、単色のマゼンタを使用します。opaque は画像全体を保持します（assemble_frames.py）。
• サンプリング：生成アートには lanczos またはプリマルチプライドアルファを考慮した面積リサイズを使用します。nearest は、ピクセルグリッドが検証済みの場合に限って使用します。高解像度でピクセルアート風に描かれた画像は、きれいな32 pxのアートではありません。
• 共通のルート位置は、フレームごとのアルファ境界ボックスの下端ではありません。意図した飛行、ジャンプ、上下動、反動を維持します。

生成（画像ルート）

プロンプトは自分で作成します（prompt-rules.md、グリッド、フェーズ、プリセットについては action-recipes.md を参照してください）。--reference（またはツールの実際の画像入力）で参照画像を添付します。文章中にパスを書いただけでは参照画像になりません。生成のたびに承認済みのマスターを含め、連鎖的な編集ではなく絶対的なフェーズを記述します。修正は、承認済みの静止画に対し、変更点を1つだけ指定して編集します。一度に1つのアクションファミリーを生成し、幅広い斬撃、軌跡、飛翔体はボディシートに含めないようにします。実際のルート、モデル、返されたサイズを確認します。プロンプトの内容から推測して断言してはいけません。

パイプライン

シート（FX、アイコン、プロップ）：生シートに対して sheet_qc.py spill を実行し、次に generate2dsprite.py process、続いて sheet_qc.py frames、scale_frames.py、build_animation_clips.py、export_engine.py の順に実行します。キャラクターアクションは、パッケージ化されたクリップとして video2dsprite から戻ります。

必要なこと	方法
画像ツール用のシートを計画する（アスペクト比、グリッド、ガイド、プロンプト）	plan_guide.py --frames N --cycle run --output-dir <new> を実行し、guide.png を添付して prompt.txt を貼り付けます。固定スケールと足元のラインには make_anchor_layout.py、安全な空フレームには make_layout_guide.py を使います
スライス前に生シートを確認する	sheet_qc.py spill --input <sheet> --rows R --cols C --output-dir <new> を実行します。パーツが交差している場合は、余白を増やして再生成するか、所有範囲ごとにスライスします。最大コンポーネントによるフィルタリングは決して行いません
シートをキー処理、スライスして登録する	generate2dsprite.py process --input <sheet> --target asset --mode <mode> --rows R --cols C --output-dir <new> --strict-qc を実行します（geometry v2、processing.md）
アートピクセルあたり M 個のソースピクセルで描かれたピクセルアート	process --resampler nearest --logical-pixel M --pixel-scale N を実行します（整数倍のスケールのみ）
1つの登録点を基準にしたジャンプ、上下動、反動	process --scale-strategy registered（または --anchor-px X,Y）を実行します
アクション間でキャラクター1体のスケールを統一する	接地した参照画像に対して process --write-scale-profile <p.json> を実行し、その後 --scale-profile <p.json> --max-profile-scale-drift 0.08 を指定します
キャンバスのサイズがグリッドで割り切れない場合、または行の順序を変更する場合	process --grid-rounding nearest または --pad-to-grid を実行します。--direction-order down,up,left,right（modes.md）
識別性、NEAR/FAR の交互配置、ドリフト、ベースライン	sheet_qc.py frames --sheet <sheet> --rows R --cols C --cycle run --output-dir <new> を実行します。ハーフサイクルが重複している場合は、後半を再生成します。コード描画フレーム（art_source=code）では、identity_residual と torso_drift は参考情報です
1つのキャンバスとルート上でゲーム内サイズを維持し、クランプしない	scale_frames.py --frames <pngs> --root-lock torso-x --row-baseline --emit-clips --ticks N --output-dir <new> を実行します。後続のアクションには --profile <first>/scale-frames.json --action-padding L,T,R,B を追加します
タイミング、イベント、トランジション付きのクリップ	build_animation_clips.py --manifest clips.json --output-dir <new> を実行し、リンターの結果と review/ を確認します（frames-and-clips.md）
フレーム全体またはシーンループ（キー処理なし）	assemble_frames.py を使います（--key chroma、--slice ownership。アンビエントループのみ --loop-overlap K --ambient を指定）
共有パレット、ロック、バリアント、ちらつき（ピクセル仕上げ）	palette_tool.py build、apply、lock、quantize-seq、variants、luts を使います。厳密な論理グリッドには pixel_reduce.py を使います（palette-and-pixels.md）
エンジンへのエクスポート	export_engine.py --clips <animation-clips.json> --target all --output-dir <new> を実行します。Sprite3D の場合は --target godot-sprite3d --world-height <units> を指定します（engine-export.md）
ゲーム内でクリップを再生する（歩行、ヒットストップ、トランジション）	runtime-integration.md を参照します
リクエストがあった場合のみ、コード描画スプライト、リグ、FX	codeart2d の render_pixelspec.py、rig_animate.py、または fx_build.py に --build-clips を指定して使います（process は決して使用しません）。その後、export_engine.py を実行し、コード描画であることを明示します

受け入れ基準

• ゲーム内のサイズで確認します。シルエットとキャラクターの識別性、接地と飛行、ループの継ぎ目またはワンショット再生後の復帰、明るい背景と暗い背景でのアルファ、手足などの先端部、アクション間のスケール、ルートとコライダーを確認します。
• 品質に関する主張には数値を添えます。pipeline-meta.json の matte.qa（key_ring_spill 警告が出た場合は、--despill-radius 1 または --key-quality soft を追加）、sheet-qc.json、クリップビルダーのリント結果を示します。数値による QC で症状は見つけられますが、解剖学的な妥当性や動作を承認することはできません。
• 公開された各 QA エンベロープから、すべての WARN または FAIL チェック（id、value、threshold、files）を原文どおり報告します。公開されたエンベロープに警告が1つでもある場合、「すべてのチェックに合格」とは決して述べないでください。
• 受け入れ済みのソースアート、ランタイム用フレームまたはクリップ、プレビュー、プロンプトと来歴（route、model、estimateUsd）、QA、残る制限を納品します。改訂時も、最後に受け入れられたバンドルを保持してください。

参考資料

processing.md（処理フラグ、レガシースイッチ）、modes.md、prompt-rules.md、action-recipes.md、character-animation.md（アニメーション索引）、frames-and-clips.md、palette-and-pixels.md、engine-export.md、runtime-integration.md、video-handoff.md。データコントラクトは references/schemas/sprite.schema.json を参照してください。