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 生成的是图像文件。Blockbench 仍是几何体和 UV 的来源。所有路径最终都会通过 create_texture（data、pbr_channel）或 import_texture_set 导入文件。

0. 定位工具

python scripts/sat_locate.py

Designer 将 sbsrender、sbscooker、sbsupdater 和 substance3d_baker 捆绑在 C:\Program Files\Adobe\Adobe Substance 3D Designer\ 中，但这些工具不在 PATH 上。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 位。平铺方块纹理可直接以 16/32 px 渲染。对于图集，以图集尺寸或更大尺寸渲染，然后缩小。

工作流 B：从 Blockbench 模型烘焙遮罩

1. 修正 UV：每个面都需要自己的 UV 矩形。方块格式默认的逐面 Auto UV 会将各面堆叠在一起，导致烘焙失败。参见 baker.md § 准备。
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 位 → 8 位，盒式降采样）。
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 由图表定义（一个经过测试的图表翻转了红色通道，而非绿色通道），因此请对比渲染结果，或使用 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 重叠或参数有误，而不是一种风格效果。