FreeMinecraftModels Animations
FreeMinecraftModels imports animation data from .bbmodel and .fmmodel files. This page covers reserved names, how animations blend, frame timing, interpolation, loop modes, inverse kinematics (IK) and how models turn.
For bone naming rules and the rest of the import contract, see Model Authoring Notes.
State Animations
FreeMinecraftModels binds these six lowercase animation names, and the four swim and ridden ones below, to automatic runtime states. Everything else in the model is a custom animation.
| Animation name | Loops | When it plays |
|---|---|---|
spawn | no | Once, when the model is created. When it ends, the model switches to walk if its entity is moving, otherwise to idle |
idle | yes | While the entity has no horizontal velocity. Cross-fades to walk when X or Z velocity becomes nonzero |
idle.long | no | Once, after the model has shown idle with nothing else playing for a random longIdleMinSeconds to longIdleMaxSeconds (15 to 30 seconds by default). Then the model cross-fades back to idle and the wait starts over |
walk | yes | While the entity's X or Z velocity is nonzero. Cross-fades to idle when both are zero |
attack | no | When triggered. Plays once on top of idle or walk, then ends |
death | no | On removeWithDeathAnimation(). Fades in from the current pose. When it ends, the model shrinks away over 20 ticks and is removed |
FMM triggers attack itself only for Evokers, when fangs the Evoker summoned appear within two blocks of it. Other plugins trigger attacks through the API. EliteMobs plays attack.melee and attack.ranged. Every name that starts with attack. is an attack, played like attack.
idle.long plays once whatever its Blockbench loop setting says. Moving, an attack or other action, a custom animation on the base layer, and a player steering the mob as a mount all start the wait over, and the same things cut an idle.long short. A model without idle.long never waits. idle.long needs FreeMinecraftModels 2.15.0 or later; earlier versions treat it as a custom animation.
Four more base animations play in place of walk and idle while the mob swims or a player rides it, whenever the model has them:
- Ridden. A model on a saddled horse that a player steers, such as a ridden pet or a
/fmm mountmount, playsridein place ofwalkwhile it moves, andidle.ridein place ofidlewhile it stands. A pet file can name other animations withriding.animationandriding.idleAnimation; see Riding. Plugins callgetAnimationComponent().setRiddenAnimation(name)andsetRiddenIdleAnimation(name), wherenullturns one off. A model withoutridewalks under its rider, and one withoutidle.rideidles. - Swim. A model whose mob swims, meaning it is in water and off the ground, plays
swimin place ofwalkwhile it moves, andidle.swimin place ofidlewhile it holds still. A pet file can name other animations withswimming.animationandswimming.idleAnimation; see Swimming. Plugins callgetAnimationComponent().setSwimAnimation(name)andsetIdleSwimAnimation(name), wherenullturns one off. A model withoutswimwalks in water, and one withoutidle.swimidles while it holds still. A mount a player steers plays its ridden animations in water too.
All four need FreeMinecraftModels 2.15.0 or later.
Naming
Animation names are lowercase. A dot separates a general name from a more specific one, and an underscore joins words inside one part: idle.long is a kind of idle, and attack.melee a kind of attack. Each still pose is idle. followed by the name of the movement it pauses:
| Moving | Still | |
|---|---|---|
| On land | walk | idle, and idle.long now and then |
| In water | swim | idle.swim |
| Ridden | ride | idle.ride |
When a model lacks a dotted name, FMM plays the name up to its last dot instead: attack for attack.melee, idle for idle.swim. The same goes for names that scripts and plugins play: playAnimation and hasAnimation both follow it.
Models made before this used long_idle, attack_melee and attack_ranged. FMM finds them under the new names, and the new names under the old ones, so older models and older plugins keep working without changes.
The dotted names, the fallback and the older spellings need FreeMinecraftModels 2.15.0 or later.
Rules that follow from how the state machine is built:
- The starting state is
spawnif the model has one, otherwiseidle. A model with neither shows its rest pose until it starts walking or something plays an animation. - Only animations that exist in the model are used. A model with a
walkbut noidlekeeps walking after it stops moving. - The idle/walk switch reads the underlying entity's horizontal velocity; vertical motion alone does not start walking. Static entities and player disguises have no underlying entity for this purpose, and stationary props have no horizontal movement. Their additional animations are driven through scripts, the API, or FMM's disguise controller.
jump stateRegular modeled entities have no jump state. An animation named jump behaves like any other custom animation and has to be played by name. Player disguises are the exception: their separate controller plays jump when the player jumps.
Animation blending
FMM plays a model's animations in two layers and mixes them into one pose every tick, on Java and on Bedrock.
| Layer | What plays on it |
|---|---|
| Base | spawn, idle, idle.long, walk, the ridden and swim animations, and death, or a custom animation played with blend set to false, which takes over the whole pose |
| Action | attack and every attack. name, such as attack.melee and attack.ranged, damaged, and custom animations played with blend set to true. An action plays on top of the base layer, so a model can attack while it walks |
A bone that the base animation does not key returns to its rest pose. A bone that the action does not key keeps its base pose.
Fades
| Switch | Fade |
|---|---|
Between idle, idle.long, walk and the ridden and swim animations | Cross-fade over idleWalkBlendTicks, default 5 ticks. Both animations keep playing during the fade |
Anything to death | Fade from the pose the model showed on the previous tick, action included, over deathBlendTicks, default 4 ticks |
| Every other switch | Instant |
Fades ease in and out rather than moving at a constant rate. When a new idle/walk switch interrupts a fade, the next fade starts from the pose the model was showing. Actions start and end without a fade.
Override and blend weight
FMM reads two settings from each animation's properties in Blockbench.
| Blockbench setting | Effect in FMM |
|---|---|
| Override on | On the action layer, the bones the animation keys take its pose and drop the base pose |
| Override off (default) | On the action layer, the animation's rotation and position add to the base pose of the bones it keys, and its scale multiplies the base scale |
| Blend Weight | Scales how strongly the animation applies, on either layer. 1 (the default) applies the keyframes as authored. 0.5 applies half of each rotation and position and moves scale halfway from 1 toward the keyed value |
Turn Override on when the bones an attack keys must reach exactly the authored pose, whatever the walk cycle is doing. Leave it off to add the attack's motion to the walk, for example a swing of the arms while the legs keep walking. On Java, Override has no effect on base-layer animations, which always replace the pose.
FMM reads Blend Weight only as a plain number. A Molang expression logs Model <model>, animation <animation> has the blend weight '<value>'. FreeMinecraftModels only reads plain numbers and uses 1. FMM does not support Blockbench's Start Delay, Loop Delay and Anim Time Update. An animation that sets any of them logs a warning and plays without them.
Which animation wins
- Custom animations,
damagedincluded, outrank built-in ones. While one plays on either layer, attack requests are dropped.deathinterrupts everything. - A new action replaces the action that is playing, so a second attack restarts the attack, and a custom animation played with
blendset totruereplaces a running attack. - A custom animation played with
blendset tofalseends the current action. - While a custom animation holds the base layer, FMM keeps tracking idle and walk underneath. Taking the base layer ends a
spawnoridle.longin progress. When a one-shot custom animation ends, the model snaps toidleorwalk, whichever matches its movement. An explicit request foridleorwalkends a looping custom animation at once, and is shown after a one-shot one ends. - A one-shot action ends after its last frame. If the base layer has nothing to show, for example on a prop with no
spawnoridleanimation, the action holds its last frame instead, so a door opened this way stays open. A one-shot custom animation on the base layer also holds its last frame when the model has noidleorwalkto return to.
Player Disguises Use A Different Set
A player disguise adds a per-tick controller that requests animations through the same playback engine. Its five reserved names are attack, jump, sneak, walk, idle, evaluated in that priority order when its one-shot countdown is inactive. attack plays on the action layer, jump and sneak take over the base layer, and idle and walk select the built-in states. It warns on the console if the model has no idle. See Player Disguises for the full table and the one-shot timing caveat.
Custom Animations
Any animation whose name is not one of the state names above can still be played by name:
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()
blendpicks the layer for a custom animation.trueplays it on the action layer, on top ofidleorwalk, with its Blockbench Override and blend weight.falsegives it the base layer, so it replaces the whole pose and ends the current action. See Animation blending.- Requests are queued and applied in order at the start of the model's next tick. Every request runs; a later one does not cancel an earlier one in the queue.
loopapplies to custom animations anddamaged. Built-in names ignore bothblendandloop:idleandwalkalways loop, whilespawn,deathand the attacks play once.idle.longplayed by name is a custom animation like any other.- Built-in and attack names match regardless of case. For other names, FMM looks for the exact name first, then its lowercase form, then the older spelling of a renamed name, then the general part of a dotted name (see Naming).
hasAnimationfinds the same namesplayAnimationplays. The model must contain the lowercase name for a built-in state to work. damagedalways plays on the action layer, whateverblendsays.playAnimationreturnsfalsefor a name the model does not have and for any request afterdeathwas requested.truemeans the request was queued, not that a frame has played: an attack can still be dropped by a running custom animation.stopCurrentAnimations()ends every custom animation and action and snaps the model toidle, or to its rest pose when it has noidle.- Death is terminal: once
deathis requested, new playback requests returnfalse, queued requests are ignored andstopCurrentAnimations()does nothing.
Timing And Duration
- Blockbench stores animation length in seconds. FMM converts it with
ceil(seconds x 20), so duration is always a whole number of ticks and short animations round up rather than down. - A channel keyed only with numbers is baked into a flat per-tick frame array at import time, and playback reads one frame per tick. A channel with a MoLang keyframe is sampled per tick for each entity instead; see MoLang keyframes.
- Each playing animation keeps its own tick counter, so the base layer, the action layer and a fading animation advance independently. Looping animations index with
counter % duration; non-looping ones clamp to their last frame. - Keyframe times keep their fractional tick position (
20 x time, not rounded), so a keyframe at 0.37 s contributes to interpolation between ticks. Frames are sampled at integer ticks from0toduration - 1; a keyframe exactly at the declared end time influences interpolation but is not itself sampled. Place a final pose before that boundary if a rendered frame must reach it. - If two keyframes on the same channel land on exactly the same time, the later one in file order wins.
- A keyframe with a non-finite time aborts that track and produces a single
Malformed animation timeline for model ...warning per animation, while the model's other animations keep converting.
Zero-Length Animations Are Valid
An animation whose length is 0 (or negative) is treated as an intentional static pose — a common authoring choice for furniture and other props that need a named "no animation" entry. It is skipped silently with no warning, and it contributes no frames.
Loop Modes
Blockbench's loop setting controls the exported Bedrock animation:
| Blockbench loop mode | Bedrock export |
|---|---|
loop | "loop": true |
once | "loop": false |
hold | "loop": "hold_on_last_frame" |
Java playback uses the built-in state's loop policy or the loop argument passed for a custom animation. It does not select its loop policy from this Blockbench field, so Java and Bedrock playback can differ when those settings disagree.
Interpolation Types
Each keyframe carries one of four interpolation types: linear, catmullrom (Smooth in Blockbench), bezier and step. Anything outside that set fails to parse and is reported as a malformed timeline.
FMM plays the segment between two keyframes the way Blockbench previews it, from the types of both keyframes, checked in this order:
- A
stepkeyframe holds its value until the next keyframe. - A
linearkeyframe followed by alinearorstepone blends in a straight line. - When either keyframe is
catmullrom, the segment follows a Catmull-Rom curve through the keyframe before the segment, the segment's two keyframes and the keyframe after it, so the motion flows through each keyframe instead of stopping at it. A missing neighbour repeats the segment's own end. In an animation whose Blockbench loop mode isloop, with at least three keyframes on the channel, the curve carries on across the loop, treating the last keyframe as the first one again. - Otherwise one of them is
bezier, and the segment follows the leaving keyframe's right handle and the arriving keyframe's left handle, in time and value. A keyframe saved without handles has them 0.1 seconds to either side with no value offset. A handle's time is kept inside the segment.
Before its first keyframe a channel holds that keyframe's value, and after its last keyframe it holds the last one's.
A keyframe with separate pre and post values is reached at its pre value and left from its post value. On a smooth segment, such a keyframe also ends the curve on its side. A post value that FMM cannot read is ignored.
These rules apply to baked channels, to MoLang channels on Java, and to the baked tracks of the Bedrock export. They need FreeMinecraftModels 2.15.0 or later. FreeMinecraftModels 2.3.0 to 2.14.2 blended each segment by the arriving keyframe's type alone: catmullrom eased to a stop at every keyframe, bezier used fixed 0.42 and 0.58 control points whatever its handles said, which played almost straight, and a step keyframe jumped to its value halfway through the segment leading into it. Separate pre and post values collapsed to the pre value. Models with smooth, step or Bezier keyframes therefore move differently after the update, closer to what their author saw in Blockbench.
Animated Channels
Three channels are baked per bone: rotation, position, and scale. Notes that matter when authoring:
- Position values are divided by 16 (Blockbench pixels to blocks).
- Rotation values are converted to radians.
- Blockbench
format_version5 and newer flips the sign of X and Y rotation and of X position. FMM compensates automatically based on the declared format version, so do not hand-correct for it — but do not mix a v5 declaration with v4-shaped data either. - A bone with no keyframes on a channel keeps its rest value for that channel. A bone the base-layer animation does not key at all is reset to rotation
0,0,0, translation0,0,0, scale1,1,1; a bone the action does not key keeps the base pose. - Keyframe data points may be written as strings in the
.bbmodel. A string that is a number is read as that number, and an empty string becomes1for scale and0otherwise. Any other string is a MoLang expression; see MoLang keyframes. - A keyframe with two data points, Blockbench's separate pre and post values, is reached at the first and left from the second. See Interpolation Types.
MoLang keyframes
A keyframe value written as a MoLang expression, such as math.sin(query.anim_time * 360) * 10, is evaluated for each entity while the animation plays.
- A channel, meaning the rotation, position or scale of one bone or the position of an IK controller, that has at least one MoLang keyframe is not baked. Each entity samples it every tick, with the same interpolation and the same unit conversion as baked channels. Number keyframes on that channel keep their values.
- These queries are available, also with the short
q.prefix:
| Query | Value |
|---|---|
query.anim_time | Seconds into this animation. A looping animation starts again from 0 each loop |
query.life_time | Seconds since the model was created |
query.modified_distance_moved | Blocks the entity has moved horizontally |
query.is_moving | 1 while the entity moves horizontally, otherwise 0 |
- Other queries and unknown variables read as
0. Av.variable keeps its value on that entity between evaluations, and atemp.(t.) value lasts for one expression. - Expressions use the same operators and math functions as particle MoLang.
- A program of several statements without
returntakes the value of its last line, as Blockbench previews it.v.a = 10; v.b = v.a * 3; v.b + 5plays as35. A last line that is an assignment is worth0. Particle MoLang keeps Bedrock's rule, where a program withoutreturnis worth0. - An expression FMM cannot parse logs
Failed to parse the keyframe expression '<expression>' in animation <animation> for model <model>: <reason>. That value plays as 0.once at load. - A result that is not a finite number plays as
0. - A smooth segment also evaluates the keyframes on either side of it to shape its curve. Those evaluations keep none of the variables they assign, so a keyframe's assignments take effect only on the ticks of the segments it starts or ends.
Bedrock players evaluate these channels on their own client: the Bedrock export writes the channel's keyframes as authored, see Bedrock export.
What Is Not Animated
- The
hitboxbone. Animation tracks targeting it are skipped outright. - Sound and timeline-instruction keyframes in Blockbench effect tracks. FMM imports only the particle keyframes of an effect track; see Particles. Play sounds from a Lua script or from your own plugin instead.
- Bones that could not be resolved by name. A track pointing at a missing bone logs
Failed to get bone <name> from model <model>!and is skipped.
Inverse Kinematics (IK)
Blockbench null objects act as IK controllers. FMM solves chains at runtime with FABRIK (Forward And Backward Reaching Inverse Kinematics), capped at 10 iterations with a 0.001 tolerance.
How it fits together:
- A null object with both
ik_source(chain root bone) andik_target(end bone or locator) defines a chain. Discovery checks the hierarchy and also supports sibling/downward searches; root-level sibling targets produce a source-only chain. - Only the null object's position keyframes drive IK. They become a per-frame offset added to the target bone's or locator's rest position. The runtime solver does not use the controller's stored rest position as the goal base. Rotation and scale tracks do not drive IK.
- Each tick, each chain follows the topmost playing animation that drives it: the action, then the base animation, then an animation fading out. That animation's goal offset is applied and the chain is solved. A chain that no playing animation drives is cleared, so an IK pose does not carry over into an animation that does not use it.
lock_ik_target_rotationis parsed and stored, but the current solver does not apply it.
Chains that cannot be resolved are skipped with a named console warning — see Model Authoring Notes for the exact messages and the authoring constraints.
Bedrock Export
Each converted model also writes a Bedrock animation file at animations/<model_id>.animation.json inside the generated bundle:
- Animation identifiers are
animation.fmm.<model_id>.a_<hex>, where<hex>is the animation name's UTF-8 bytes written as hexadecimal. Two names that differ only in characters Bedrock does not allow therefore get separate identifiers. animation_lengthis the duration in seconds, floored at0.05so a one-tick animation is still valid.- Loop mode is mapped as shown in the Loop Modes table.
- A model with no animations still gets a single no-op
idleentry so the Bedrock entity definition stays valid. - Geometry excludes
hitbox, generatedfmm_nametag_bone_*nametag bones andm_mount-point bones; authoredtag_anchors remain. The animation exporter writes baked bone tracks without applying that same visual-bone filter, so do not animate excluded mount bones expecting visible geometry. - Bedrock animation export uses baked bone rotation, position and scale frames. It does not bake the runtime IK solver's rotations into those tracks; verify IK-dependent models separately on Bedrock.
- A bone channel with a MoLang keyframe is written as authored instead, expressions and numbers alike, and Bedrock clients evaluate it. A program of several statements is written with
returnbefore its last line, so Bedrock plays the same value as Java. From 2.14.2, it also gets the closing;Bedrock requires. Its keyframes blend linearly on Bedrock, whatever interpolation was authored, and only their pre values are written. On a model withformat_version5 or newer, X and Y rotation and X position go out negated, a number as its negative and a program with what it returns negated, so Bedrock plays the same pose as Java. - An exported model hangs from a
freeminecraftmodels_leanbone pivoted at the middle of its cubes. It shows the travel orientation lean and centring to Bedrock players through four integer entity properties,freeminecraftmodels:lean_x,lean_y,lean_zandbody_offset. A model with more than 672 animations, counting the generated ones that hide asaddleorfishbone, has no room for those properties, gets no lean bone, and stays upright on its feet on Bedrock. - One animation controller is generated per animation, switched by an entity property, which is how FMM plays a specific animation on a Bedrock client. FMM switches on the base animation and the action together, matching the Java layers.
- A model with a bone named
saddle, in any case, gets one more animation,freeminecraftmodels_hide_saddle, after its own, and one with a bone namedfishgetsfreeminecraftmodels_hide_fishafter that. Each shrinks its bone and the bones under it to nothing, and plays only while the server hides the bone: a rideable pet's saddle until it is saddled, and a fishing pet's fish until it carries a catch home. This needs FreeMinecraftModels 2.15.0 or later. - An animation with Override on is written with
"override_previous_animation": true, and a blend weight other than1as"blend_weight". The base animationsidle,walk,spawnanddeathcome first in the entity's animate list, so actions layer on top of them. - The controllers'
blend_transitioncarries the Java fade times:idleandwalkfade in and out overidleWalkBlendTicks,deathfades in overdeathBlendTicks, and every other animation switches instantly,idle.longand the ridden and swim animations included. The times are written when the pack is generated, so a config change reaches Bedrock players after the pack regenerates. - Particle keyframes become the animation's
particle_effectstimeline, so Bedrock clients play them natively. See Particles.
These need FreeMinecraftModels 2.16.0:
- A model has no lean bone above 532 animations instead of 672, still counting the generated hide animations.
- Keyed X and Y rotation and X position play the same way on Bedrock as on Java. From 2.8.0 to 2.15.0, the baked tracks of every model, and the MoLang channels of a model with
format_version5 or newer, went out with those axes mirrored. Motion that swings evenly around zero looked the same, but a pose held to one side bent the other way on Bedrock, such as an elbow bent backward. Bedrock players see the fix once the pack regenerates and their client takes the new pack.
See Resource Pack Output for where the bundle lands on disk.
Turning inertia
With weightedTurning on (the default), a model on a mob turns toward the mob's facing with inertia instead of snapping to it. Each tick its turning speed changes by at most the acceleration, up to the speed cap, and it slows down early enough to stop exactly on the new facing. The mob itself turns and walks as before. The model's bones, hitbox, locators and Bedrock presentation all use the model's facing.
Both limits depend on the model's size:
- Size is the cube root of the
hitboxbone's volume (width x depth x height, in blocks), times the mob'sscaleattribute. A model without ahitboxbone uses the cube root of the mob's own bounding box instead. Sizes below0.25count as0.25 - Top speed is
turnSpeedCapdivided by the square root of the size, and never more than 90 degrees per tick - Acceleration is
turnAccelerationdivided by the size
With the default turnSpeedCap: 30 and turnAcceleration: 6:
| Hitbox | Size | Top speed (degrees per tick) | Acceleration (degrees per tick, each tick) |
|---|---|---|---|
| 0.5 x 0.5 x 0.5 | 0.5 | 42.4 | 12 |
| 1 x 1 x 1 | 1 | 30 | 6 |
| 2 x 2 x 2 | 2 | 21.2 | 3 |
| 4 x 4 x 4 | 4 | 15 | 1.5 |
Other rules:
- A model turns instantly while a player rides its mob directly or sits on one of its
m_seats, so the rider's view and the model stay together. - A model on a saddled horse that a player steers, such as one from
/fmm mount, faces where the rider faces, and its head stays level instead of following the rider's look up and down. h_head bones follow the mob's head and can lead the slower body by up to 75 degrees.- A dying model keeps the facing it had. A model whose movement sync is off keeps its own facing.
- Static entities, props and player disguises do not use turning inertia.
Travel orientation
A dynamic model can lean with its travel as well as face its heading. Walkers stay level, but flying and swimming creatures usually should not. Pets set this from the orientation section of their pet file. Plugins call DynamicEntity#setTravelOrientation(TravelOrientation). Models are UPRIGHT by default.
| Style | Lean |
|---|---|
UPRIGHT | None. The model only faces where it goes |
TOP_FIRST | Its top leads, like a jellyfish: it leans into its travel, lies on its side cruising and turns upside down to dive |
FRONT_FIRST | Its front leads, like a bird or fish: it pitches into climbs and dives and banks into turns, up to 45 degrees of bank |
| Setting | Default | Meaning |
|---|---|---|
startSpeed | 0.6 | Blocks per second below which the model stays upright, so idle drifting and bobbing do not tip it |
fullSpeed | 4.0 | Blocks per second at which it lines up fully with its travel. Between the two it leans partway |
maxTilt | 180 | Most it leans, in degrees, 0 to 180 |
turnSpeed | 180 | Degrees per second its lean can change |
- The lean turns the whole model about the middle of its cubes, after its facing and its animations, so every bone, locator and mount point follows it.
- The speed comes from the entity's movement, smoothed over a few ticks. A move of more than 2.5 blocks in one tick counts as a teleport and does not lean the model.
- A model can lean another way while its mob swims, meaning it is in water and off the ground. Pets set this with
swimming.orientation(see Swimming), and plugins withDynamicEntity#setSwimOrientation(TravelOrientation), wherenullleans as on land. While it swims, the lean follows the mob's own velocity at once, held back only byturnSpeed, rather than the smoothed speed, so a swimmer's nose points up while it rises and down while it dips. This needs FreeMinecraftModels 2.15.0 or later. - The model eases back upright when it stops, while it dies, while a player rides it and while its movement sync is off.
- Bedrock players see the lean through the exported lean bone (see Bedrock export). It steps at the server's tick rate without client smoothing. After the pack first regenerates with the lean bone, restart the server once so the Bedrock bridge registers the new entity properties.
Centring on the body
ModeledEntity#setCenteredOnBody(true) draws a model with the middle of its cubes on the middle of its entity, instead of standing it on the entity's feet. A flying or swimming creature whose model is much bigger than its hidden body then moves, turns and leans around that body. The fallback nameplate, the click box and the hit box move with the model. The hitbox and nametag bones do not count toward the middle.
It is off by default. Pets turn it on for FLYING and AQUATIC species, and their centerOnBody key overrides that. Bedrock players see the model centred too, through the same lean bone. The Bedrock entity's own collision box still starts at its feet.
Playing Animations From Other Systems
| Caller | Entry point |
|---|---|
| Plugin (Java) | ModeledEntity#playAnimation(String, boolean blend, boolean loop) / #stopCurrentAnimations() / #hasAnimation(String) |
| Prop Lua script | context.prop:play_animation(name, blend, loop) / context.prop:stop_animation() |
| Any Lua entity table | entity.model:play_animation(name, blend, loop) / entity.model:stop_animations() (available when entity.is_modeled is true) |
See the API & Developer Guide and Lua: Prop API for the surrounding surfaces.
The Lua defaults differ: context.prop:play_animation(name) defaults to blend=true, loop=true, while entity.model:play_animation(name) defaults to false, false. Pass both booleans explicitly when the distinction matters.
Troubleshooting
My animation never plays automatically.
The shared state machine recognizes lowercase spawn, idle, idle.long, walk, swim, idle.swim, ride, idle.ride, attack and death, and treats every attack. name and damaged as actions. Movement drives idle/walk transitions, swimming and a steering rider bring in the swim and ridden animations, and idle.long waits for a quiet spell of idling; attacks and death still need their runtime trigger. See State Animations. Other names need an explicit playAnimation / play_animation call, except for the additional names selected by the disguise controller.
My model does nothing at all.
It probably has neither a spawn nor an idle animation, so it shows its rest pose until it walks or something plays an animation. Add an idle.
My attack looks wrong while the model walks. With Override off, the attack adds to the walk pose of every bone it keys. Turn Override on in the attack's Blockbench properties so those bones take the attack's pose, or key fewer bones. See Override and blend weight.
My model switches between idle and walk too slowly or too abruptly.
Change idleWalkBlendTicks. 0 switches instantly.
My idle.long plays too often, too rarely or never.
Change longIdleMinSeconds and longIdleMaxSeconds. The wait only counts while the model shows plain idle: moving, attacks, custom animations and riders start it over. longIdleMaxSeconds: 0 turns idle.long off.
My smooth, step or Bezier animation moves differently after an update. FreeMinecraftModels 2.15.0 and later play these keyframes the way Blockbench previews them; see Interpolation Types. Check the animation in Blockbench's preview: that is the motion FMM now plays.
My big model turns too slowly.
Turning speed falls with size; see Turning inertia. Raise turnSpeedCap and turnAcceleration, check that the hitbox bone is not larger than intended, or set weightedTurning: false.
Console says ... FreeMinecraftModels does not support these ... or ... has the blend weight ....
FMM plays that animation without Blockbench's Start Delay, Loop Delay and Anim Time Update, and reads Blend Weight only as a plain number. Clear those fields or replace the Molang expression with a number.
My animation plays but nothing moves. Check the animation length. A zero-length animation is treated as a static pose and is skipped silently by design.
On Bedrock, every animation of a model stops, idle included, while Java plays them.
Bedrock rejects a MoLang program with a ; or an assignment unless it ends with ;, and one rejected keyframe stops every animation on the entity. FreeMinecraftModels 2.13.0 to 2.14.1 write such programs without the closing ;, and 2.14.2 adds it. Update, or on those versions end the keyframe program with ; yourself in Blockbench. Java plays it the same way.
A MoLang keyframe holds still at 0.
Check the console for Failed to parse the keyframe expression. A program whose last line is an assignment is worth 0; end it with the value you want, or with return. Queries other than the four listed under MoLang keyframes read as 0.
Rotations are mirrored.
Check meta.format_version in the .bbmodel. FMM flips X/Y rotation sign for format version 5 and newer; a file that declares one version but carries the other version's data will come out mirrored.
Console says Malformed animation timeline for model ....
One track in that animation could not be read or interpolated. The warning fires once per animation and names the bone or IK controller involved; the model's other animations still convert.
Sounds in my Blockbench timeline do nothing. Sound keyframes are not imported. Trigger sounds from a Lua script or your own plugin. Particle keyframes are imported; if they don't show, see Particles.