blockbench-texturing

Blockbench 纹理绘制

使用 Blockbench MCP 工具为 3D 模型创建和绘制纹理。

如果模型应使用 Minecraft 自带的纹理（“原版”或“默认”纹理，或砖块、橡木木板等指定方块的纹理），请使用原版纹理。它会在任何绘制或生成操作之前，从 CDN 下载 Mojang 的原始纹理。

对于动画纹理图集，请使用翻页动画纹理：通过 GPT Image 2.5 纹理技能生成图案，将测量后的精灵单元格转换为垂直条带，并配置单帧 UV 尺寸和播放元数据。

先规划 UV，再添加纹理细节

沿用用户的外观/性能偏好。对于注重性能或平衡的设计，应在添加几何体之前，为重复的支撑杆/填充件、座椅肋条、接缝和安装细节分配共享 UV 图块。将小型紧固件绘制到现有的支撑面上；如果目标支持，则添加对齐的 PBR 贴图。仅复用 UV 并不能减少现有几何体。

调整纹理尺寸前，先修正纹素密度。选择使用平铺面还是唯一图集；对于低多边形 glTF，将各面的 UV 折叠到调色板图集上。确认目标是否接受非正方形或非 2 的幂次图像：Minecraft 不支持，而 Hytale 和 Babylon.js 支持。Minecraft 的面 UV 不会平铺，因此要通过拆分面来重复平铺。请参阅实时资源规划的第 7–9 节。

绘制前，检查目标的方盒/逐面 UV 模式和有效 UV 尺寸。UV 单位可能与图像像素不同；使用 per_texture_uv_size 的格式会采用每个面的纹理尺寸。保留有意设置的镜像/重复 UV 重叠，并为不对称细节分配独立空间。使用棋盘格或方向标记预览拉伸、方向和接缝。根据用户的风格和观看距离匹配像素密度；Minecraft 像素画规则并不适用于所有格式。请参阅格式和交付指南。

Blockbench 原生的纹理模板工作流可以排布 UV，但 create_texture 只会创建/导入图像，不会生成该布局。auto_uv_mesh 会映射面，但不会打包 UV 岛。若要使用打包布局，请使用运行中的工具包明确提供的工具，或使用原生模板/UV 工作流；重新排布前，保留已有的绘制图集。

保留 UV 比例和材质尺度

在应用详细材质、跨不同面尺寸共享色块或修正纹理拉伸之前，请阅读 UV 尺度和失真指南。使用有效纹理的帧尺寸和逻辑 UV 尺寸，分别计算两个面方向上每模型单位对应的图像采样像素数。共享材质通常需要比例合适的 UV 占用区域，而不是在每个面上使用相同的完整矩形。

使用可还原的棋盘格检查局部拉伸和部件之间的尺度差异，然后检查实际的纹理颗粒/图案。优先使用比例合适的子区域、合适的饰条，或经过验证且受目标支持的平铺方式。有限的 UV 矩形或更大的图像并不能证明尺度正确。均匀材质或设计效果可保留有意的拉伸；即使纯 albedo 搭配细节丰富的 PBR 通道，也仍需检查尺度。

用 UV 瓦片替换重复几何体

当选定的观看距离能够容纳平面细节时，可用少量格式支持的面板来表现重复的栏杆填充或 X 形支撑。将图案映射到这些面板上，并保持孔洞透明。实心表面使用不透明区域；图集岛之间留出边距，但不要填充有意保留的孔洞。在移除替换掉的几何体之前，检查侧视图、两侧、过滤／mipmap 效果以及远景视图，确认横杆不会消失，也不会出现光晕或纹理渗色。测试透明层是否会产生过度绘制；每根横杆都用一个镂空面板会抵消几何体减少带来的收益。

明确选择目标的 alpha-test／剔除行为；双面渲染和半透明混合都有开销。格式支持时可以使用多张纹理，但导入图像并不意味着运行时材质绑定也已完成。对于 Bedrock 自定义方块，请遵循材质实例和纹理交付；实体绑定使用不同的工作流。

生成原生纹理模板

对于新的图集，请进入受支持的编辑模式并设置所需的大纲选择，然后打开原生操作，但不要直接接受默认值：

trigger_action: action="create_texture", confirmDialog=false

使用 fill_dialog 前，请检查返回的应用截图／对话框。当前的原生对话框通常包含 name、type="template"、resolution（像素密度）、rearrange_uv、double_use（复用匹配的面）、power 和 padding。仅发送该宿主对话框中存在的字段。检查默认值后，示例如下：

