blockbench-pbr-materials

Blockbench PBR 材质

使用 get_capabilities 检查当前项目和已注册的格式功能，包括 pbr。分配现有资源前，先检查 list_textures 和 list_materials。纹理和材质引用可以使用名称或 UUID；名称有重复时，优先使用返回的 UUID。

保留目标的材质约定。Bedrock MER 既不是 glTF 金属度/粗糙度贴图，也不是任意的 ORM 通道打包方式。Blockbench 预览成功并不意味着所选导出器或游戏支持该材质。通道贴图应与颜色纹理使用相同的 UV 布局，并在绘制前检查其尺寸。共享 UV 和交付检查请参阅格式与交付指南。

原版 Minecraft 方块附带现成的 Bedrock 纹理集：一个 .texture_set.json 文件和一个 _mers.tga 文件，有些还附带 _normal.tga。要从 Mojang 自己的材质开始，请使用带 --pbr 的原版纹理，然后对下载的文件运行 import_texture_set。

使用 PBR 表现表面细节

遵循所选的外观/性能偏好。对于小型紧固件、铆钉、焊缝、凹槽和较浅的座椅肋条，使用对齐的法线或高度细节，而不要堆叠许多微小立方体。在 MER 中添加区域性的金属度和粗糙度变化；共享图集可以表示铝、橡胶和涂装标记，无需为每个可见表面单独创建材质。应制作有效的通道数据，不要把反照率图像当作法线/MER 贴图。要从现有颜色纹理生成法线、高度或 MER 贴图，请使用反照率转法线，并先通过 create_texture 导入生成的贴图，再在此处分配。

法线/高度着色不会生成轮廓厚度、栏杆开口或碰撞体。这些效果很重要时，应保留几何体。确认目标渲染模式确实使用 PBR，保留清晰易读的纯颜色备用方案，并考虑额外贴图带来的内存开销。Bedrock 的 Classic 管线只使用颜色层；法线和高度图是互斥的纹理集图层。请参阅官方纹理集规范。

在开始贴图前先确定着色模型，因为它决定了制作 PBR 贴图是否值得。

• 原版 Java 没有 PBR 插槽；只有当用户的目标是使用 LabPBR 的着色器包时，它们才会读取 LabPBR。
• Bedrock Classic 只读取颜色；Vibrant Visuals 和 RTX 会读取纹理集。
• 风格化低多边形 glTF 通常不使用法线贴图。

需要让细节深度随摄像机角度变化时，应将细节保留为几何体。请参阅实时资源规划的第 2、3 和 6 节。

使用 UV 比例和失真指南，让各部件的表面起伏和材质纹理保持一致的比例。即使图像分辨率不同，各通道中的对应区域也必须对齐。修改 UV 或图集时必须保持这些对应关系；旋转/镜像后应检查切线空间法线的方向。纯色并不意味着可以拉伸细节丰富的法线或粗糙度贴图。

PBR 纹理组和 .texture_set.json 用于描述表面通道，不会为 Bedrock 方块表面指定渲染材质。有关这些绑定和随附的包文件，请参阅 Bedrock 材质实例。

工具和参数名称

工具	此工作流中使用的参数
create_pbr_material	name、color_texture、normal_texture 或 height_texture、mer_texture、color_value、mer_value、subsurface_value
configure_material	material 以及相同的通道／数值字段；将纹理字段设为 "none" 可清除该通道
assign_texture_channel	material、texture、channel
list_materials	无参数
get_material_info	material
import_texture_set	以 .texture_set.json 结尾的 path
save_material_config	material；输出路径根据已保存的颜色纹理生成

这些都是扁平的工具参数。不要将通道包装在 textures 中，也不要将设置包装在 config 中；这些 PBR 工具不使用 material_id、texture_id 或 output_path。

通道和值的规则

通道	纹理数据	均匀值替代项
color	基础颜色／反照率 RGBA	color_value: [R, G, B, A]，每个值为 0–255
normal	切线空间 RGB；中性法线为 #8080FF	无
height	灰度高度，暗色表示低、亮色表示高	无
mer	R=金属度，G=自发光，B=粗糙度	mer_value: [M, E, R]，每个值为 0–255

