blockbench-flipbook-textures

Blockbench のフリップブックテクスチャ

サイズが同一のアニメーションフレームを縦に並べた PNG を作成し、タイミングと指定されたターゲットに必要なメタデータを確認します。N フレームがそれぞれ W × H ピクセルの場合、最終的なビットマップは W × (H * N) です。フレーム 0 を最上部に配置し、フレーム間に余白は設けません。各フレームは、完全なタイルまたは完全な UV アトラスにします。

必要なスキルとツール

• Blockbench のコンテンツを変更する前に blockbench-use を読み込み、UV の確認と割り当てには blockbench-texturing を読み込みます。
• アートワークを生成または再ペイントする場合は、必ず blockbench-gpt-image-textures を使用してください。 FAL_KEY の処理を含め、GPT Image 2.5 Flare/Sunburst のワークフローとスクリプトを使用します。別の画像モデルに黙って置き換えないでください。依存関係またはモデルが利用できない場合は、不足している機能を説明し、生成に依存しないレイアウトや変換の作業を続行します。既存の提供済みシートの変換に、追加の生成呼び出しは必要ありません。
• 同梱のコンバーターには Python 3.10 以降と Pillow を使用します（選択した環境で python -m pip install Pillow を実行）。測定した領域の切り抜きと縦方向の組み立てには ImageMagick も使用できます。フレームの境界全体、明示的な数値順、およびアルファチャンネルを保持してください。

スクリプトのパスは作業ディレクトリではなく、インストール済みスキルを基準に解決してください。以下のコマンドは、このスキルのフォルダーが現在のディレクトリであることを前提としています。出力はユーザーのアセット用ワークスペースに保存してください。

1. アニメーションの仕様を決める

すでに提示されている要件を再利用します。生成前に、結果を左右する未確定事項を確認してください。対象・エフェクト、ピクセルアートかペイント調か、フレームごとのピクセルサイズ、フレーム数、再生時間/FPS または 1 フレームあたりのティック数、ループ再生か一度だけの再生か、透明度、空間方向のタイル化、および用途（Blockbench のプレビュー、Java リソースパック、Bedrock のブロック、またはエンティティ）です。提供されたシートのサイズをフレームサイズだと推測しないでください。タイミングだけが未指定の場合は、1 フレームあたり 2 ティック（10 FPS）を提案し、その前提を明示してください。

以下の値はそれぞれ独立して扱ってください。

数量	意味
W, H	1 フレームあたりの最終ピクセルサイズ。通常の Minecraft ブロックタイルには正方形のフレームを使用します
N	書き出すストリップ内の物理フレーム数
U, V	1 フレーム全体の論理 UV 寸法。W, H と異なる場合があります
C, R	生成元シートの列数と行数。C * R >= N である必要があります
S	生成時の整数アップスケール。生成元セルは W*S × H*S です
T	Minecraft のメタデータに指定する、1 フレームあたりの正の整数ティック数。FPS = 20/T

単純な順次再生サイクルの場合、再生時間は N*T/20 秒です。カスタム再生スケジュールでは再生時間が変わります。要求された FPS を正確に表現できない場合は、ティック数の丸めについて説明してください。プレビューと書き出しでは、選択した値を維持してください。Minecraft の標準的なテクスチャメタデータはループ再生です。一度だけ再生するには、存在しないループフラグを作らず、ターゲット固有の制御を使用する必要があります。

既存のモデルでは、get_capabilities、list_textures、および関連する get_cube_uv / get_mesh_info の結果を確認します。1 フレーム分の UV レイアウトと比率を、すべてのフレームで維持してください。単独でタイル化するテクスチャには、架空のジオメトリや使い捨てのモデルではなく、セル全体を明示したレイアウトが必要です。ボーン/キーフレームアニメーションは別のワークフローです。

2. GPT Image 2.5 でシートを生成する

