blockbench-substance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blockbench + Adobe Substance 3D

Optional and advanced. Most Blockbench work never needs this: paint with blockbench-texturing, generate with blockbench-gpt-image-textures, derive normal/MER with blockbench-albedo-to-pbr. Use this skill only when the user asks for Substance or already has

.sbsar

.sbs

/Painter assets. It needs a licensed Adobe Substance 3D install. Load blockbench-use first and blockbench-pbr-materials to assign results.

Substance produces image files. Blockbench stays the source of geometry and UVs. Every path ends with files imported through

create_texture

(

data

pbr_channel

) or

import_texture_set

可选且高级。 大多数 Blockbench 工作都不需要此 skill：使用 blockbench-texturing 绘制，使用 blockbench-gpt-image-textures 生成纹理，使用 blockbench-albedo-to-pbr 派生 normal/MER。仅当用户要求使用 Substance，或已经拥有

.sbsar

.sbs

/Painter 资源时，才使用此 skill。它需要已授权的 Adobe Substance 3D 安装环境。先加载 blockbench-use，再加载 blockbench-pbr-materials，以将结果指派给相应资源。

Substance 生成的是 图像文件。Blockbench 始终是几何体和 UV 的来源。无论采用哪条路径，最终都要通过

create_texture

（

data

、

pbr_channel

）或

import_texture_set

导入文件。

0. Locate the tools

0. 定位工具

bash

python scripts/sat_locate.py

Designer bundles

sbsrender

sbscooker

sbsupdater

and

substance3d_baker

, off PATH, in

C:\Program Files\Adobe\Adobe Substance 3D Designer\

sbsmutator

and the

pysbs

Python API come only with the standalone Substance Automation Toolkit. Painter is a GUI app driven over HTTP. If nothing is found, stop and tell the user; do not install Adobe software.

bash

python scripts/sat_locate.py

Designer 在

C:\Program Files\Adobe\Adobe Substance 3D Designer\

中自带

sbsrender

、

sbscooker

、

sbsupdater

和

substance3d_baker

，但它们未加入 PATH。

sbsmutator

和

pysbs

Python API 仅随独立版 Substance Automation Toolkit 提供。Painter 是通过 HTTP 驱动的 GUI 应用。如果未找到任何工具，请停止操作并告知用户；不要安装 Adobe 软件。

Pick the path

选择工作流

Goal	Tool	Reference
Procedural material (bricks, rust, leaves) as Blockbench textures	`sat_render.py` → `sbsrender`	sat-cli.md
Have a `.sbs` graph, need an `.sbsar`	`sbscooker` ( `sbsupdater` first if old)	sat-cli.md
Edit/specialise a `.sbs` headlessly	`sbsmutator` (SAT only)	sat-cli.md
AO / curvature / ID / position masks from the model	`substance3d_baker`	baker.md
Hand-paint the model with smart materials	Painter + `painter_remote.py`	painter.md
Pack Bedrock MER, convert bit depth, flip normal green, shrink	`prep_maps.py`	below

目标	工具	参考
将程序化材质（砖块、锈迹、树叶）用作 Blockbench 纹理	`sat_render.py` → `sbsrender`	sat-cli.md
已有 `.sbs` graph，需要生成 `.sbsar`	`sbscooker` （如果版本较旧，先运行 `sbsupdater` ）	sat-cli.md
以无头方式编辑或定制 `.sbs`	`sbsmutator` （仅 SAT）	sat-cli.md
从模型获取 AO/曲率/ID/position mask	`substance3d_baker`	baker.md
使用 smart material 手动绘制模型	Painter + `painter_remote.py`	painter.md
打包 Bedrock MER、转换位深、翻转法线绿通道、缩小尺寸	`prep_maps.py`	见下文

Workflow A: procedural material → Blockbench

工作流 A：程序化材质 → Blockbench

bash

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

```
--size
```
is pixels; the script converts to log2
```
$outputsize
```
(raw
```
sbsrender
```
needs
```
'$outputsize@4,4'
```
for 16 px). It creates
```
--out
```
; raw
```
sbsrender
```
exits 47 if the folder is missing.
Read
```
inputs
```
from the JSON report, then set parameters by identifier. Unknown identifiers come back as
```
warnings
```
, because
```
sbsrender
```
ignores them silently.

Match outputs to channels by

usages

baseColor

diffuse

→ color;

normal

;

height

;

metallic

roughness

(or

glossiness

, inverted) +

emissive

→ MER.

Output is 8-bit by default. Tiling block textures render straight at 16/32 px. For atlases, render at the atlas size or larger and shrink.

