blockbench-animation

Blockbench 动画

使用 Blockbench MCP 工具为 3D 模型创建动画。

骨骼绑定和动作决策

动画前，请确认格式支持动画，并确认目标导出器。基于组的 bone_rigging 和 manage_keyframes 操作对象是 Blockbench 组；原生骨架骨骼和顶点权重属于另一种骨骼绑定类型，有各自的工具。不要仅因名称相似，就假定这些组工具可以为 ArmatureBone 制作动画。请参阅 MCP 概览 了解发现方式，并参阅 格式和交付指南 了解目标要求。

请在建模前选择动画类型，因为这会影响几何体。

• Minecraft 仅支持刚性骨骼（节点）动画。在关节处将每个弯曲部分拆分成独立部件，并让它们互相重叠，这样旋转时就不会出现缝隙。
• 蒙皮变形需要带顶点权重的 Generic Model 骨架、关节处的边循环，以及能够保留骨骼绑定的导出器。
• MCP 工具无法制作形态目标。可改用骨骼、可见性关键帧或纹理翻页动画。

请参阅 实时资源规划 第 10 节。

将枢轴放在关节处，并沿层级向外构建。先确定关键姿势和时间安排，再根据动作需要调整重量感、接触、预备动作和跟随动作。平滑插值可能会产生过冲，而机械运动也可能是连续的；应根据动作选择曲线，而不是给某一整类动作指定同一种插值。Blockbench 概览 官方指南介绍了层级、枢轴和时间轴控件。

动画时间以秒为单位。时间轴 FPS 控制吸附，不代表通用的游戏播放速率，也不保证导出器会以该速率采样。请遵循目标格式的规则。检查起始姿势、极值姿势和中间姿势；对于循环片段，还要检查循环衔接处。端点数值相同并不意味着速度平滑或脚部接触稳定。

可用工具

工具	用途
create_animation	为骨骼创建带关键帧的动画
manage_keyframes	按骨骼和通道创建、编辑或删除关键帧
animation_graph_editor	微调动画曲线（平滑、线性、缓入缓出）
bone_rigging	创建或修改动画骨骼结构
animation_timeline	控制播放、时间、FPS 和循环设置
batch_keyframe_operations	批量操作：偏移、缩放、反转、镜像
animation_copy_paste	在骨骼或动画之间复制动画数据

快速开始

创建连续旋转

检查 get_capabilities 中是否有 format.features.animation_mode=true，并使用 list_outline 找出现有骨骼/组。为多网格对象设置动画时，可让共享父组旋转整个对象；添加关键帧前，将该组的枢轴放在预期的中心位置。保留用户现有的项目和几何体。

示例使用工具调用伪代码。将 spin.uuid 绑定到 create_animation 返回的 UUID；不要自行编造动画 ID，也不要假定 ID 带有某种名称前缀。bones 是必填项，即使创建空动画以便后续调用关键帧工具也是如此。

spin = create_animation: name="spin", animation_length=4.0, loop=true, bones={}
manage_keyframes: animation_id=spin.uuid, action="create",
  bone_name="logo_root", channel="rotation", keyframes=[
    {time: 0, values: [0, 0, 0], interpolation: "linear"},
    {time: 1, values: [0, 90, 0], interpolation: "linear"},
    {time: 2, values: [0, 180, 0], interpolation: "linear"},
    {time: 3, values: [0, 270, 0], interpolation: "linear"},
    {time: 4, values: [0, 360, 0], interpolation: "linear"}
  ]
animation_timeline: animation_id=spin.uuid, action="set_time", time=1.0
capture_screenshot
animation_timeline: animation_id=spin.uuid, action="play"

将 logo_root 替换为 list_outline 返回的组。此示例每四秒绕 Y 轴旋转一周；如果 Logo 位于 XY 平面内并要在平面上旋转，则使用 Z 轴。在使用四元数插值的格式中，四分之一圈的关键帧可以保持预期的旋转路径，避免等效方向或 180 度间隔导致旋转方向不明确。播放前以及导出后，请检查中间时间点和循环边界。

动画通道

• position - [x, y, z] 偏移量
• rotation - [x, y, z] 度数
• scale - [x, y, z] 或统一数值

manage_keyframes.values 接受三轴数组，也接受会扩展到所有三轴的数值。各轴数值不同时，尤其是旋转时，优先使用显式数组。数值型工具通道并不意味着支持任意 Molang、Hytale UV 偏移/可见性或效果通道。请使用相应的专用工具或受支持的原生工作流。粒子关键帧、定位器和效果文件详见粒子。

插值类型

• linear - 恒定速率
• catmullrom - 平滑样条
• bezier - 自定义曲线
• step - 瞬间变化

常见工作流

行走循环（1 秒）

这是针对现有腿部骨骼的最简时间示例，并非完整的行走动画。完善循环前，请在实际模型中检查落脚接触、膝盖运动、身体移动和肢体间隙。

walk = create_animation: name="walk", animation_length=1.0, loop=true, bones={
  "leg_left": [
    {time: 0, rotation: [30, 0, 0]},
    {time: 0.5, rotation: [-30, 0, 0]},
    {time: 1.0, rotation: [30, 0, 0]}
  ],
  "leg_right": [
    {time: 0, rotation: [-30, 0, 0]},
    {time: 0.5, rotation: [30, 0, 0]},
    {time: 1.0, rotation: [-30, 0, 0]}
  ]
}