fill_dialog: values="{\"name\":\"atlas\",\"type\":\"template\",\"rearrange_uv\":true}", confirm=true

根据目标选择密度、重叠复用方式和边距；模板的 resolution 并非要求的最终图集宽度。大纲中没有选择时，可能会选中整个模型；对于单纹理格式，即使只选择了部分元素，也可能处理所有符合条件的可见元素。确认前请检查操作范围，尤其是在已有绘制内容时。生成操作可能异步继续：完成后，请先检查 list_textures、实际 UV 和 get_texture，再进行绘制。fill_dialog: confirm=false 会取消对话框；它不能用于填入字段后让对话框保持打开。请参阅原生纹理生成器和官方模板工作流。

绘制坐标以图像像素为单位。存在多张纹理时，请为每个绘制工具明确传入 texture_id。图层和选区会影响原生绘制；绘制前请检查当前选中的图层和已有选区。layer_name 用于命名新图层或重命名图层；大多数图层操作会针对当前选中的图层，而不是按名称查找任意图层。

可用工具

纹理管理

工具	用途
create_texture	使用指定尺寸和填充颜色创建新纹理
list_textures	列出项目中的所有纹理
get_texture	获取纹理图像数据
activate_texture	选择现有纹理
apply_texture	将纹理应用到元素

绘制工具

工具	用途
paint_with_brush	使用可自定义的画笔进行绘制
paint_fill_tool	填充区域
draw_shape_tool	绘制矩形／椭圆
gradient_tool	应用渐变
eraser_tool	使用画笔设置擦除
color_picker_tool	从纹理中拾取颜色
copy_brush_tool	克隆／复制纹理区域

画笔管理

工具	用途
create_brush_preset	保存画笔设置
load_brush_preset	加载已保存的画笔
paint_settings	配置绘制模式

图层与选区

工具	用途
texture_layer_management	管理纹理图层
texture_selection	创建／修改选区

UV 工具

工具	用途
set_mesh_uv	设置 UV 坐标
auto_uv_mesh	自动生成 UV
rotate_mesh_uv	旋转 UV 映射
get_mesh_info	使用 include_uv=true 读取网格面/顶点键和现有 UV
get_cube_uv	检查盒体/各面的 UV、实际生效的面贴图、UV 尺寸和位图尺寸
set_cube_uv	编辑盒体偏移/镜像或各面的矩形、旋转和贴图引用

资源

资源	URI	用途
纹理	textures://{id}	列出/读取纹理信息

创建纹理

新建空白纹理

create_texture: name="skin", width=64, height=64, fill_color="#808080", layer_name="base"

带透明度的纹理

create_texture: name="overlay", width=32, height=32, fill_color=[0, 0, 0, 0], layer_name="base"

将 UV 尺寸与位图分辨率分开设置

在 per_texture_uv_size=true 的格式中，create_texture 接受作为正数的 uv_width 和 uv_height，两者需同时提供。省略两者则保留原生默认值。导入图像 data 时也可使用这对参数；它会在图像解码后设置逻辑 UV 尺寸，而不调整位图大小。

# For an intended Generic Model with per_texture_uv_size=true
create_texture: name="paint_detail", width=128, height=64,
  uv_width=32, uv_height=16, fill_color="#808080", layer_name="base"
list_textures
# Inspect uv_size=[32,16], bitmap_size=[128,64], frame_size=[128,64]

此静态图像的每个 UV 单位在两个轴上都对应 4 个像素。同一项目中的多个纹理可以有不同的 UV 尺寸，因此映射时应使用面实际生效的纹理尺寸。list_textures 会在当前资源包中显示 uv_size、bitmap_size 和 frame_size。采用项目级 UV 尺寸的格式不接受逐纹理覆盖；请改为检查和编辑原生项目的 UV 尺寸设置。更改逻辑尺寸可能会改变现有映射，因此请保留预期的像素密度并验证结果。

应用到元素

提供 fill_color 时，create_texture 要求指定 layer_name。纹理查找支持名称或 UUID；名称有歧义时，请使用 list_textures 中的 UUID。

apply_texture: id="body", texture="skin", applyTo="all"

绘制

基本笔刷笔画

paint_with_brush: texture_id="skin", coordinates=[
  {x: 10, y: 10},
  {x: 15, y: 12},
  {x: 20, y: 10}
], brush_settings={color: "#FF0000", size: 3, shape: "circle"}

柔边笔刷

paint_with_brush: texture_id="skin", coordinates=[{x: 32, y: 32}],
  brush_settings={color: "#FFFFFF", size: 10, softness: 50, opacity: 128}