必要な GPT 画像テクスチャスキルと、そのAPI の制約を読み込みます。レイアウトを考慮したプロンプトを各フレーム内で適用し、そのレイアウトを各ソースセルのオフセット位置で繰り返します。単独のタイルでは、セル全体がレイアウトになります。一時的なシートのグリッドを説明するときも、既存モデルの UV は変更しないでください。

生成器がアスペクト比と解像度を扱える場合に限り、縦長のソースシートを優先します。それ以外の場合は、コンパクトなグリッドを選択します。検証済みの fal カスタムサイズ制限は、16 の倍数、655,360 ピクセル以上 8,294,400 ピクセル以下、長辺 3840 以下、アスペクト比 3:1 以下です。必要に応じて、依存関係の最新の API リファレンスを再確認してください。アップスケールでは、過大なアスペクト比を修正できません。最終的な指定寸法を変更せずに、別のグリッド、計測した外側の余白、または明示的に計画したバッチを選択してください。fal スキーマを参照してください。

プロンプトの構成、座標の計算方法、16 フレームの例については、シートのプロンプト作成を読んでください。次の内容を明示します。

• キャンバスとセルの正確な矩形、行優先の時系列順（左から右、次に上から下）、使用するセル、末尾の未使用セル。
• 固定するカメラ、フレーミング、オブジェクトのアンカー、スケール、パレット、ライティング、共通の UV アイランド位置。被写体を個別に変化させるのではなく、各フレームの動きのフェーズを説明します。
• ループでは最後から最初へのシームレスな遷移を指定します。意図的な静止区間で重複が必要な場合を除き、0 と 1 の両方を含めず、フェーズ i/N をサンプリングします。テクスチャをタイル状に並べる必要がある場合は、空間的に継ぎ目のないエッジを別途指定します。
• 不透明なタイルではセル全体を覆い、透明なスプライトでは実際のアルファを使用します。ラベル、仕切り線、キャプション、装飾的な枠線、焼き込みのチェッカーボードは使用しません。

次のように、依存関係のスクリプトを使って生成します。

bun ../blockbench-gpt-image-textures/scripts/fal_gpt_image.mjs --prompt-file /path/to/prompt.json --model flare --width 1024 --height 1024 --background transparent --quality medium --num 1 --format png --out /path/to/output --label portal_sheet

不透明なタイルには不透明な背景を使用します。プロンプトとダウンロードした元ファイルを保存します。変換前に、実際に返された寸法、レイアウト、各フレームの内容、アルファを確認します。API でキャンバスの正確なサイズを指定しても、セルの境界が正確になるとは限りません。内容に大きな欠落、重なり、不整合がある場合は、プロンプトを修正するか、必要な生成スキルで該当するアートワークを編集します。スライスしても動きの問題は修正できません。不一致の原因を特定せずに、生成を繰り返さないでください。

3. 縦型フリップブックに正規化する

4×4 の 256×256 セルで構成された、検証済みの 1024×1024 ソースを、32×32 フレーム 16 枚にする場合：

python scripts/sheet_to_flipbook.py /path/to/source.png /path/to/portal.png --grid 4 4 --count 16 --frame-width 32 --frame-height 32 --ticks-per-frame 2 --preview /path/to/portal-preview.apng

これにより、静的な 32×512 RGBA PNG、確認用のオプションのループ APNG、標準出力への JSON レポートが生成されます。APNG はプレビュー用であり、Blockbench や Minecraft にインポートするテクスチャではありません。アセットを引き渡す際は、標準出力をレポートファイルに保存してください。このコンバーターはゲームのメタデータを書き込みません。