平滑曲线

animation_graph_editor: animation_id=walk.uuid,
  bone_name="leg_left", channel="rotation", action="smooth"

批量调整时间

批量操作使用当前活动动画。selection="all" 会包含隐藏/折叠的动画器，因此，如果请求只涉及较少的关键帧，请使用 selected、range 或 pattern。编辑前请确认当前活动动画。时间操作会拒绝负数/超出范围的时间，以及同一通道中的重复时间。

batch_keyframe_operations: operation="scale", selection="all",
  parameters={scale_factor: 2.0}  # Double keyframe times around zero
animation_timeline: animation_id=walk.uuid, action="set_length", length=2.0

scale 会围绕 scale_pivot（默认为零）缩放关键帧时间。offset_values 会添加数值型 XYZ 分量；mirror 会取反指定分量，并非按解剖学左右进行重定向。数值编辑要求变换关键帧只有一个数据点；表达式或前置/后置数据点请使用原生工具。当前的批量编辑会先验证，再作为一次可撤销事务应用。

烘焙数值曲线

在当前源插件中，operation="bake" 会先对原始连续数值变换曲线进行采样，再插入线性关键帧。它会影响每个所选通道在其首个和最后一个所选时间之间的部分，保留现有采样时间/端点，恢复播放头，并将采样总数限制为 10,000。

batch_keyframe_operations: operation="bake", selection="selected",
  parameters={bake_interval: 0.05}

每个目标通道至少选择两个时间点。间隔单位为秒（最小值为 0.001）；请根据动作/导出目标选择间隔。表达式、效果通道、阶跃曲线和前置/后置数据点均不受支持。只烘焙平滑通道的一部分可能会改变相邻插值，因为边界关键帧会变为线性；若需保留所选范围之外的连续性，请烘焙整个通道。依赖烘焙结果前，请检查采样姿势和目标输出。

骨骼绑定

在现有骨骼之间复制

当前的 animation_copy_paste 会保留原生变换数据点、表达式、前置/后置值、插值和分离的 Bezier 手柄。复制不会修改模型/历史记录；粘贴会作为一次可撤销的动画编辑。

animation_copy_paste: action="copy", source={animation: walk.uuid,
  bone: "leg_left", channels: ["rotation"], time_range: {start: 0, end: 1}}
animation_copy_paste: action="mirror_paste", target={animation: walk.uuid,
  bone: "leg_right", time_offset: 0, mirror_axis: "x"}

粘贴使用精确且不吸附的时间戳，并替换同一通道/时间已有的关键帧。覆盖前请检查目标。mirror_paste 使用原生空间镜像：位置会取反所选轴，旋转会取反另外两轴，缩放保持不变；曲线手柄会跟随镜像后的数值。这不同于批量 mirror，后者会取反一个数值分量。请根据绑定的实际枢轴和朝向检查镜像后的姿势；复制通道不会将动画重定向到比例不同的骨架。剪贴板内容会一直保留，直到下次复制或重新加载插件。

创建骨骼结构

bone_rigging: action="create", bone_data={name: "spine", origin: [0, 12, 0]}
bone_rigging: action="create", bone_data={name: "head", origin: [0, 24, 0], parent: "spine"}

设置枢轴点

bone_rigging: action="set_pivot", bone_data={name: "arm_left", origin: [4, 22, 0]}

时间轴控制

传入返回的动画 UUID 作为 animation_id，即可显式指定时间轴。省略此参数时会使用所选动画；create_animation 会选中创建结果。批量操作使用当前活动动画，因此请先确认其选中状态。批量操作可能会延长动画长度以容纳移动后的关键帧；调整时间后，请显式设置所需的最终片段长度。

animation_timeline: animation_id=spin.uuid, action="set_fps", fps=60
animation_timeline: animation_id=spin.uuid, action="loop", loop_mode="loop"  # or "once", "hold"
animation_timeline: animation_id=spin.uuid, action="set_time", time=0.5
animation_timeline: animation_id=spin.uuid, action="play"

提示

• 使用 list_outline 查看可用骨骼，然后再制作动画
• 先使用 bone_rigging 设置骨骼层级，再添加关键帧
• 适当时使用 catmullrom 创建平滑路径，然后检查是否有过冲
• 使用 step 实现有意的停顿和突然的姿势变化
• 如需精确的旋转值，请使用 manage_keyframes 明确设置各轴的值；同时检查复制或镜像的姿势及其工具结果

导出验证

交接需要可编辑项目时，请保留该项目。确认实际的动画导出工作流：模型编解码器不一定能导出单独的动画文件、控制器或特效。按需提供 Bedrock 动画 JSON 和 Hytale .blockyanim 资源，并确保它们与相应模型一同交付。条件允许时，请在目标环境中验证名称、时长、插值和循环行为。

Molang 表达式需要格式和运行时支持；glTF 和 FBX 无法保留任意由表达式驱动的行为。烘焙可以近似选定的时间序列，但无法保留由变量驱动的状态机。当前的批量烘焙仅支持数值曲线；表达式烘焙需要使用适当的原生工作流。请参阅 Blockbench 动画表达式。