跳到主要内容

FreeMinecraftModels 动画

FreeMinecraftModels 从 .bbmodel 和 .fmmodel 文件导入动画。本页介绍保留名称、动画如何混合、帧时间、插值、循环模式、逆向运动学(IK)以及模型如何转向。

关于骨骼命名规则以及导入契约的其余部分,参见模型制作说明。

状态动画​

FreeMinecraftModels 把下面这六个小写动画名称,以及下文的四个游泳和骑乘动画名称,绑定到自动的运行时状态上。模型中的其他一切都属于自定义动画。

动画名称是否循环何时播放
spawn否模型被创建时播放一次。结束后,若其实体正在移动,模型切换到 walk,否则切换到 idle
idle是实体没有水平速度时。当 X 或 Z 速度变为非零时,交叉淡入到 walk
idle.long否模型显示 idle 且没有其他动画播放,经过随机的 longIdleMinSeconds 到 longIdleMaxSeconds(默认 15 到 30 秒)后播放一次。之后模型交叉淡入回 idle,等待重新开始计时
walk是实体的 X 或 Z 速度不为零时。当两者均为零时,交叉淡入到 idle
attack否被触发时。在 idle 或 walk 之上播放一次,然后结束
death否调用 removeWithDeathAnimation() 时。从当前姿势淡入。结束后,模型会在 20 tick 内缩小消失并被移除

FMM 自己只会为唤魔者(Evoker)触发 attack,时机是唤魔者召唤的尖牙出现在它两格范围内时。其他插件通过 API 触发攻击。EliteMobs 会播放 attack.melee 和 attack.ranged。所有以 attack. 开头的名称都是攻击,播放方式与 attack 相同。

idle.long 无论其 Blockbench 循环设置如何,都只播放一次。移动、攻击或其他动作、基础层上的自定义动画,以及玩家把该生物当作坐骑操控,都会使等待重新开始,同样的情况也会打断正在播放的 idle.long。没有 idle.long 的模型从不等待。idle.long 需要 FreeMinecraftModels 2.15.0 或更高版本;更早的版本把它当作自定义动画。

另有四个基础动画,只要模型有它们,就会在生物游泳或玩家骑乘它时代替 walk 和 idle 播放:

  • 骑乘。 装着马鞍、由玩家操控的马上的模型(例如被骑乘的宠物或 /fmm mount 坐骑),在移动时播放 ride 来代替 walk,站立时播放 idle.ride 来代替 idle。宠物文件可以用 riding.animation 和 riding.idleAnimation 指定其他动画;参见骑乘。插件调用 getAnimationComponent().setRiddenAnimation(name) 和 setRiddenIdleAnimation(name),传入 null 会关闭对应的动画。没有 ride 的模型会在骑乘者身下行走,没有 idle.ride 的模型则会待机。
  • 游泳。 其生物在游泳(即在水中且离开地面)的模型,在移动时播放 swim 来代替 walk,静止不动时播放 idle.swim 来代替 idle。宠物文件可以用 swimming.animation 和 swimming.idleAnimation 指定其他动画;参见游泳。插件调用 getAnimationComponent().setSwimAnimation(name) 和 setIdleSwimAnimation(name),传入 null 会关闭对应的动画。没有 swim 的模型会在水中行走,没有 idle.swim 的模型静止不动时则会待机。玩家操控的坐骑在水中也播放其骑乘动画。

这四个都需要 FreeMinecraftModels 2.15.0 或更高版本。

命名​

动画名称使用小写。点把一般名称与更具体的名称分开,下划线则在同一部分内连接单词:idle.long 是一种 idle,attack.melee 是一种 attack。每个静止姿势都是 idle. 加上它所暂停的那种移动的名称:

移动中静止
在陆地上walkidle,偶尔还有 idle.long
在水中swimidle.swim
被骑乘rideidle.ride

当模型缺少某个带点的名称时,FMM 会改为播放该名称最后一个点之前的部分:attack.melee 改播 attack,idle.swim 改播 idle。脚本和插件播放的名称也是如此:playAnimation 和 hasAnimation 都遵循这一规则。

在此之前制作的模型使用 long_idle、attack_melee 和 attack_ranged。FMM 会在新名称下找到这些旧名称,也会在旧名称下找到新名称,因此旧模型和旧插件无需任何修改即可继续使用。

带点的名称、这种回退以及旧拼写需要 FreeMinecraftModels 2.15.0 或更高版本。