填充区域

paint_fill_tool: texture_id="skin", x=16, y=16, color="#3366FF",
  fill_mode="color_connected", tolerance=0

原生填充 API 仅支持精确颜色匹配；不接受非零的 tolerance。

面/元素填充模式取决于原生几何/UV 上下文。仅凭纹理像素坐标无法确定模型面。对于已知 UV 矩形，请使用显式矩形绘制；对于面填充，请先建立并验证原生目标上下文。请检查结果；仅有成功消息并不能证明只更改了目标面。

形状与渐变

绘制矩形

draw_shape_tool: texture_id="skin", shape="rectangle",
  start={x: 0, y: 0}, end={x: 16, y: 16}, color="#FFCC00"

绘制空心椭圆

draw_shape_tool: texture_id="skin", shape="ellipse_h",
  start={x: 8, y: 8}, end={x: 24, y: 24}, color="#000000", line_width=2

应用渐变

gradient_tool: texture_id="skin",
  start={x: 0, y: 0}, end={x: 0, y: 32},
  start_color="#87CEEB", end_color="#1E90FF"

擦除

eraser_tool: texture_id="skin", coordinates=[{x: 10, y: 10}, {x: 12, y: 12}],
  brush_size=5, shape="circle", opacity=255

取色

color_picker_tool: texture_id="skin", x=16, y=16
# Returns picked color, sets as active

仿制/复制笔刷

copy_brush_tool: texture_id="skin",
  source={x: 0, y: 0}, target={x: 32, y: 0},
  brush_size=8, mode="copy"

笔刷预设

创建预设

create_brush_preset: name="soft_round", size=8, shape="circle",
  softness=30, opacity=200, color="#FFFFFF"

加载预设

load_brush_preset: preset_name="soft_round"

纹理图层

创建图层

texture_layer_management: texture_id="skin", action="create_layer",
  layer_name="details"

设置图层不透明度

texture_layer_management: texture_id="skin", action="set_opacity",
  opacity=75  # Operates on the selected layer; layer opacity is 0–100 percent

向下合并

texture_layer_management: texture_id="skin", action="merge_down"  # Selected layer

选区

矩形选区

texture_selection: texture_id="skin", action="select_rectangle",
  coordinates={x1: 0, y1: 0, x2: 16, y2: 16}

添加到选区

texture_selection: texture_id="skin", action="select_ellipse",
  coordinates={x1: 8, y1: 8, x2: 24, y2: 24}, mode="add"

反转选区

texture_selection: texture_id="skin", action="invert_selection"

羽化边缘

texture_selection: texture_id="skin", action="feather_selection", radius=2

UV 映射

立方体 UV

确认 get_cube_uv 和 set_cube_uv 已通过 get_capabilities: include_tools=true 公告；较早加载的捆绑包需要重新加载，才能使用这些工具。如果某个组与立方体同名，请将立方体的实际 UUID 用作 id。

get_cube_uv: id="body_geo"
# → {uuid, name, box_uv, autouv, uv_offset, mirror_uv, faces}
# Each face: uv, rotation, texture, texture_status, effective_texture, uv_size, bitmap_size, frame_size

# Move the atlas origin of an existing box-UV cube
set_cube_uv: id="body_geo", uv_offset=[16, 8], mirror_uv=false

# In an existing per-face-UV cube, edit one rectangle (UV units)
set_cube_uv: id="panel_geo", faces={north: {uv: [0, 0, 8, 4]}}

选择与立方体检查所得模式相匹配的示例；方框偏移和面的矩形属于不同的工作流。更改模式需要显式传入 box_uv 参数，并使用允许此参数的格式；原生转换可能会重置旋转并启用已禁用的面。工具会验证转换是否成功，并在转换被拒绝时回滚。非零面的旋转需要格式支持 uv_rotation。显式矩形通常会禁用自动重新映射；Hytale 会保留 autouv=1，并要求矩形的范围与面基础尺寸的绝对值相匹配；UV 旋转为 90/270 度时，宽度和高度互换。偏移和镜像只要匹配就允许，范围发生变化则会在执行撤销前被拒绝。Hytale 四边形不能使用方框 UV。请参阅 Hytale 原生 UV 行为。

每个面的 texture 可接受现有纹理名称/UUID、表示未分配的 false，或表示禁用该面的 null。单纹理和每组纹理格式会限制每个面的纹理分配；请使用它们现有的全局/分组工作流。即使 single_texture=false，Hytale 也会通过附加集合或项目默认纹理解析纹理；此时工具会拒绝非 null 的每面分配。编辑后请重新检查，包括 effective_texture、uv_size、bitmap_size 和 frame_size。要将 UV 转换为帧内的像素，请在每个轴上使用 frame_size / uv_size；bitmap_size 包含整个动画图集。对于宽 64 像素、含 16 个 UV 单位的帧，UV 坐标 4 对应帧内 X=16。

