blockbench-gpt-image-textures

GPT Image 2.5 による Blockbench テクスチャ

fal.ai で GPT Image 2.5 を使ってテクスチャ画像を生成し、既存の Blockbench UV レイアウトに適用します。プロンプトには UV レイアウト、つまり画像のどのピクセル範囲がどの面に対応するかを含める必要があります。これがないと、モデルはアトラスではなく絵を描いてしまいます。

検出と検証のルールについては、まず blockbench-use を読み込み、UV の確認とクリーンアップ用のペイントについては blockbench-texturing を読み込んでください。

モデルを選ぶ

モデル	fal エンドポイント	用途
Flare（デフォルト）	openai/gpt-image-2.5/flare/text-to-image	高速な下書き、大半のアトラス、透明な背景
Sunburst	openai/gpt-image-2.5/sunburst/text-to-image	複雑なディテールを含む最終的な高解像度アトラス。生成には時間がかかります

どちらも同じパラメーターを受け付け、参照画像を使う /edit バリアントを共有しています。詳細、料金、レシピについては、references/fal-api.md を参照してください。

ワークフロー

0. ジオメトリとディテールのバランスを決める

新しいモデルや大幅な再設計では、ジオメトリの確定やアトラス生成の前に、blockbench-use を通じて外観と精度、パフォーマンス、またはバランス重視のどれを優先するかを決めてください。外観とパフォーマンスの計画を適用し、簡略化した目標ジオメトリと共有 UV タイルを先に確定します。HD 画像のリクエストは、小さなディテール用キューブを増やしてよいという意味ではありません。

パネルで表現するブレースや手すりの充填部分では、アトラスの島の外側だけでなく、寸法を測った各 UV 領域の内側に、繰り返し模様と透明な穴を記述します。既存の面に表現する留め具については、その領域にアルベドの模様を含め、対応する法線／高さ／MER ディテールにはPBR ワークフローを使用してください。チャンネルデータは個別に検証してください。カラーアトラスは PBR マップではありません。カスタムブロックで切り抜きや複数のマテリアルを使用する場合は、Bedrock のマテリアルバインディングを確認してください。

1. まず UV レイアウトを確定する

プロンプトを作成する前に、Blockbench でアトラスのレイアウトが存在している必要があります。get_capabilities: include_tools=true を実行し、次に list_textures を実行してください。テクスチャも UV も存在しない場合は、texturing スキルの説明に従ってネイティブのテクスチャテンプレートを生成してから続行します。モデルが持っていないレイアウトをプロンプト内で作り上げないでください。

生成前に、UV のスケールと歪みに関するガイダンスを使ってレイアウトを監査してください。有効なフレームと論理 UV サイズを使い、面の両方向に沿って、サーフェスの寸法とサンプリングした画像ピクセル数を比較します。意図しない伸張やマテリアルスケールの不整合があれば、先に修正してください。画像生成モデルは、長方形の内側をペイントするだけで歪んだマッピングを修正することはできません。同じスウォッチ全体を再利用するのは、面の寸法が適合する場合、または意図的な例外の場合に限り適切です。

レイアウトを収集します。

list_textures                              # frame_size and uv_size of the target atlas
get_cube_uv: id="<cube uuid>"              # one call per textured cube
get_mesh_info: mesh_id="<uuid>", include_uv=true   # meshes, if any

生の結果を 1 つの JSON ファイルに保存します。

{ "textures": [ ...list_textures... ], "cubes": [ ...get_cube_uv results... ],
  "meshes": [ { "name": "cloth", "faces": [ { "key": "f1", "uv": [[40,40],[56,40],[56,52],[40,52]] } ] } ] }

2. キャンバスと領域を計算する

fal は 655,360 ピクセル未満の画像を受け付けないため、64x64 のアトラスはネイティブサイズでは生成できません。整数倍に拡大して生成し、後で縮小します。スクリプトがスケールを選び、各面の矩形を生成画像のピクセルに変換します。

