blockbench-mcp-overview

Blockbench MCP 概览

修改内容前，先加载 blockbench-use。运行中服务器的工具列表和架构决定可用操作；此源技能可能介绍比已安装程序包更新的工具。工具状态和成功提示不能代替对结果的检查。

探索宿主和工作流

get_capabilities: include_tools=true
# → blockbench, plugin, project, format, formats, tools, notes
list_modes
# → current_mode, modes[{id, available, selected, ...}]

project 可能为 null。使用准确的已注册格式 ID：Generic Model 通常为 free。无需切换项目即可通过 get_capabilities: format_id="free" 检查候选格式。详细功能标志可能为 null（未知）；精简列表会区分 true 标志和未知标志。已安装的插件格式通过发现机制支持，而不是依赖这些技能中的固定白名单。

当工具依赖编辑器状态时，使用 list_modes 和 set_mode: mode_id="<returned ID>"，然后刷新可用性。Animate 使用 animate，而不是 animation。更改模式不会改变项目格式。

工作流	工具或指南
立方体、网格和组	建模
立方体/网格 UV、纹理图像、绘制和图层	纹理
组骨架、关键帧、曲线和时间轴	动画
粒子效果、定位器和粒子关键帧（create_particle_effect、add_locator、manage_particle_keyframes、export_particle_pack）	粒子
法线/高度/MER 通道材质	PBR 材质
从颜色纹理生成法线/高度/MER 贴图（PyPBR 或 vgpu、Depth Anything）	从反照率生成法线
Hytale 专用格式、附件和可见性	Hytale
原生骨架和顶点权重	见下方骨架部分
Java 物品/方块显示变换	见下方显示部分
Bedrock 方块面材质名称	见下方材质实例部分
撤销历史和文件交付	见下方恢复/导出部分

检查和 ID

针对具体问题，优先使用 find_elements_by_criteria 和 filter_by_material；使用 list_outline 了解层级结构。引用现有资源前，先读取 list_textures 和 list_materials。名称可能冲突，尤其是组和它的立方体，因此应保留 UUID。

place_mesh 返回 {meshes: [{name, uuid, vertex_keys, face_keys}]}。组件数组遵循输入顺序。其他网格创建工具和现有网格可通过 get_mesh_info 检查；其顶点和面有各自独立的 next_offset。修改前读取到 null。位置和法线均为网格局部坐标。拓扑更改或撤销/重做后，重新检查。有关可执行的客户端编排示例，请参阅建模技能。

get_cube_uv: id="<cube UUID>" 会读取盒状/逐面模式、面 UV 和有效纹理尺寸。set_cube_uv 会在格式检查后编辑这些值。list_textures 会报告 uv_size、bitmap_size 和 frame_size；在支持逐纹理 UV 尺寸的格式中，create_texture 可设置明确的 uv_width/uv_height。架构和示例见纹理技能。

资源包括 projects://{id}、nodes://{id}、textures://{id} 以及 Hytale 专用资源。请从运行中的服务器发现资源模板和具体 URI，而不是自行编造 ID。项目导出也可能返回实时的 .bbmodel 资源链接。

一个简单的模型和动画

以下是为新建的 Bedrock 实体编写的工具调用伪代码。请先确认该格式已注册，且项目支持动画。

create_project: name="robot", format="bedrock"
add_group: name="body", origin=[0, 12, 0]
place_cube: elements=[{name: "torso_geo", from: [-4, 12, -2], to: [4, 24, 2]}], group="body"

create_texture: name="skin", width=64, height=64, fill_color="#808080", layer_name="base"
apply_texture: id="torso_geo", texture="skin", applyTo="all"

idle = create_animation: name="idle", animation_length=2, loop=true, bones={}
manage_keyframes: animation_id=idle.uuid, action="create", bone_name="body",
  channel="rotation", keyframes=[
    {time: 0, values: [0, 0, 0]},
    {time: 1, values: [0, 5, 0]},
    {time: 2, values: [0, 0, 0]}
  ]