由状态机的构建方式所推导出的规则:

  • 如果模型有 spawn,起始状态就是 spawn,否则是 idle。两者都没有的模型会显示其静止姿势,直到它开始行走或有东西播放动画。
  • 只有模型中存在的动画才会被使用。一个有 walk 但没有 idle 的模型在停止移动后会继续播放行走动画。
  • idle/walk 切换读取底层实体的水平速度;单纯的垂直移动不会开始行走。静态实体与玩家伪装没有供此功能使用的底层实体,静止道具也没有水平移动。其他动画通过脚本、API 或 FMM 伪装控制器驱动。
没有 jump 状态

普通的建模实体没有 jump 状态。名为 jump 的动画表现得和其他任何自定义动画一样,需要按名称播放。玩家伪装是个例外:当玩家跳跃时,它们独立的控制器会播放 jump。

动画混合​

FMM 在 Java 版和 Bedrock 版上,都把模型的动画分成两层来播放,并在每个 tick 把它们混合成同一个姿势。

层在其上播放的内容
基础层spawn、idle、idle.long、walk、骑乘和游泳动画,以及 death,或 blend 设为 false 播放的自定义动画,后者会接管整个姿势
动作层attack 以及所有 attack. 名称(例如 attack.melee 和 attack.ranged)、damaged,以及 blend 设为 true 播放的自定义动画。动作在基础层之上播放,因此模型可以边走边攻击

基础动画没有设置关键帧的骨骼会回到静止姿势。动作没有设置关键帧的骨骼会保持其基础姿势。

淡入淡出​

切换淡入淡出
在 idle、idle.long、walk 以及骑乘和游泳动画之间在 idleWalkBlendTicks(默认 5 tick)内交叉淡入淡出。淡入淡出期间两个动画都继续播放
任何动画到 death从模型上一 tick 显示的姿势(包括动作)出发,在 deathBlendTicks(默认 4 tick)内淡入
其他所有切换立即切换

淡入淡出是缓入缓出的,而不是匀速变化。当新的 idle/walk 切换打断一次淡入淡出时,下一次淡入淡出从模型当时显示的姿势开始。动作的开始和结束没有淡入淡出。

Override 与混合权重​

FMM 从 Blockbench 中每个动画的属性里读取两项设置。

Blockbench 设置在 FMM 中的效果
开启 Override在动作层上,动画设置了关键帧的骨骼采用它的姿势,并舍弃基础姿势
关闭 Override(默认)在动作层上,动画的旋转和位置会叠加到它设置了关键帧的骨骼的基础姿势上,其缩放则与基础缩放相乘
Blend Weight(混合权重)缩放该动画在任一层上的应用强度。1(默认)按制作时的关键帧原样应用。0.5 只应用每个旋转和位置的一半,并使缩放从 1 向关键帧值移动一半

如果攻击设置了关键帧的骨骼必须精确达到制作时的姿势,不受行走循环影响,请开启 Override。若想把攻击的动作叠加到行走上,例如腿部继续行走的同时挥动手臂,请保持关闭。在 Java 上,Override 对基础层动画没有影响,基础层动画总是替换整个姿势。

FMM 只把 Blend Weight 读作普通数字。Molang 表达式会记录 Model <model>, animation <animation> has the blend weight '<value>'. FreeMinecraftModels only reads plain numbers and uses 1. FMM 不支持 Blockbench 的 Start Delay、Loop Delay 和 Anim Time Update。设置了其中任何一项的动画会记录一条警告,并在不使用它们的情况下播放。

哪个动画优先​

  • 自定义动画(包括 damaged)的优先级高于内置动画。当其中一个在任一层播放时,攻击请求会被丢弃。death 会打断一切。
  • 新的动作会替换正在播放的动作,所以第二次攻击会重新开始攻击;以 blend 设为 true 播放的自定义动画会替换正在运行的攻击。
  • 以 blend 设为 false 播放的自定义动画会结束当前动作。
  • 当自定义动画占据基础层时,FMM 会在其下继续跟踪 idle 和 walk。占据基础层会结束正在进行的 spawn 或 idle.long。一次性的自定义动画结束时,模型会立即切换到与其移动状态相符的 idle 或 walk。对 idle 或 walk 的显式请求会立刻结束循环的自定义动画,并在一次性自定义动画结束后显示。
  • 一次性动作在其最后一帧之后结束。如果基础层没有可显示的内容,例如没有 spawn 或 idle 动画的道具,该动作会改为停留在最后一帧,因此以这种方式打开的门会保持打开。当模型没有可返回的 idle 或 walk 时,基础层上的一次性自定义动画也会停留在最后一帧。

