用途
Blockbench Hytale 用于通过 Blockbench MCP 创建 Hytale 模型和动画。它面向角色/附件（character/attachment）格式与道具（prop）格式的建模需求，并复用共享的建模、贴图和动画工作流。
格式选择
使用前需调用 get_capabilities（include_tools=true）并选择返回的 Hytale 格式 ID。创建 Bedrock 项目不会激活 Hytale。
| 格式 | 每世界方块单位数 | 用途 |
|---|---|---|
| hytale_character | 64 | 角色与附件，包括工具、武器和装饰品 |
| hytale_prop | 32 | 世界道具、家具和方块 |
这些数字描述的是几何/纹素密度，而非最大图集分辨率。贴图宽度和高度可以不同，但必须各自为 32 的倍数。需将有效 UV 尺寸与实际图像匹配，并保留该格式与尺寸关联的面 UV。
可使用 create_project 创建项目（仅在确实需要新项目时使用；替换内容前先检查已有项目），并通过 hytale_get_format_info 获取 formatType、blockSize、animationFPS、nodeCount、maxNodes、nodeCountValid、features 等信息。
对于新的静态 128×96 Hytale 图集，可显式匹配 UV 和位图尺寸（两种 Hytale 格式均支持逐贴图 UV 尺寸），例如通过 create_texture 设置 width、height、uv_width、uv_height、fill_color、layer_name，再用 list_textures 确认 uv_size、bitmap_size 和 frame_size 均为 [128,96]。uv_width/uv_height 参数在当前源码插件中可用，需确认已加载的工具 schema 支持它。创建该图像不会打包模型的 UV；需要新布局时应遵循贴图技能的原始模板工作流。
几何与 UV
该格式支持立方体/四边面、基于关节的分组、拉伸、可选盒式 UV 以及逐贴图 UV 尺寸。沿用插件默认尺寸设置时建议使用整数基础尺寸；拉伸允许在保留 UV 布局的同时获得更精细的可见尺寸。分数基础尺寸并非绝对不可能，但会增加 UV 一致性难度。导出的模型有 255 节点限制，导出器对分组主立方体的折叠会影响实际节点数。
可用的操作包括：add_group（添加分组，可指定 parent 和 origin）、place_cube（放置立方体，指定 from、to 和 group）、hytale_set_cube_stretch 与 hytale_get_cube_stretch（设置/读取拉伸）、hytale_create_quad（创建四边面，可指定 position、normal、size、double_sided）。法线可为 +X、-X、+Y、-Y、+Z 或 -Z。双侧可见时应使用双面渲染。小幅拉伸改动可修正穿插；艺术指南建议其风格每轴约 0.7–1.3，这是视觉建议而非 MCP schema 的有效范围。先铺色块再绘制体积与细节，避免产生杂色颗粒。柔和笔刷适合 Hytale 的绘画风格，并非必须像素级精确绘制。
set_cube_uv 会保留 Hytale 的 autouv=1 和与尺寸关联的矩形大小。可以移动或镜像某面的 UV，同时保留其绝对基础几何宽高（UV 旋转 90/270 度时宽高互换）；在撤销前更改这些范围会被拒绝。拉伸改变可见形状，但不改变该基础 UV 尺寸。Hytale 四边面无法转换为盒式 UV。贴图选择遵循附件集合或项目默认值，即使格式报告 single_texture=false；非空的逐面贴图分配会被拒绝。应检查 effective_texture 并使用原生集合/默认贴图工作流。
着色
hytale_set_cube_properties 可设置 shading_mode 和 double_sided，hytale_get_cube_properties 可读取它们。可接受的着色名称有 standard、flat、fullbright 和 reflective。导出的属性并不能证明视口外观一致，需在 Hytale 中验证材质。
附件
hytale_list_attachments 列出已有的附件集合。hytale_set_attachment_piece 标记已有的分组，hytale_list_attachment_pieces 读取这些标记。片段会附加到匹配的基础模型骨骼名称上，因此需检查两个资源并保留所需名称。
标记分组不会创建集合、配置游戏内物品或导出单独的附件。当前工具族可列出集合，但不创建它们；需要时应使用已安装插件的原生集合/附件工作流。模型编译器需要活动的 Collection 才能进行附件专用导出；通用 export_model.options 中的 JSON 字符串不是该对象。需用基础模型验证附件并检查实际导出的节点。
动画
Hytale 动画文件使用每秒 60 帧单位。MCP 关键帧时间为秒；time=0.5 在导出时表示第 30 帧。可使用 create_animation 返回的动画 UUID 和已有分组名称，通过 hytale_create_visibility_keyframe 设置可见性关键帧，通过 hytale_set_animation_loop 设置循环模式（如 hold）。可见性变化需要初始状态以及过渡关键帧。交换两个表示时应在同一时间点给两者设关键帧。
Hytale 使用四元数插值并会环绕循环片段。完整旋转应使用中间朝向，使关键帧之间小于 180 度，并预览方向和循环接缝。原生 UV 偏移通道存在，但当前 MCP 工具族没有专用的 UV 偏移关键帧工具。
上游的 .blockyanim 导出器会写入 holdLastKeyframe，并将 Catmull-Rom 映射为 smooth、其他插值映射为 linear。编辑器的 once、step 或 Bezier 状态因此不能确立等价的运行时播放效果，需验证实际导出和目标行为。
验证与导出
应先检查相关姿势下的 UV/位图尺寸、贴图分配、拉伸和几何。运行 hytale_validate_model，然后检查其问题与范围。当前实现会统计已安装 blockymodel 编译器主模型输出中的节点数，并检查两个贴图尺寸均为 32 的正倍数，报告 main_model_node_count_and_texture_dimensions；附件和完整引擎兼容性需要单独检查。较旧的包使用启发式节点计数和错误的基于密度的贴图检查，因此依赖此结果前应发现/重新加载当前构建。
通过 list_export_formats 发现可用格式；对预期的模型导出使用已注册的 blockymodel 编解码器。贴图图像是单独的交付物。动画应通过已安装插件的原生动画工作流导出。上游提供 export_blockyanim 操作；当发现结果未返回 blockyanim 模型编解码器时，不要自行发明一个。通过授权的 UI 工作流完成由此产生的原生保存对话框。
可重新打开副本或在可用时检查运行时资源。应报告贴图、附件、着色、插值和循环行为是否真的在 Hytale 中检查过。
资源与版本说明
可用资源包括 hytale://format、hytale://attachments/{id}、hytale://pieces/{id} 和 hytale://cubes/{id}。技术参考检查于 2026-09-13；正在运行的 Hytale 插件版本对可用行为具有最终权威。
限制
- 创建 Bedrock 项目不会激活 Hytale，必须选择 Hytale 格式 ID。
- 四边面无法转换为盒式 UV。
- 当前工具族可列出但不创建附件集合。
- 当前 MCP 工具族没有专用的 UV 偏移关键帧工具。
- 导出的模型有 255 节点限制。
- 贴图宽高必须各自为 32 的正倍数。
- 部分功能受运行中的 Hytale 插件版本限制。