node scripts/uv_layout_prompt.mjs inspection.json --texture <atlas name|uuid> > layout.json
node scripts/uv_layout_prompt.mjs inspection.json --format text   # human-readable check

出力には image_size（変更せず fal に渡します）、canvas.texel_scale、各面に 1 つずつ対応し px と texels の矩形を含む領域、および同じピクセルを再利用する面の shared_regions が含まれます。終了コード 2 はアトラスの縦横比が 3:1 を超えていることを示します。パディングしたキャンバスを生成し、手順 5 で --crop を使ってクロップするか、アトラスを分割してください。

canvas.texel_scale は生成時の拡大率を示すもので、モデル上のマテリアル密度ではありません。サーフェスの寸法はジオメトリから別途収集してください。領域のリストだけでは、モデル単位あたりのピクセル数を確定したり、局所的なメッシュの歪みを検出したりできません。

3. レイアウトを含めてプロンプトを書く

プロンプトは JSON として構成します。layout ブロックは必須で、ステップ 2 の内容をそのまま使用します。テンプレート、領域の説明ルール、記入例の詳細については、references/uv-layout-prompting.md を参照してください。最小限の形式は次のとおりです。

{
  "type": "UV texture atlas for a low-poly 3D game model, flat orthographic texture sheet, not a 3D render",
  "subject": "brown alpaca, cartoon Minecraft style",
  "style": "crisp pixel art, each texel a solid 16x16 px block, no anti-aliasing, 12-color palette, flat unlit colors",
  "canvas": { "width": 1024, "height": 1024, "texel_scale": 16, "represents": "64x64 texel atlas" },
  "background": "fully transparent outside the listed regions",
  "regions": [
    { "name": "head/north (face)", "px": [128, 128, 256, 256], "paint": "front of the head: two dark eyes, muzzle, no outline" },
    { "name": "head/up",   "px": [128, 0, 256, 128], "paint": "top of head fur, seam-continuous with head/north" }
  ],
  "rules": [
    "paint every region edge to edge; leave everything else transparent",
    "no labels, grid lines, borders, drop shadows or text anywhere",
    "adjacent faces of one cube must continue seamlessly across their shared edge",
    "regions listed as shared receive identical content"
  ]
}

3D シーンではなく、各面に何が描かれているかを説明します。領域名には立方体と方向を含め、計算されたピクセル矩形を正確に保ち、スクリプトが報告した回転やミラーリングについても記載します。

素材の詳細を記述する場合は、各領域のモデル単位での表面範囲、木目の方向、関連する領域間で統一された模様の大きさを説明します。通常、より大きな面には同じ木目やパターンがより多く繰り返し表示されます。素材ごとに説明をまとめる場合も、個々の UV フットプリントを維持してください。異なるサイズの面すべてに、素材全体の矩形を割り当てないでください。これらの選択をすべての PBR チャンネルと調整してください。

4. 生成する

FAL_KEY=... node scripts/fal_gpt_image.mjs --prompt-file prompt.json --model flare \
  --width 1024 --height 1024 --background transparent --quality medium --num 2 --out ./output --label alpaca

layout.json の image_size にある --width/--height を使用します。--background transparent を指定すると Flare では実際のアルファが生成されます。Sunburst の出力では、アルファに頼る前に確認してください。まず medium の品質と --num 2 を指定して候補を選び、最終版にのみ high または xhigh を使用します。--dry-run は確認用にリクエスト本文を出力します。ダウンロードはスクリプト内で行われます。fal の URL は有効期限があります。

5. アトラスのサイズに縮小する

texel_scale が 1 の場合は、このステップを省略します。それ以外の場合は、最近傍法で各テクセルブロックの中央をサンプリングし、ピクセルアートではアルファをスナップします。

python scripts/resize_to_atlas.py output/alpaca_<ts>.png output/alpaca_64.png --width 64 --height 64 --alpha-threshold 128

高解像度の絵画調アトラスでは --sample average を使用します。また、余白のあるキャンバスを先にアトラスのアスペクト比に合わせて切り抜くには、--crop X Y W H を使用します。