玩家伪装使用另一组名称​

玩家伪装增加了一个逐 tick 控制器,通过相同的播放引擎请求动画。它的五个保留名称是 attack、jump、sneak、walk、idle,在单次动画倒计时未运行时按此优先级检查。attack 在动作层上播放,jump 和 sneak 接管基础层,idle 和 walk 选择内置状态。模型没有 idle 时会在控制台警告。完整表格和单次动画的时间限制请参阅玩家伪装。

自定义动画​

任何名称不属于上述状态名称的动画,仍然可以按名称播放:

modeledEntity.playAnimation("open", /* blend */ true, /* loop */ false);
modeledEntity.stopCurrentAnimations();
boolean exists = modeledEntity.hasAnimation("open");
context.prop:play_animation("open", true, false)
context.prop:stop_animation()
  • blend 决定自定义动画所在的层。true 会让它在动作层上、idle 或 walk 之上播放,并使用它在 Blockbench 中的 Override 和混合权重。false 则让它占据基础层,因此它会替换整个姿势并结束当前动作。参见动画混合。
  • 请求会被排队,并在模型下一个 tick 开始时按顺序应用。每个请求都会执行;后来的请求不会取消队列中更早的请求。
  • loop 适用于自定义动画和 damaged。内置名称会忽略 blend 和 loop:idle 和 walk 总是循环,而 spawn、death 和攻击只播放一次。按名称播放的 idle.long 是一个自定义动画,与其他自定义动画无异。
  • 内置名称和攻击名称不区分大小写。对于其他名称,FMM 会先查找准确名称,再查找其小写形式,然后查找已改名名称的旧拼写,最后查找带点名称的一般部分(参见命名)。hasAnimation 能找到的名称与 playAnimation 能播放的名称相同。模型必须包含小写名称,内置状态才能生效。
  • damaged 无论 blend 如何设置,总是在动作层上播放。
  • 对于模型没有的名称,以及 death 被请求之后的任何请求,playAnimation 都返回 false。true 表示请求已入队,而不是已经播放了某一帧:攻击仍然可能被正在运行的自定义动画丢弃。
  • stopCurrentAnimations() 会结束所有自定义动画和动作,并让模型立即回到 idle;若没有 idle,则回到静止姿势。
  • 死亡是终止状态:一旦请求了 death,新的播放请求返回 false,已排队的请求被忽略,stopCurrentAnimations() 也不会有任何作用。

时间与时长​

  • Blockbench 以秒为单位存储动画长度。FMM 使用 ceil(seconds x 20) 进行转换,因此时长永远是整数个 tick,短动画向上取整而不是向下。
  • 只用数字设置关键帧的通道会在导入时被烘焙成一个扁平的逐 tick 帧数组,播放时每 tick 读取一帧。带有 MoLang 关键帧的通道则改为由每个实体逐 tick 采样;参见 MoLang 关键帧。
  • 每个正在播放的动画都有自己的 tick 计数器,因此基础层、动作层和正在淡出的动画各自独立推进。循环动画用 counter % duration 取索引;非循环动画则钳制在其最后一帧。
  • 关键帧时间保留小数 tick 位置(20 x time,不取整),因此 0.37 秒的关键帧也会参与 tick 之间的插值。帧在 0 到 duration - 1 的整数 tick 上采样;恰好位于声明结束时间的关键帧会影响插值,但本身不会被采样。如果必须在可见帧中达到最终姿势,请将其放在这个边界之前。
  • 如果同一通道上的两个关键帧落在完全相同的时间,文件顺序中靠后的那个胜出。
  • 时间为非有限值的关键帧会中止该轨道,并为每个动画产生一条 Malformed animation timeline for model ... 警告,而该模型的其他动画照常转换。

零长度动画是合法的​

长度为 0(或负数)的动画会被视为有意为之的静态姿势 —— 这是家具和其他需要一个具名「无动画」条目的道具中常见的制作选择。它会被静默跳过、不给出警告,并且不贡献任何帧。

循环模式​

Blockbench 的循环设置控制导出的 Bedrock 动画:

Blockbench 循环模式Bedrock 导出
loop"loop": true
once"loop": false
hold"loop": "hold_on_last_frame"