animation_timeline: animation_id=idle.uuid, action="set_time", time=1
capture_screenshot

将 idle.uuid 绑定到返回值；它不是字面量工具参数。添加精细纹理图案前，先检查 UV。仅凭静止姿势的截图无法验证动作。

原生骨架

当运行格式支持 armature_rig 时，查找原生骨架工具：list_armatures、get_armature、add_armature、list_armature_bones、get_armature_bone、add_armature_bone，以及更新和移除操作。ArmatureBones 与基于组的 BoneAnimators 是不同的 API；通用动画工具会解析组。

对于现有网格和骨架，使用 get_mesh_info 检查运行时顶点键，并使用 get_vertex_weights: mesh_id="<UUID>" 查看当前权重。set_vertex_weights_batch 接受 bone_id、mesh_id 和 weights: { "<vertex key>": 0.5 }；权重范围为 0–1。更改后检查所有影响权重及关节处的变形；设置一个骨骼的数值并不能建立绑定正确或已归一化的完整骨架。在承诺提供蒙皮运行时资产之前，请检查导出器是否支持原生骨架。

Java 显示变换

对于支持 display_mode 的格式：

get_display_transform: slot="gui"
set_display_transform: slot="gui", rotation=[30, 225, 0], scale=[0.75, 0.75, 0.75]
enter_display_mode: slot="gui"
capture_screenshot

显示变换会更改导出的数据。请确认所请求的手持、背包、地面或框架视图是否使用了对应槽位；不要通过调整摄像机来暗示这些变换已被编写。

Bedrock 方块材质实例

在 bedrock_block 中，get_face_material_instances 用于读取，set_face_material_instance 用于写入目标的 minecraft:material_instances 组件中映射的名称。

get_face_material_instances: cube_id="block_geo"
set_face_material_instance: cube_id="block_geo", faces=["up"], material_name="top"

这些工具用于指定面名称；它们不会创建行为包方块组件或资源包纹理定义。这些材质实例与 PBR 纹理组和 GPU 实例化相互独立。对于多种材质或镂空面板，请参阅材质实例与纹理交付；使用纹理替代重复几何体之前，请参阅外观与性能方案。实体使用客户端实体／渲染控制器绑定，而不是此方块组件。请检查几何体导出内容和随附的目标配置。

恢复

save_checkpoint 会插入一个历史标记。它不会保存文件、保留现有的重做分支，也不会让未记录的脚本修改变得可撤销。使用 get_undo_stack 找到标记，并在执行 undo: steps=N 之前统计实际条目数；绘制工具可能会创建多个原生笔画。请保留其间用户所做的编辑。

对于这些操作，请使用专用的 undo／redo，而不是 trigger_action。直接使用 risky_eval 编写的脚本必须处理原生撤销机制，并在发生变更时清理失败状态。优先使用可用的专用工具，并遵循会话现有的授权。

导出

list_export_formats
# Inspect available, has_compile, extension and belongs_to_current_format
export_model: codec_id="project", result_format="embedded"
export_model: codec_id="project", path="C:/models/robot.bbmodel", max_content_length=0

请使用 Blockbench 主机上的授权目标路径。文件系统权限可能由主机处理。only_current_format=true 会筛选编解码器列表；如需查找其他可用的兼容导出格式，请使用完整列表。

export_model 会调用编解码器的编译操作。它不会自动运行编解码器的交互式导出流程、写入所有外部图像，也不会导出单独的动画文件。请检查 byte_length、输出路径、截断情况以及返回的内容／资源元数据。被截断的文本／base64 预览并不是完整的可下载资产。只有在嵌入的结果未超出响应限制时，才会包含完整文件。

请根据格式与交付指南选择格式、依赖项和目标路径检查方式。条件允许时，请重新打开副本或检查目标应用；准确说明验证的局限性。