blockbench-substance

Blockbench + Adobe Substance 3D

任意の高度な機能です。 Blockbench での作業のほとんどでは必要ありません。blockbench-texturing でペイントし、blockbench-gpt-image-textures で生成し、blockbench-albedo-to-pbr でノーマル／MER を作成できます。このスキルは、ユーザーが Substance を求めている場合、または .sbsar／.sbs／Painter のアセットをすでに持っている場合にのみ使用してください。ライセンス済みの Adobe Substance 3D のインストールが必要です。最初に blockbench-use を読み込み、結果を割り当てるには blockbench-pbr-materials も読み込んでください。

Substance が生成するのは画像ファイルです。ジオメトリと UV のソースは引き続き Blockbench です。どの経路でも、最後に create_texture（data、pbr_channel）または import_texture_set でファイルをインポートします。

0. ツールを探す

python scripts/sat_locate.py

Designer には sbsrender、sbscooker、sbsupdater、substance3d_baker が同梱されており、PATH 外の C:\Program Files\Adobe\Adobe Substance 3D Designer\ にあります。sbsmutator と pysbs Python API は、単体の Substance Automation Toolkit にのみ含まれています。Painter は HTTP 経由で操作する GUI アプリです。何も見つからない場合は停止してユーザーに伝え、Adobe ソフトウェアをインストールしないでください。

経路を選ぶ

目的	ツール	リファレンス
手続き型マテリアル（レンガ、さび、葉）を Blockbench テクスチャとして使用する	sat_render.py → sbsrender	sat-cli.md
.sbs グラフがあり、.sbsar が必要	sbscooker（古い場合は最初に sbsupdater）	sat-cli.md
.sbs をヘッドレスで編集／特化する	sbsmutator（SAT のみ）	sat-cli.md
モデルから AO／曲率／ID／位置マスクを作成する	substance3d_baker	baker.md
スマートマテリアルを使ってモデルに手作業でペイントする	Painter + painter_remote.py	painter.md
Bedrock MER のパック、ビット深度の変換、ノーマルの緑チャンネルの反転、縮小	prep_maps.py	以下

ワークフロー A：手続き型マテリアル → Blockbench

python scripts/sat_render.py material.sbsar --out out --size 16 --seed 7 \
  --set Season=0.8 --normal-format directx

• --size はピクセル単位です。スクリプトが log2 の $outputsize に変換します（生の sbsrender では 16 px に '$outputsize@4,4' が必要です）。スクリプトは --out を作成します。フォルダーが存在しない場合、生の sbsrender は終了コード 47 で終了します。
• JSON レポートから inputs を読み取り、識別子でパラメーターを設定します。不明な識別子は warnings として返されます。sbsrender はそれらを黙って無視するためです。
• usages に基づいて出力をチャンネルに対応付けます。baseColor／diffuse → カラー、normal、height、metallic + roughness（または反転した glossiness）+ emissive → MER。
• デフォルトでは出力は 8-bit です。タイリングするブロックテクスチャは 16／32 px でそのままレンダリングします。アトラスの場合は、アトラスのサイズ以上でレンダリングしてから縮小します。

ワークフロー B：Blockbench モデルからマスクをベイクする

1. UV を修正します：すべての面に独自の UV 長方形が必要です。ブロック形式のデフォルトの面ごとの Auto UV では、面が重なり、ベイクが台無しになります。baker.md § Prepare を参照してください。
2. export_model → codec_id: "gltf"、options: {"encoding": "binary"}、path: <abs>.glb（または obj）。
3. アンダースコア形式のフラグを使って、密度を 8～16 倍にしてベイクします（オンラインドキュメントにあるハイフン形式は失敗します）：

   substance3d_baker AmbientOcclusion.Raytraced model.glb --use_lowdef_as_highdef true --output_size 512,512 --output_path bake
   

4. python scripts/prep_maps.py convert bake/*.png --out bake/64 --size 64（16-bit → 8-bit、ボックスフィルターで縮小）。
5. マップをマスクとして使用します。AO をカラー テクスチャに乗算するか、sbsrender --set-entry／Painter に渡します。

ワークフロー C：Painter でペイントし、マップを戻す

1. UV を修正してから、codec_id: "obj" を指定して export_model を実行します。Painter は glTF をインポートできません。
2. --enable-remote-scripting を指定して Painter を起動します（アプリが開いてしまうため、--help は使わないでください）。次に：

   python scripts/painter_remote.py --ping --wait 240
   python scripts/painter_remote.py --python-file scripts/painter_new_project.py --result \
     --set MESH=C:/work/model.obj --set NORMAL=DirectX --set RESOLUTION=1024 --set BAKE=1
   

3. ユーザーが Painter でペイントします（または、ローカルの API ドキュメントを読んだ後にレイヤーをスクリプトで作成します）。
4. エクスポートしてサイズを縮小します：

   python scripts/painter_remote.py --python-file scripts/painter_bedrock_export.py --result \
     --set OUT=C:/work/painter_out --set NAME=model --set PRESET=bedrock --set SIZE_LOG2=9
   python scripts/prep_maps.py convert C:/work/painter_out/model*.png --out final --size 64
   

   bedrock では NAME.png、NAME_mer.png、NAME_normal.png（DirectX）が生成されます。gltf では ORM と OpenGL 法線マップが生成されます。Painter は 128 px 未満ではエクスポートせず、チャンネルがないマップは出力しません。結果の files リストを信頼してください。

パックとインポート

python scripts/prep_maps.py pack-mer --metallic out/m_metallic.png --emissive 0 --roughness out/m_roughness.png --out final/model_mer.png
python scripts/prep_maps.py texture-set --color model --mer model_mer --normal model_normal --out final/model.texture_set.json

定数は 0～255 です。--glossiness を指定すると --roughness が置き換えられ、値が反転されます。次に、JSON パスを指定して import_texture_set を実行するか、ファイルごとに create_texture（pbr_channel: color／normal／height／mer）と create_pbr_material を実行します。法線マップと高さマップは、どちらか一方のみを使い、両方は使わないでください。

規約と検証

• 法線マップ：Bedrock は DirectX（緑チャンネルが下向き）、glTF／Java labPBR は OpenGL です。ベイカーのデフォルトは directx です。グラフの $normalformat はグラフごとに定義されています（テストしたグラフの 1 つでは、緑ではなく赤が反転していました）。そのため、レンダリングを比較するか、prep_maps.py convert --flip-green を使ってください。インポート後、Blockbench のプレビューで盛り上がった部分が盛り上がって見えることを確認してください。
• 16 ビットの落とし穴：AO／曲率／高さの PNG は 16 ビットの場合がよくあります。PIL.Image.convert("L") を使うと白にクリップされます。prep_maps.py convert または --output-bit-depth 8 を使ってください。
• パス：実行ファイルには C:/... パスを渡してください。Git Bash の /c/... は --alias を壊します。'$outputsize@...' は引用符で囲んでください。
• Blockbench プロジェクトの安全性：エクスポートとインポートの前にプロジェクト UUID を記録し、テクスチャを書き戻す前に UUID を確認してください。
• インポートした各マップを list_textures／get_texture と capture_screenshot で確認してください。真っ白、または均一なグレーのマップは、ビット深度、UV の重なり、またはパラメーターに誤りがあることを意味します。これはスタイル上の結果ではありません。