Java 播放使用内置状态的循环规则或自定义动画传入的 loop 参数,不使用这个 Blockbench 字段决定是否循环。因此设置不一致时,Java 与 Bedrock 的播放可能不同。

插值类型​

每个关键帧带有四种插值类型之一:linear、catmullrom(Blockbench 中的 Smooth)、bezier 和 step。超出这一集合的任何值都会解析失败,并被报告为格式错误的时间轴。

FMM 按 Blockbench 预览的方式播放两个关键帧之间的片段,依据两个关键帧的类型,并按以下顺序检查:

  1. step 关键帧保持其值,直到下一个关键帧。
  2. 后面跟着 linear 或 step 关键帧的 linear 关键帧,按直线混合。
  3. 当任一关键帧为 catmullrom 时,该片段沿一条 Catmull-Rom 曲线运动,曲线穿过该片段之前的关键帧、该片段的两个关键帧以及其后的关键帧,因此运动会流畅地经过每个关键帧,而不是在其上停住。缺少相邻关键帧时,以该片段同一侧的端点代替。在 Blockbench 循环模式为 loop、且该通道至少有三个关键帧的动画中,曲线会跨过循环继续,把最后一个关键帧当作再次出现的第一个关键帧。
  4. 否则其中之一是 bezier,片段沿离开关键帧的右手柄和到达关键帧的左手柄运动,包括时间和数值。保存时没有手柄的关键帧,其手柄位于两侧各 0.1 秒处,数值无偏移。手柄的时间会被限制在该片段之内。

在第一个关键帧之前,通道保持该关键帧的值;在最后一个关键帧之后,保持最后一个关键帧的值。

带有各自 pre 值和 post 值的关键帧,以其 pre 值到达,并从其 post 值离开。在平滑片段上,这样的关键帧也会在其一侧结束曲线。FMM 无法读取的 post 值会被忽略。

这些规则适用于烘焙通道、Java 版上的 MoLang 通道,以及 Bedrock 导出的烘焙轨道。它们需要 FreeMinecraftModels 2.15.0 或更高版本。FreeMinecraftModels 2.3.0 到 2.14.2 仅按到达关键帧的类型混合每个片段:catmullrom 在每个关键帧处缓动至停止,bezier 无论手柄如何都使用固定的 0.42 和 0.58 控制点,播放起来几乎是直线,而 step 关键帧会在通向它的片段中途跳到它的值。单独的 pre 值和 post 值会合并为 pre 值。因此,带有平滑、step 或贝塞尔关键帧的模型在更新后运动方式会不同,更接近作者在 Blockbench 中看到的效果。

被动画化的通道​

每根骨骼会烘焙三个通道:旋转、位置和缩放。制作时需要注意的事项:

  • 位置值会被除以 16(Blockbench 像素转方块)。
  • 旋转值会被转换为弧度。
  • Blockbench format_version 5 及更新版本会翻转 X、Y 旋转以及 X 位置的符号。 FMM 会根据声明的格式版本自动补偿,因此不要手工修正 —— 但也不要把 v5 的声明和 v4 形态的数据混在一起。
  • 某个通道上没有关键帧的骨骼,在该通道上保持其静止值。基础层动画完全没有设置关键帧的骨骼,会被重置为旋转 0,0,0、平移 0,0,0、缩放 1,1,1;动作没有设置关键帧的骨骼则保持基础姿势。
  • 关键帧数据点在 .bbmodel 中可能被写成字符串。表示数字的字符串会按该数字读取,空字符串对缩放而言变成 1,其他情况变成 0。任何其他字符串都是 MoLang 表达式;参见 MoLang 关键帧。
  • 带有两个数据点(即 Blockbench 分别设置的 pre 值和 post 值)的关键帧,以第一个值到达,并从第二个值离开。参见插值类型。

MoLang 关键帧​

写成 MoLang 表达式的关键帧值,例如 math.sin(query.anim_time * 360) * 10,会在动画播放期间对每个实体分别求值。

  • 一个通道(即一根骨骼的旋转、位置或缩放,或一个 IK 控制器的位置)只要至少有一个 MoLang 关键帧,就不会被烘焙。每个实体每个 tick 都会对它采样,插值方式和单位换算与烘焙通道相同。该通道上的数字关键帧保持其数值。
  • 可以使用以下查询,也可以使用简写前缀 q.:
查询值
query.anim_time进入此动画的秒数。循环动画每次循环都从 0 重新开始
query.life_time自模型创建以来的秒数
query.modified_distance_moved实体水平移动的方块数
query.is_moving实体水平移动时为 1,否则为 0
  • 其他查询和未知变量读取为 0。v. 变量会在该实体的多次求值之间保留其值,temp.(t.)值只在一个表达式内有效。
  • 表达式使用与粒子 MoLang 相同的运算符和数学函数。
  • 由多条语句组成且没有 return 的程序,取其最后一行的值,与 Blockbench 预览的方式一致。v.a = 10; v.b = v.a * 3; v.b + 5 播放时为 35。最后一行是赋值时,其值为 0。粒子 MoLang 沿用 Bedrock 的规则,即没有 return 的程序值为 0。
  • FMM 无法解析的表达式会在加载时记录一次 Failed to parse the keyframe expression '<expression>' in animation <animation> for model <model>: <reason>. That value plays as 0.。
  • 不是有限数字的结果按 0 播放。
  • 平滑片段还会对其两侧的关键帧求值,以确定曲线形状。这些求值不会保留它们所赋值的任何变量,因此关键帧的赋值只在它开始或结束的片段的 tick 上生效。

Bedrock 玩家在自己的客户端上对这些通道求值:Bedrock 导出会按作者所写原样写出该通道的关键帧,参见 Bedrock 导出。

哪些内容不会被动画化​

  • hitbox 骨骼。指向它的动画轨道会被直接跳过。
  • Blockbench 效果轨道中的声音和时间轴指令关键帧。FMM 只导入效果轨道中的粒子关键帧;参见粒子。请改用 Lua 脚本或你自己的插件来播放声音。
  • 无法按名称解析到的骨骼。指向不存在骨骼的轨道会记录 Failed to get bone <name> from model <model>! 并被跳过。

逆向运动学(IK)​

Blockbench 的空对象(null object)充当 IK 控制器。FMM 在运行时使用 FABRIK(Forward And Backward Reaching Inverse Kinematics)求解骨链,最多 10 次迭代,容差为 0.001。

它们是如何配合的:

  1. 同时具有 ik_source(根骨骼)和 ik_target(末端骨骼或定位器)的空对象定义骨链。检测会检查层级,也支持同级及向下搜索;根层级的同级目标会生成仅包含源骨骼的骨链。
  2. 只有空对象的位置关键帧驱动 IK。每帧偏移会加到目标骨骼或定位器的静止位置上。运行时求解器不会使用已保存的控制器静止位置作为目标基点,旋转与缩放轨道也不驱动 IK。
  3. 每个 tick,每条骨链都会跟随驱动它的最上层正在播放的动画:先是动作,然后是基础动画,再是正在淡出的动画。该动画的目标偏移被应用,然后骨链被求解。没有任何正在播放的动画驱动的骨链会被清除,因此 IK 姿势不会带入不使用它的动画。
  4. lock_ik_target_rotation 会被解析并保存,但当前求解器不会应用它。

无法解析的骨链会被跳过,并给出一条带名称的控制台警告 —— 确切的消息文本和制作约束参见模型制作说明。

Bedrock 导出​