• すでに縦型の場合は --grid 1 N、横型の場合は --grid N 1 を使用します。縦型ソースの寸法、順序、アルファがすでに正確な場合は、検証後にそのまま使用できます。
• 末尾に未使用のセルがある場合は --count N を使用します。物理フレームが連続していない場合や重複している場合は、--count ではなく --indices 0,1,2,1 を使用します。これらのインデックスはソースのセルを選択します。ゲームのメタデータのインデックスは生成後のストリップを参照します。同じ並べ替えを二重に適用しないでください。
• 外側の余白や均一な溝がある場合は、グリッドの境界に --crop X Y W H、セル間に --gap X Y を指定します。単位はすべてソース画像のピクセルです。
• 配置が不規則な場合は、--rects /path/to/rectangles.json を渡します。たとえば [[8,8,256,256],[280,8,256,256]] のような JSON 配列を時系列順に並べます。矩形はすべて同じ寸法で、ソースの範囲内に収まる必要があります。アンカー位置を一定にしてセル全体を測定してください。スプライトごとに不透明部分の境界を個別にトリミングすると、揺れが生じます。
• ピクセルアートの場合、デフォルトのニアレストネイバーサンプリングで輪郭が保たれます。ペイント調のアートには --resample lanczos を使用します。各フレームはリサイズする前に切り抜かれます。グリッド全体を細いストリップにリサイズしないでください。
• デフォルトではアルファを保持します。二値の切り抜きアルファにする場合に限り、--alpha-threshold 128 を使用してください。煙や柔らかな光彩にはしきい値を適用しないでください。アルファのスナップでは、生成時に背景が不透明になってしまった場合、それを取り除くことはできません。

このヘルパーは、セルが小数になる指定、アスペクト比の変更、無効なインデックス、ソースへの上書きを拒否します。既存の出力を上書きするには --overwrite が必要です。測定に誤りがある場合はレイアウトの入力を修正してください。クロップを推測したりセルを引き伸ばしたりして、検証を回避しないでください。

4. インポート、設定、検証

ランタイムメタデータをインポートまたは生成する際は、Blockbench and Minecraft deliveryを確認してください。有効なフォーマットで animated_textures、per_texture_uv_size、texture_mcmeta がサポートされているか確認してください。意図したプロジェクトを維持し、利用可能な MCP ツールまたはネイティブダイアログを使用してください。

静的ストリップを create_texture でインポートし、意図した要素のみに割り当ててください。テクスチャごとの UV サイズをサポートするフォーマットでは、確定済みの1フレーム分の値 uv_width=U、uv_height=V を指定してください。ストリップの高さを1フレーム分の UV 高さとして使用しないでください。それ以外のフォーマットではプロジェクトの UV 寸法が使用されるため、変更する前に既存のテクスチャへの影響を確認してください。サポートされているテクスチャプロパティまたはアニメーション UI でタイミングを設定してください。存在しない set_flipbook ツールを想定したり、ドキュメントに記載されていないパラメーターを create_texture に渡したりしないでください。

納品前に、以下を検証してください。

• PNG の寸法が正確に W × H*N であること。各フレーム全体の向きと順序が正しく、アンカーが安定し、適切なアルファが設定されていること。
• list_textures で bitmap_size=[W,H*N]、frame_size=[W,H]、意図した uv_size=[U,V] が報告されること。ビットマップの高さをフレームの高さで割って、フレーム数を検証してください。
• APNG と Blockbench の実際のフレームをいくつか確認してください。最後から最初への遷移も含めて確認します。クリッピング、時間的なちらつき、意図しない重複、UV アイランドのずれ、空間的な継ぎ目、想定する表示サイズでのフィルタリングを確認してください。静止スクリーンショットだけでは再生を証明できません。
• 対象のメタデータをエクスポートした PNG と一致させ、可能な場合は対象ランタイムで検証してください。Java では .png.mcmeta を使用します。Bedrock のブロックでは textures/flipbook_textures.json とテクスチャアトラスのバインディングを使用します。Bedrock のエンティティには、専用の UV アニメーション／マテリアル設定が必要です。

ストリップ、要求されたメタデータ、ソースプロンプト／シート、変換レポート、任意のプレビューを、寸法・枚数・タイミングを簡潔に添えて納品してください。実際に実行したプレビューとランタイムチェックを明記してください。PBR アニメーションでは、すべてのチャンネルでフレームのジオメトリ、順序、タイミングを揃えてください。隣接するフレームがフィルターで混ざらないよう、フレームごとに個別に処理してください。