• 一个材质只能使用法线或高度通道。要在两者之间切换，请在同一次 configure_material 调用中移除旧通道。
• 每个已分配的通道都使用单独的纹理。替换通道会解除旧纹理与材质的关联，但不会删除图像。
• 均匀值要求对应通道未分配纹理；仍有关联贴图时提供均匀值会返回错误。切换到 mer_value 时，请使用 mer_texture="none" 移除 MER 贴图。
• 当前 Blockbench 预览中，MER 纹理需要颜色纹理。若使用均匀颜色，也请使用均匀 MER 值。
• 将纹理移至其他材质会改变其所属组。移走颜色纹理时，请先清除或移走源材质的 MER 纹理，以确保源材质仍然有效。
• subsurface_value 是一个 0–255 的数值，不是 RGB 对象。游戏／导出支持情况取决于目标平台。

创建材质

create_texture: name="stone_color", width=16, height=16,
  fill_color="#808080", layer_name="base"
create_texture: name="stone_normal", width=16, height=16,
  fill_color="#8080FF", layer_name="base"

create_pbr_material: name="stone", color_texture="stone_color",
  normal_texture="stone_normal", mer_value=[0, 0, 230]
# → {success, material: {name, uuid, is_material, channels}}

get_material_info: material="stone"

只要 create_texture 提供了 fill_color，就必须提供 layer_name。保留创建响应中的 material.uuid，并在后续的 material 参数中使用其值。只要名称唯一，上述名称即可使用。此示例使用哑光非金属 MER 值；230/255 的粗糙度约为 90%。

编辑和替换通道

将法线贴图替换为另一个已创建的法线纹理：

assign_texture_channel: material="stone", texture="stone_normal_v2", channel="normal"

一次调用即可将法线通道切换为已创建的高度贴图：

configure_material: material="stone", normal_texture="none", height_texture="stone_height"

引用的替换纹理必须存在；使用 list_textures 查找其 UUID。之后使用 get_material_info 验证新的分配。此类项目编辑会记录在专用的 undo / redo 工具中；撤销通道替换会恢复被替换纹理和传入纹理的分配状态。

均匀属性

对于名为 stone 的现有材质，请先清除所有 MER 贴图，再设置均匀值：

configure_material: material="stone", mer_texture="none", mer_value=[0, 0, 204]

外观	mer_value 示例
哑光石材	[0, 0, 230]
光滑金属	[255, 0, 64]
光滑电介质	[0, 0, 13]
自发光非金属	[0, 255, 204]

要使用均匀颜色，请在同一次调用中清除颜色纹理和 MER 纹理：

configure_material: material="stone", color_texture="none", mer_texture="none",
  color_value=[128, 128, 128, 255], mer_value=[0, 0, 204]

绘制并分配 MER 贴图

创建 MER 纹理，并将其与材质的颜色纹理一起分配：

create_texture: name="stone_mer", width=16, height=16,
  fill_color=[0, 0, 204, 255], layer_name="base"

# Metallic spot, retaining roughness at 204 and emission at zero
paint_with_brush: texture_id="stone_mer", coordinates=[{x: 8, y: 8}],
  brush_settings={color: "#FF00CC", size: 4}

# Emissive spot, retaining roughness at 204 and metalness at zero
paint_with_brush: texture_id="stone_mer", coordinates=[{x: 4, y: 4}],
  brush_settings={color: "#00FFCC", size: 2}

configure_material: material="stone", color_texture="stone_color", mer_texture="stone_mer"
get_material_info: material="stone"

笔刷颜色会写入所有 RGB 通道。请在该颜色中编码你想保留的属性，不要假定红色或绿色笔刷只会影响单个通道。

检查、导入和导出

list_materials
# → [{name, uuid, channels: {color, normal, height, mer}, config}]

get_material_info: material="stone"
# → {name, uuid, is_material, textures, config, texture_set_json}

import_texture_set: path="C:/packs/textures/stone.texture_set.json"

导入需要 Blockbench 桌面主机上有可读取的文件及其引用的图像。编辑前请先检查导入的素材。

导出时，请先通过 Blockbench 保存颜色图像，以便它具有有效的文件路径。get_material_info 会提供 config.file_path 和 texture_set_json 预览。保存工具会根据颜色图像推导 .texture_set.json 的目标路径；它不接受任意输出路径：

save_material_config: material="stone"

仅在内存中创建的新纹理没有保存路径。如果用户只需要 JSON 内容，请使用 get_material_info 预览。保存材质配置会写入磁盘文件，与可撤销的项目编辑是分开的。如果交付内容要求在指定的游戏／渲染环境中呈现，请在那里验证外观。