每个转换后的模型还会在生成的资源包内的 animations/<model_id>.animation.json 写出一个 Bedrock 动画文件:

  • 动画标识符为 animation.fmm.<model_id>.a_<hex>,其中 <hex> 是动画名称的 UTF-8 字节的十六进制表示。因此,两个仅在 Bedrock 不允许的字符上有所不同的名称会得到各自独立的标识符。
  • animation_length 是以秒为单位的时长,下限为 0.05,这样只有一个 tick 的动画依然有效。
  • 循环模式按循环模式表中所示进行映射。
  • 没有任何动画的模型仍会得到一个空操作的 idle 条目,以保证 Bedrock 实体定义依然有效。
  • 几何体排除 hitbox、生成的 fmm_nametag_bone_* 名牌骨骼及 m_ 挂载点,保留作者创建的 tag_ 锚点。动画导出器写入烘焙轨道时不会应用相同的可见骨骼过滤,所以不要指望被排除的挂载骨骼在播放动画后出现可见几何体。
  • Bedrock 动画导出使用烘焙的骨骼旋转、位置和缩放帧,不会将运行时 IK 求解结果写入这些轨道。依赖 IK 的模型需要在 Bedrock 上单独验证。
  • 带有 MoLang 关键帧的骨骼通道会按作者所写原样写出(表达式和数字都一样),并由 Bedrock 客户端求值。由多条语句组成的程序会在其最后一行之前写入 return,因此 Bedrock 播放的值与 Java 版相同。从 2.14.2 起,它还会加上 Bedrock 所需的结尾 ;。无论作者设置了何种插值,它的关键帧在 Bedrock 上都按线性混合,并且只写出它们的 pre 值。在 format_version 为 5 或更高的模型上,X 和 Y 旋转以及 X 位置会以取反的形式输出:数字输出其相反数,程序则输出其返回值的相反数,因此 Bedrock 播放的姿势与 Java 版相同。
  • 导出的模型挂在一根 freeminecraftmodels_lean 骨骼上,其枢轴位于模型立方体的中心。它通过四个整数实体属性 freeminecraftmodels:lean_x、lean_y、lean_z 和 body_offset,向 Bedrock 玩家展示行进朝向倾斜和以身体为中心。动画数超过 672(包括为隐藏 saddle 或 fish 骨骼而生成的动画)的模型没有空间容纳这些属性,不会得到倾斜骨骼,在 Bedrock 上保持脚着地的直立状态。
  • 每个动画会生成一个动画控制器,由一个实体属性进行切换,这正是 FMM 在 Bedrock 客户端上播放特定动画的方式。FMM 会同时对基础动画和动作进行切换,与 Java 版的层相对应。
  • 带有名为 saddle(不区分大小写)的骨骼的模型,会在它自己的动画之后再得到一个动画 freeminecraftmodels_hide_saddle,而带有名为 fish 的骨骼的模型会在其后再得到 freeminecraftmodels_hide_fish。它们各自把对应骨骼及其下的骨骼缩小到无,并且只在服务器隐藏该骨骼时播放:可骑乘宠物的马鞍在被装上马鞍之前,以及钓鱼宠物的鱼在它把渔获带回家之前。这需要 FreeMinecraftModels 2.15.0 或更高版本。
  • 开启 Override 的动画写为 "override_previous_animation": true,混合权重不为 1 时写为 "blend_weight"。基础动画 idle、walk、spawn 和 death 排在实体 animate 列表的最前面,因此动作会叠加在它们之上。
  • 控制器的 blend_transition 携带 Java 的淡入淡出时间:idle 和 walk 在 idleWalkBlendTicks 内淡入淡出,death 在 deathBlendTicks 内淡入,其他所有动画立即切换,包括 idle.long 以及骑乘和游泳动画。这些时间在资源包生成时写入,所以配置更改要在资源包重新生成之后才会到达 Bedrock 玩家。
  • 粒子关键帧会成为该动画的 particle_effects 时间轴,因此 Bedrock 客户端会原生播放它们。参见粒子。
版本可用性

这些需要 FreeMinecraftModels 2.16.0:

  • 动画数超过 532 而不是 672 的模型就没有倾斜骨骼,仍然把生成的隐藏动画计算在内。
  • 带关键帧的 X 和 Y 旋转以及 X 位置,在 Bedrock 上的播放方式与 Java 版相同。从 2.8.0 到 2.15.0,每个模型的烘焙轨道,以及 format_version 为 5 或更高的模型的 MoLang 通道,输出时这些轴都被镜像了。围绕零点均匀摆动的动作看起来一样,但偏向一侧的姿势在 Bedrock 上会向另一侧弯曲,例如手肘向后弯。资源包重新生成且玩家客户端采用新资源包后,基岩版玩家就会看到修复。

关于该资源包在磁盘上的落点,参见资源包输出。

转向惯性​

当 weightedTurning 开启(默认)时,生物身上的模型会带着惯性转向生物的朝向,而不是瞬间对齐。每个 tick,它的转向速度最多改变一个加速度的量,直至速度上限,并会及早减速,以便恰好停在新的朝向上。生物本身仍像以前一样转向和行走。模型的骨骼、碰撞箱、定位器和 Bedrock 表现都使用模型的朝向。

这两个限制都取决于模型的大小:

  • 大小是 hitbox 骨骼体积(宽 x 深 x 高,单位为方块)的立方根,再乘以生物的 scale 属性。没有 hitbox 骨骼的模型,改用生物自身碰撞箱的立方根。小于 0.25 的大小按 0.25 计算
  • 最高速度是 turnSpeedCap 除以大小的平方根,且不超过每 tick 90 度
  • 加速度是 turnAcceleration 除以大小