网格自动 UV

select_mesh_elements: mesh_id="ball", mode="face"  # Select the intended faces
auto_uv_mesh: mesh_id="ball", mode="project"  # project, unwrap, cylinder, sphere

project 使用当前预览摄像机；unwrap 会为每个面创建独立的平面映射，不会打包 UV 岛。cylinder 和 sphere 使用网格局部原点以及每个映射面的有效 UV 尺寸，因此请先检查纹理分配。将明确的返回面键传入 faces，即可只处理网格的一部分。

设置自定义 UV

网格面和顶点键会在运行时生成；立方体方向名称不是网格面 ID。请像建模技能所示，保留 place_mesh 返回的 meshes[] 条目；或者使用 get_mesh_info 并设置 include_uv=true 来检查现有网格。

此客户端编排示例接续建模技能中创建的四边形 panel。call 会调用指定的 MCP 工具、检查 isError 并解码 JSON 结果；发送工具参数前，必须先将变量表达式绑定到实际返回值。

const uvCorners = [[0, 0], [16, 0], [16, 16], [0, 16]];
await call("set_mesh_uv", {
  mesh_id: panel.uuid,
  face_key: panel.face_keys[0],
  uv_mapping: Object.fromEntries(panel.vertex_keys.map((key, index) => [key, uvCorners[index]])),
});

UV 值使用 Blockbench 纹理单位，而非归一化的 0–1 坐标。对于现有面，请使用检查结果中的 faces.items[].key，并按该面的 vertices 周边顺序排列；使用这些确切的顶点 ID 作为 UV 映射的键。逐页读取，并使用各页独立的 next_offset，直到其为 null；读取期间不要编辑几何体。请参阅建模技能中的 readMeshPages 辅助函数；读取现有 UV 时，请添加 include_uv: true。拓扑更改后请重新检查。

旋转 UV

await call("rotate_mesh_uv", {mesh_id: panel.uuid, angle: "90", faces: [panel.face_keys[0]]});

绘制设置

paint_settings: pixel_perfect=true, mirror_painting={enabled: true, axis: ["x"]},
  lock_alpha=true

常见工作流

绘制现有皮肤布局

请使用目标皮肤的实际 UV 模板。以下坐标只是已在该模板中确认过的区域示例；空白图像和这些笔触本身不会自动构成有效的玩家皮肤。

# Create texture
create_texture: name="player_skin", width=64, height=64, fill_color="#C4A484", layer_name="base"

# Base colors
draw_shape_tool: texture_id="player_skin", shape="rectangle",
  start={x: 20, y: 20}, end={x: 27, y: 31}, color="#3366CC"

# Details with brush
paint_with_brush: texture_id="player_skin", coordinates=[{x: 10, y: 10}, {x: 12, y: 10}],
  brush_settings={color: "#000000", size: 1}, connect_strokes=false  # Separate eye pixels

# Apply
apply_texture: id="head", texture="player_skin"

程序化图案

# Create base
create_texture: name="pattern", width=32, height=32, fill_color="#FFFFFF", layer_name="base"

# Draw grid
draw_shape_tool: texture_id="pattern", shape="rectangle_h", start={x: 0, y: 0}, end={x: 31, y: 31},
  color="#CCCCCC", line_width=1
draw_shape_tool: texture_id="pattern", shape="rectangle_h", start={x: 8, y: 8}, end={x: 24, y: 24},
  color="#999999", line_width=1

提示

• 在 paint_settings 中使用 pixel_perfect=true，绘制整洁的像素艺术
• 确认预期的对称效果和原生目标上下文后，再启用 mirror_painting；对于非对称细节，请将其关闭
• 使用图层进行非破坏性编辑
• lock_alpha 可防止在现有像素之外绘制
• 使用 fill_mode="color_connected"，仅填充相连的同色像素
• 为常用设置创建笔刷预设
• paint_with_brush 默认会连接各个点；对于眼睛或斑点等独立印章，请设置 connect_strokes=false
• 完成重要的绘制更改后，检查 get_texture 和渲染后的模型。对于平铺方块，请尽早检查重复排列；对于动画资源，请检查不同姿势下显露的表面。这些做法遵循 Minecraft 风格指南 和 Bedrock 贴图指南。