6. Blockbench にインポートして適用し、確認する

create_texture: name="alpaca", data="<absolute path to alpaca_64.png>"
apply_texture: id="<group or element>", texture="alpaca", applyTo="all"
get_texture: texture="alpaca"
capture_screenshot

per_texture_uv_size を使用する形式では、元のアトラスの uv_size に一致する uv_width/uv_height を create_texture に渡します。レンダリングしたモデルを確認し、領域のずれ、継ぎ目からのにじみ、コンテンツのミラーリング、木目や凹凸のスケールの不一致がないかを調べます。一時的なチェッカーを使って、マッピングの歪みとアトラスに描き込まれたディテールの不一致を区別します。長辺・短辺、側面・端面を、近距離と想定する表示距離の両方で確認します。

生成された境界がずれている場合は、予定した UV フットプリントに合うように素材を再描画するか、範囲を広げます。生成されたコンテンツの境界に合わせて各面の UV 矩形を個別に調整することは避けてください。アスペクト比と密度の両方が変わる可能性があります。UV の編集が必要な場合は、比率と意図した密度を維持し、対応する PBR 領域を更新して、スケールを再確認してください。画像の小さな誤りは、テクスチャリングスキルのペイントツールで修正します。大きな誤りの場合は、前回の出力 URL を指定し、変更する領域だけを明記したプロンプトで /edit エンドポイントを使って反復します。

カラーアトラスが完成したら、画像モデルで PBR チャンネルを生成するのではなく、albedo to normal を使って法線マップ、高さマップ、MER マップを作成します。各マップのテクセルグリッドを一致させるため、縮小後のアトラスに対して実行してください。

想定される結果

• モデルはピクセル単位の矩形を厳密な指定ではなく目安として扱います。領域の境界では1～3テクセル程度ずれたり、内容が透明な余白にはみ出したりすることがありますが、縮小とクリーンアップの工程で大部分を補正できます。
• 小さな領域をたくさん使うより、少数の大きな領域を使う方がうまくいきます。領域が約20を超えるアトラスでは、プロンプトで部位ごとにまとめ、共有領域は一度だけ説明してください。
• 「各テクセルを16x16 pxの単色ブロックにする」といったピクセルアートの表現を使うと、ブロックがテクセルのグリッドに揃います。こうした表現がないと、モデルがアンチエイリアスを適用し、縮小後にエッジがぼやけます。
• /edit に image_urls として渡すレンダリング済み UV テンプレートやチェッカーは、テキストだけの場合よりもレイアウトの基準としてはるかに確実です。capture_screenshot またはネイティブのテンプレートテクスチャを使用してアップロードし、同じ layout ブロックを使って「このテクスチャシートに色を塗って」とプロンプトで指示してください。
• 長いテキスト、ロゴ、読みやすいラベルは別の工程で作成してください。レイアウトのルールと競合します。
• すべての出力は完全な RGB(A) 画像です。モデルが領域外に描画するのを防ぐものはありません。プロンプトではなく、get_cube_uv の矩形と照らし合わせて確認してください。

リソース

• references/fal-api.md：エンドポイント、パラメーター、サイズ、料金、透過、curl／Node／Python のレシピ、編集エンドポイント。
• references/uv-layout-prompting.md：プロンプトテンプレート、ボックス UV ネットの説明方法、面ごとの矩形とメッシュアイランド、Bedrock エンティティ、Java ブロック、Generic Model のターゲット別の実例。
• scripts/uv_layout_prompt.mjs：検査用 JSON からキャンバスサイズとピクセル領域を生成します。
• scripts/fal_gpt_image.mjs：Flare または Sunburst（テキストから画像生成、または編集）を呼び出し、結果を保存します。
• scripts/resize_to_atlas.py：最近傍法またはボックス法でアトラスのサイズに縮小します。オプションでクロップとアルファのスナップにも対応します（Pillow が必要です）。