在默认的 turnSpeedCap: 30 和 turnAcceleration: 6 下:

碰撞箱大小最高速度(度/tick)加速度(度/tick,每个 tick)
0.5 x 0.5 x 0.50.542.412
1 x 1 x 11306
2 x 2 x 2221.23
4 x 4 x 44151.5

其他规则:

  • 当玩家直接骑乘其生物,或坐在其某个 m_ 座位上时,模型会瞬间转向,使骑乘者的视角与模型保持一致。
  • 位于玩家所操控的已装鞍马匹上的模型(例如来自 /fmm mount 的模型)会朝向骑乘者所面对的方向,且其头部保持水平,不会跟随骑乘者视线的上下移动。
  • h_ 头部骨骼跟随生物的头部,可以领先较慢的身体最多 75 度。
  • 正在死亡的模型保持它当时的朝向。关闭了移动同步的模型保持自己的朝向。
  • 静态实体、道具和玩家伪装不使用转向惯性。

行进朝向​

动态模型除了朝向其前进方向之外,还可以随行进而倾斜。行走者保持水平,但飞行和游泳的生物通常不应如此。宠物通过其宠物文件的 orientation 部分来设置。插件调用 DynamicEntity#setTravelOrientation(TravelOrientation)。模型默认为 UPRIGHT。

样式倾斜
UPRIGHT无。模型只朝向它前进的方向
TOP_FIRST顶部领先,像水母一样:它倾向行进方向,巡航时侧躺,下潜时倒转
FRONT_FIRST前部领先,像鸟或鱼一样:爬升和下潜时俯仰,转弯时侧倾,侧倾最多 45 度
设置默认值含义
startSpeed0.6低于此速度(方块每秒)时模型保持直立,因此空闲时的漂移和上下起伏不会使它倾斜
fullSpeed4.0达到此速度(方块每秒)时它与行进方向完全对齐。介于两者之间时它部分倾斜
maxTilt180最大倾斜角度,单位为度,0 到 180
turnSpeed180其倾斜每秒最多可以变化的度数
  • 倾斜让整个模型绕其立方体的中心旋转,发生在朝向和动画之后,因此每根骨骼、定位器和挂载点都会随之移动。
  • 速度来自实体的移动,并在几个 tick 内做了平滑。一个 tick 内移动超过 2.5 个方块算作传送,不会使模型倾斜。
  • 模型的生物在游泳(即在水中且离开地面)时,可以朝另一种方式倾斜。宠物用 swimming.orientation 设置(参见游泳),插件用 DynamicEntity#setSwimOrientation(TravelOrientation),其中 null 表示与在陆地上一样倾斜。游泳时,倾斜会立即跟随生物自身的速度,只受 turnSpeed 限制,而不是平滑后的速度,因此游泳者上升时鼻尖朝上,下潜时朝下。这需要 FreeMinecraftModels 2.15.0 或更高版本。
  • 模型在停止、死亡、被玩家骑乘,以及其移动同步关闭时,会缓缓恢复直立。
  • Bedrock 玩家通过导出的倾斜骨骼看到这种倾斜(参见 Bedrock 导出)。它按服务器的 tick 速率分步变化,没有客户端平滑。在资源包首次带着倾斜骨骼重新生成之后,请重启服务器一次,让 Bedrock 桥接注册新的实体属性。

以身体为中心​

ModeledEntity#setCenteredOnBody(true) 会把模型绘制成其立方体的中心位于实体的中心,而不是让它站在实体的脚下。这样,模型远大于其隐藏身体的飞行或游泳生物,会围绕该身体移动、转向和倾斜。备用名牌、点击框和命中框会随模型一起移动。hitbox 和名牌骨骼不计入中心。

它默认关闭。宠物会为 FLYING 和 AQUATIC 物种打开它,其 centerOnBody 键可覆盖这一点。Bedrock 玩家也会通过同一根倾斜骨骼看到居中的模型。Bedrock 实体自身的碰撞箱仍从其脚下开始。

从其他系统播放动画​

调用方入口
插件(Java)ModeledEntity#playAnimation(String, boolean blend, boolean loop) / #stopCurrentAnimations() / #hasAnimation(String)
道具 Lua 脚本context.prop:play_animation(name, blend, loop) / context.prop:stop_animation()
任意 Lua 实体表entity.model:play_animation(name, blend, loop) / entity.model:stop_animations()(当 entity.is_modeled 为 true 时可用)