bash

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
```
中读取内容，再按 identifier 设置参数。未知 identifier 会出现在
```
warnings
```
中，因为
```
sbsrender
```
会静默忽略它们。
根据
```
usages
```
将输出与 channel 对应：
```
baseColor
```
/
```
diffuse
```
→ color；
```
normal
```
；
```
height
```
；
```
metallic
```
+
```
roughness
```
（或取反后的
```
glossiness
```
）+
```
emissive
```
→ MER。
输出默认为 8-bit。可平铺的方块纹理可直接按 16/32 px 渲染。对于 atlas，应按 atlas 尺寸或更大尺寸渲染，然后缩小。

Workflow B: bake masks from the Blockbench model

工作流 B：从 Blockbench 模型烘焙 mask

Fix UVs: every face needs its own UV rectangle. Default per-face Auto UV on block formats stacks faces on top of each other and ruins the bake. See baker.md § Prepare.

export_model

→

codec_id: "gltf"

options: {"encoding": "binary"}

path: <abs>.glb

(or

obj

Bake at 8–16× density with underscore flags (the online docs show hyphens, which fail):

bash

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

python scripts/prep_maps.py convert bake/*.png --out bake/64 --size 64

(16-bit → 8-bit, box downsample).

Use the maps as masks: multiply AO into the colour texture, or feed them to
```
sbsrender --set-entry
```
/ Painter.

修复 UV：每个面都需要独立的 UV 矩形。block 格式默认启用逐面 Auto UV，会将各个面堆叠在一起并破坏烘焙。请参阅 baker.md § Prepare。

export_model

→

codec_id: "gltf"

、

options: {"encoding": "binary"}

、

path: <abs>.glb

（或

obj

）。

以 8–16× 密度烘焙，并使用下划线形式的参数（在线文档展示的是连字符形式，但无法运行）：
bash
```
substance3d_baker AmbientOcclusion.Raytraced model.glb --use_lowdef_as_highdef true --output_size 512,512 --output_path bake
```

python scripts/prep_maps.py convert bake/*.png --out bake/64 --size 64

（16-bit → 8-bit，box downsample）。

将这些贴图用作 mask：将 AO 乘算到颜色纹理中，或将其传给
```
sbsrender --set-entry
```
/ Painter。

Workflow C: paint in Painter, bring maps back

工作流 C：在 Painter 中绘制并取回贴图

Fix UVs, then
```
export_model
```
with
```
codec_id: "obj"
```
. Painter cannot import glTF.

Start Painter with

--enable-remote-scripting

(never

--help

: it opens the app), then:

bash

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

The user paints in Painter (or you script layers after reading the local API docs).

Export and shrink:

bash

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

gives

NAME.png

NAME_mer.png

NAME_normal.png

(DirectX).

gltf

gives ORM + OpenGL normal. Painter never exports below 128 px, and skips maps whose channel is absent. Trust the

files

list in the result.

修复 UV，然后使用
```
codec_id: "obj"
```
调用
```
export_model
```
。Painter 无法导入 glTF。

使用

--enable-remote-scripting

启动 Painter（切勿使用

--help

，因为这会打开应用），然后运行：

bash

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

由用户在 Painter 中绘制，或在阅读本地 API 文档后通过脚本创建图层。

导出并缩小尺寸：

bash

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 normal。Painter 不会导出低于 128 px 的贴图，并且会跳过缺少相应 channel 的贴图。请以结果中的

files

列表为准。

Pack and import

打包与导入

bash

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

Constants are 0–255;

--glossiness

replaces

--roughness

and is inverted. Then

import_texture_set

with the JSON path, or

create_texture

per file (

pbr_channel

color

normal

height

mer

) +

create_pbr_material

. Normal or height, never both.

bash

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

。只能使用

normal

或

height

，二者不可同时使用。

Conventions and verification

约定与验证

Normals: Bedrock → DirectX (green-down), glTF/Java labPBR → OpenGL. Baker default is
```
directx
```
. A graph's
```
$normalformat
```
is graph-defined (one tested graph flipped red, not green), so compare renders or use
```
prep_maps.py convert --flip-green
```
. After import, raised features must read as raised in the Blockbench preview.
16-bit trap: AO/curvature/height PNGs are often 16-bit;
```
PIL.Image.convert("L")
```
clips them to white. Use
```
prep_maps.py convert
```
or
```
--output-bit-depth 8
```
.
Paths: pass
```
C:/...
```
paths to the executables;
```
/c/...
```
from Git Bash breaks
```
--alias
```
. Quote
```
'$outputsize@...'
```
.
Blockbench project safety: note the project UUID before export and import, and confirm it before writing textures back.
Check each imported map with
```
list_textures
```
/
```
get_texture
```
and a
```
capture_screenshot
```
. A blank-white or uniformly gray map means the bit depth, UV overlap or parameter was wrong. It is not a stylistic result.

法线：Bedrock → DirectX（绿色向下），glTF/Java labPBR → OpenGL。Baker 默认使用
```
directx
```
。graph 的
```
$normalformat
```
由 graph 自身定义（一个受测 graph 翻转的是红通道，而非绿通道），因此应比较渲染结果，或使用
```
prep_maps.py convert --flip-green
```
。导入后，凸起特征在 Blockbench 预览中必须呈现为凸起。
16-bit 陷阱：AO/曲率/height PNG 通常是 16-bit；
```
PIL.Image.convert("L")
```
会将其裁剪为纯白。请使用
```
prep_maps.py convert
```
或
```
--output-bit-depth 8
```
。
路径：向 executable 传递
```
C:/...
```
路径；Git Bash 中的
```
/c/...
```
会导致
```
--alias
```
失效。请为
```
'$outputsize@...'
```
加引号。
Blockbench 项目安全：在导出和导入前记录项目 UUID，并在将纹理写回之前确认无误。
使用
```
list_textures
```
/
```
get_texture
```
和
```
capture_screenshot
```
检查每张导入的贴图。纯白或均匀灰色的贴图意味着位深、UV 重叠或参数有误，并不是风格化效果。