blockbench-hytale

Blockbench Hytale

在适用的情况下，使用共享的建模、纹理绘制和动画工作流。

选择实际的 Hytale 格式

调用 get_capabilities: include_tools=true，并选择返回的 Hytale 格式 ID。创建 Bedrock 项目不会启用 Hytale。

格式	每个世界方块的单位数	用途
hytale_character	64	角色和附件，包括工具、武器与外观物品
hytale_prop	32	世界道具、家具和方块

这些数值描述的是几何体／纹素密度，并非图集分辨率上限。纹理宽度和高度可以不同，但必须分别为 32 的倍数。让有效 UV 尺寸与实际图像相符，并保留与尺寸关联的格式面 UV。官方 Hytale 美术指南介绍了密度和图集尺寸。

get_capabilities: format_id="hytale_character"
create_project: name="goblin", format="hytale_character"
hytale_get_format_info
# → formatType, blockSize, animationFPS, nodeCount, maxNodes, nodeCountValid, features

仅在确实要创建新项目时使用 create_project。替换内容前先检查现有项目。

对于新的静态 128×96 Hytale 图集，明确匹配 UV 和位图尺寸（两种 Hytale 格式都支持按纹理设置 UV 尺寸）：

create_texture: name="goblin_atlas", width=128, height=96,
  uv_width=128, uv_height=96, fill_color="#808080", layer_name="base"
list_textures
# Confirm uv_size, bitmap_size and frame_size are [128,96]

当前源代码插件支持 uv_width／uv_height 参数对；请确认已加载的工具架构支持这些参数。创建此图像不会自动为模型打包 UV；需要新布局时，请按照纹理绘制技能中的原生模板工作流操作。

几何体和 UV

该格式支持立方体／四边形、基于关节的分组、拉伸、可选的盒状 UV 和按纹理设置 UV 尺寸。使用插件默认尺寸设置时，请采用整数基础尺寸；拉伸可以在保留 UV 布局的同时实现更精细的可见尺寸。基础尺寸并非绝对不能使用小数，但这样会更难保持 UV 一致性。导出的模型最多支持 255 个节点；导出器将分组的主立方体折叠后，会影响实际计数。这些格式行为记录在 Hytale 格式源代码中。

add_group: name="rig_root", origin=[0, 0, 0]
add_group: name="body", parent="rig_root", origin=[0, 24, 0]
place_cube: elements=[{name: "torso_geo", from: [-8, 24, -4], to: [8, 48, 4]}], group="body"
hytale_set_cube_stretch: cube_id="torso_geo", stretch=[1.1, 1, 1]
hytale_get_cube_stretch: cube_id="torso_geo"

hytale_create_quad: name="leaf", position=[0, 16, 0],
  normal="+Y", size=[8, 8], double_sided=true

法线可以是 +X、-X、+Y、-Y、+Z 或 -Z。需要显示两侧时，请使用双面渲染。细微调整拉伸可以修复相交问题；美术指南建议每个轴大约使用 0.7–1.3，以符合其风格。这是视觉建议，并非 MCP 架构规定的有效范围。先铺设颜色，再绘制体积感和精细细节，并避免出现非预期的杂乱颗粒。柔边画笔适合 Hytale 的绘画风格，但不要求像素级精确绘制。请参阅美术指南。

set_cube_uv 会保留 Hytale 的 autouv=1 和与尺寸关联的矩形大小。移动或镜像面的 UV 时，请保留其绝对基础几何体宽度／高度（UV 旋转 90／270 度时需交换）；更改这些范围会在撤销前被拒绝。拉伸会改变可见形状，但不会改变该基础 UV 尺寸。对于上方逐面设置的 torso_geo，未旋转的北面为 16×24：

get_cube_uv: id="torso_geo"
set_cube_uv: id="torso_geo", faces={north: {uv: [8, 8, 24, 32], rotation: 0}}

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_set_cube_properties: cube_id="torso_geo", shading_mode="standard"
hytale_get_cube_properties: cube_id="torso_geo"