相关接口请参阅 API 与开发者指南和 Lua:道具 API。

Lua 默认参数不同:context.prop:play_animation(name) 默认为 blend=true, loop=true,而 entity.model:play_animation(name) 默认为 false, false。如果这个区别会影响行为,请明确传入两个布尔值。

故障排除​

我的动画从来不会自动播放。 共享状态机识别小写的 spawn、idle、idle.long、walk、swim、idle.swim、ride、idle.ride、attack 和 death,并把所有 attack. 名称和 damaged 视为动作。移动驱动 idle/walk 切换,游泳和操控的骑乘者会引入游泳和骑乘动画,idle.long 等待一段安静的待机时间,攻击与死亡仍需对应的运行时触发。参见状态动画。除了伪装控制器额外选择的名称,其他名称都需要明确调用 playAnimation / play_animation。

我的模型完全没有反应。 它多半既没有 spawn 也没有 idle 动画,因此在它行走或有东西播放动画之前,只会显示静止姿势。加一个 idle。

模型行走时我的攻击看起来不对。 关闭 Override 时,攻击会叠加到它设置了关键帧的每根骨骼的行走姿势上。请在该攻击的 Blockbench 属性中开启 Override,让这些骨骼采用攻击的姿势,或者减少设置关键帧的骨骼。参见 Override 与混合权重。

我的模型在 idle 和 walk 之间切换得太慢或太突兀。 修改 idleWalkBlendTicks。0 表示立即切换。

我的 idle.long 播放得太频繁、太少或从不播放。 修改 longIdleMinSeconds 和 longIdleMaxSeconds。等待只在模型显示普通 idle 时计时:移动、攻击、自定义动画和骑乘者都会使它重新开始。longIdleMaxSeconds: 0 会关闭 idle.long。

我的平滑、step 或贝塞尔动画在更新后运动方式不同。 FreeMinecraftModels 2.15.0 及更高版本按 Blockbench 预览的方式播放这些关键帧;参见插值类型。请在 Blockbench 的预览中检查该动画:那就是 FMM 现在播放的运动。

我的大型模型转向太慢。 转向速度会随大小下降;参见转向惯性。提高 turnSpeedCap 和 turnAcceleration,检查 hitbox 骨骼是否比预期的大,或设置 weightedTurning: false。

控制台显示 ... FreeMinecraftModels does not support these ... 或 ... has the blend weight ...。 FMM 播放该动画时不使用 Blockbench 的 Start Delay、Loop Delay 和 Anim Time Update,并且只把 Blend Weight 读作普通数字。请清空这些字段,或把 Molang 表达式替换为数字。

我的动画在播放,但什么都没动。 检查动画长度。零长度动画会被视为静态姿势,按设计被静默跳过。

在 Bedrock 上,模型的每个动画(包括待机动画)都会停止,而 Java 版仍能播放。 Bedrock 会拒绝带有 ; 或赋值、但不以 ; 结尾的 MoLang 程序,而一个被拒绝的关键帧就会让该实体上的所有动画停止。FreeMinecraftModels 2.13.0 到 2.14.1 写出这类程序时没有结尾的 ;,而 2.14.2 会加上它。请更新,或者在这些版本上于 Blockbench 中自行用 ; 结束关键帧程序。这不会改变 Java 版的播放效果。

某个 MoLang 关键帧一直停在 0。 检查控制台中是否有 Failed to parse the keyframe expression。最后一行是赋值的程序,其值为 0;请以你想要的值结尾,或使用 return。MoLang 关键帧下列出的四个查询之外的查询读取为 0。

旋转被镜像了。 检查 .bbmodel 中的 meta.format_version。FMM 对格式版本 5 及更新版本翻转 X/Y 旋转符号;一个声明了某个版本却携带另一个版本数据的文件会呈现镜像效果。

控制台显示 Malformed animation timeline for model ...。 该动画中的某条轨道无法被读取或插值。该警告每个动画只触发一次,并会指出涉及的骨骼或 IK 控制器;该模型的其他动画仍会正常转换。

我在 Blockbench 时间轴里的声音毫无反应。 声音关键帧不会被导入。请从 Lua 脚本或你自己的插件触发声音。粒子关键帧会被导入;如果它们没有显示,参见粒子。