附件

hytale_list_attachments 会列出已有的附件集合。hytale_set_attachment_piece 用于标记现有组；hytale_list_attachment_pieces 用于读取这些标记。部件会附加到名称匹配的基础模型骨骼上，因此请检查两项资产并保留所需名称。

# Existing attachment group whose name matches the intended base bone
hytale_set_attachment_piece: group_name="hand_right", is_piece=true
hytale_list_attachment_pieces
hytale_list_attachments

标记组不会创建集合、配置游戏中的物品，也不会导出独立附件。当前工具系列可以列出集合，但不能创建集合。需要时，请使用已安装插件的原生集合／附件工作流。模型编译器在导出附件专用内容时需要一个有效的 Collection；通用 export_model.options 中的 JSON 字符串并不是该对象。请将附件与基础模型一起验证，并检查实际导出的节点。参见Hytale 插件功能和模型编解码器源代码。

动画

Hytale 动画文件使用每秒 60 帧的单位。MCP 关键帧时间以秒为单位；导出时，time=0.5 表示第 30 帧。请使用 create_animation 返回的动画 UUID 和现有组名称：

draw = create_animation: name="draw", animation_length=1, bones={}
hytale_create_visibility_keyframe: animation_id=draw.uuid,
  bone_name="weapon_sheathed", time=0, visible=true
hytale_create_visibility_keyframe: animation_id=draw.uuid,
  bone_name="weapon_sheathed", time=0.5, visible=false
hytale_set_animation_loop: animation_id=draw.uuid, loop_mode="hold"

示例使用工具调用伪代码；请将 draw.uuid 绑定到返回的 UUID。可见性更改需要初始状态以及过渡关键帧。要在两种表现形式间切换，请在同一时间为二者都设置关键帧。

Hytale 使用四元数插值，并会循环播放循环片段。进行完整旋转时，请使用关键帧间旋转角小于 180 度的中间姿态，并预览旋转方向和循环衔接处。原生 UV 偏移通道确实存在，但当前 MCP 工具系列没有专用的 UV 偏移关键帧工具。

上游 .blockyanim 导出器会写入 holdLastKeyframe，并将 Catmull-Rom 映射为平滑插值，将其他插值映射为线性插值。因此，编辑器中的 once、step 或 Bezier 状态并不能证明运行时播放效果等同。请验证实际导出结果和目标环境中的行为。这些细节来自动画编解码器源代码。

验证和导出

1. 检查相关姿势下的 UV／位图尺寸、纹理分配、拉伸和几何体。
2. 运行 hytale_validate_model，然后检查其问题和 scope。当前实现会统计已安装的 blockymodel 编译器主模型输出中的节点，并检查两个纹理尺寸是否都是 32 的正整数倍。它会报告 main_model_node_count_and_texture_dimensions；附件和完整的引擎兼容性需要单独检查。旧版软件包使用启发式节点计数和错误的基于密度的纹理检查，因此请先发现／重新加载当前版本，再依赖此结果。
3. 使用 list_export_formats 发现可用格式；若要导出模型，请使用已注册的 blockymodel 编解码器。纹理图像是单独的交付物。
4. 通过已安装插件的原生动画工作流导出动画。上游提供 export_blockyanim 操作；如果发现结果中没有 blockyanim 模型编解码器，请勿自行假设其存在。通过授权的 UI 工作流完成随后出现的原生保存对话框。
5. 重新打开副本，或在可用时检查运行时资产。请说明是否已在 Hytale 中实际检查纹理、附件、着色、插值和循环行为。

资源包括 hytale://format、hytale://attachments/{id}、hytale://pieces/{id} 和 hytale://cubes/{id}。技术参考核对日期为 2026-09-13；可用行为以正在运行的 Hytale 插件版本为准。