Guide · Animation

Hand Condition Animations (Items in Hand)

Condition animations in Yes Steve Model (YSM) are specially named animations that play automatically when certain in-game triggers occur, allowing you to create responsive actions without touching complex animation controllers. Hand condition animations specifically control how your character's arms react when holding, using, or swinging items.

How Hand Condition Animations Work

Because a player's hands perform so many distinct actions in Minecraft, YSM separates hand condition animations into their own dedicated file. For default models, all hand condition animations must be placed inside the arm.animation.json file.

Hand animations have a higher priority than main animations and will override bone groups animated in the main file. Because of this override behavior, you should only animate arm and hand bones inside your hand animations—never include unrelated body groups like legs or the waist.

If you do not define specific condition animations for an item, the game will automatically fall back to the default base animations: use_mainhand, use_offhand, and swing_hand.

Only keyframe arm and hand bones in arm.animation.json so you do not accidentally freeze your character's walking or idle body movements.

Minecraft Terminology & Item Identification

To name your animations properly, you need to understand how Minecraft classifies hands, actions, and items. YSM builds its animation names by combining the hand, the action type, and the item identifier.

In vanilla Minecraft, mainhand refers to the primary hand (default right hand), while offhand refers to the secondary hand (default left hand). There are three main actions: use (right-clicking an usable item like food, bows, or shields in either hand), swing (left-clicking, which normally only affects the mainhand), and hold (simply holding an item in either hand without pressing any buttons).

You can target specific items using either their unique Item ID or an Item Tag. Press the F3 + H shortcut in-game to enable advanced tooltips and view exact Item IDs (such as minecraft:shield). Item Tags group similar items together (such as all swords or all dirt blocks) and can be looked up on the Minecraft Wiki.

Built-in Use Animations (Right-Click)

Use animations play when a player holds down right-click with an interactive item in their mainhand or offhand. YSM provides built-in category names that automatically work with both vanilla items and most modded items of the same type.

For continuous charge or aim actions—specifically bow, spear, lance (added in version 2.6.5), crossbow, spyglass, and toot_horn—it is strongly recommended to set the animation loop mode in Blockbench to 'Hold on Last Frame'.

use_mainhand:eat        / use_offhand:eat        (Eating food, lasts ~1.5s)
use_mainhand:drink      / use_offhand:drink      (Drinking potions/milk, lasts ~1.5s)
use_mainhand:shield     / use_offhand:shield     (Using a shield)
use_mainhand:block      / use_offhand:block      (Defensive blocking state)
use_mainhand:bow        / use_offhand:bow        (Drawing a bow - Hold on last frame)
use_mainhand:spear      / use_offhand:spear      (Charging a trident - Hold on last frame)
use_mainhand:lance      / use_offhand:lance      (Using a lance [since 2.6.5] - Hold on last frame)
use_mainhand:crossbow   / use_offhand:crossbow   (Charging a crossbow - Hold on last frame)
use_mainhand:spyglass   / use_offhand:spyglass   (Looking through a spyglass - Hold on last frame)
use_mainhand:toot_horn  / use_offhand:toot_horn  (Blowing a goat horn - Hold on last frame)
use_mainhand:brush      / use_offhand:brush      (Brushing blocks)

Built-in Swing Animations (Left-Click)

Because players usually only swing their mainhand when left-clicking, mainhand swing animations simply start with swing, whereas offhand swings start with swing_offhand. Once triggered, a swing animation will always play through to completion even if the player stops clicking.

YSM includes 8 built-in swing categories that generally support modded tools and weapons out of the box (note that fishing_rod was added in version 2.3.0).

swing:sword             / swing_offhand:sword            (Swinging a sword)
swing:axe               / swing_offhand:axe              (Swinging an axe)
swing:pickaxe           / swing_offhand:pickaxe          (Swinging a pickaxe)
swing:shovel            / swing_offhand:shovel           (Swinging a shovel)
swing:hoe               / swing_offhand:hoe              (Swinging a hoe)
swing:shield            / swing_offhand:shield           (Swinging a shield)
swing:throwable_potion  / swing_offhand:throwable_potion (Throwing a splash/lingering potion)
swing:fishing_rod       / swing_offhand:fishing_rod      (Casting or reeling a fishing rod [since 2.3.0])

Built-in Hold Animations (Idle in Hand)

Hold animations play when the player is holding an item without actively using or swinging it, and both mainhand and offhand hold animations can play simultaneously. Whenever the player switches to a different item in their hotbar, the hold animation restarts from the first frame, allowing you to animate smooth weapon-draw transitions.

Because charged crossbows and cast fishing rods cannot be distinguished by item IDs or tags alone, YSM provides special fixed names for them alongside standard item categories. Note that hold_mainhand:fishing only exists for the mainhand.

hold_mainhand:empty             / hold_offhand:empty             (Empty hand)
hold_mainhand:charged_crossbow  / hold_offhand:charged_crossbow  (Holding a loaded crossbow)
hold_mainhand:crossbow          / hold_offhand:crossbow          (Holding an unloaded crossbow)
hold_mainhand:fishing_rod       / hold_offhand:fishing_rod       (Holding a fishing rod [since 2.3.0])
hold_mainhand:fishing                                            (Holding a rod with hook cast - mainhand only)
hold_mainhand:slashblade        / hold_offhand:slashblade        (Holding a SlashBlade katana [since 2.3.0])
hold_mainhand:sword             / hold_offhand:sword             (Holding a sword)
hold_mainhand:axe               / hold_offhand:axe               (Holding an axe)
hold_mainhand:pickaxe           / hold_offhand:pickaxe           (Holding a pickaxe)
hold_mainhand:shovel            / hold_offhand:shovel            (Holding a shovel)
hold_mainhand:hoe               / hold_offhand:hoe               (Holding a hoe)
hold_mainhand:shield            / hold_offhand:shield            (Holding a shield)
hold_mainhand:throwable_potion  / hold_offhand:throwable_potion  (Holding a throwable potion)
hold_mainhand:eat               / hold_offhand:eat               (Holding food)
hold_mainhand:drink             / hold_offhand:drink             (Holding a drinkable item)
hold_mainhand:bow               / hold_offhand:bow               (Holding a bow)
hold_mainhand:spear             / hold_offhand:spear             (Holding a trident)
hold_mainhand:lance             / hold_offhand:lance             (Holding a lance [since 2.6.5])
hold_mainhand:spyglass          / hold_offhand:spyglass          (Holding a spyglass)
hold_mainhand:toot_horn         / hold_offhand:toot_horn         (Holding a goat horn)
hold_mainhand:brush             / hold_offhand:brush             (Holding a brush)
Make your hold animations relatively long so you can include a weapon-equip motion at the very beginning followed by an idle holding pose.

Creating Custom Item ID and Tag Animations

Beyond the built-in categories, you can create an unlimited number of custom hand animations for specific vanilla or modded items. Use the $ symbol followed by an Item ID, or the # symbol followed by an Item Tag, right after the action prefix.

This syntax works identically across use, swing, and hold animations for both the mainhand and offhand.

// Custom Use Animations ($ for Item ID, # for Item Tag)
use_mainhand$minecraft:shield
use_offhand$minecraft:shield
use_mainhand#minecraft:dirt
use_offhand#minecraft:dirt

// Custom Swing Animations
swing$minecraft:shield
swing#minecraft:dirt

// Custom Hold Animations
hold_mainhand$minecraft:shield
hold_offhand$minecraft:shield
hold_mainhand#minecraft:dirt
hold_offhand#minecraft:dirt

Questions

Why does my character's walking animation stop when I hold or swing an item?

Hand animations in arm.animation.json have higher priority than main animations. If you accidentally added keyframes to legs or torso bones in your hand animation, they will override and freeze your walking animation. Remove any non-arm bone groups from arm.animation.json.

How do I find the exact Item ID for a modded weapon?

Press F3 + H on your keyboard while in Minecraft to turn on advanced tooltips. Hover over the item in your inventory to see its namespace and ID (for example, minecraft:shield), then attach it after a $ symbol.

How can I make a cool weapon-unsheathing animation when selecting a sword?

Whenever a player switches items, the hold animation plays from the beginning. Put your unsheathing motion in the first second of hold_mainhand:sword, and transition into the resting hold pose for the remainder of a long animation.

What happens if I don't create a specific animation for an item?

YSM will automatically fall back to your model's generic hand animations, such as use_mainhand, use_offhand, or swing_hand.

Next: Model Selection Screen Animations (gui, hover, focus) →

More in Animation

A
Armor AnimationsArmor animations allow your custom Yes Steve Model (YSM) character to visually display gear or change its appearance whenever the player equips armor. By controlling bone scaling through specific animation names, you can dynamically show or hide custom 3D armor pieces for specific items, item tags, or any equipped armor in general.
A
Arrow and projectile animationsCustomizing projectiles allows your character model to fire unique arrows, tridents, snowballs, or even modded projectiles with their own 3D geometry and animations. Starting from YSM version 2.5.0, the legacy arrow system was expanded into a universal projectile system that supports almost any thrown or shot entity in Minecraft. This guide covers how to set up projectile files in your model configuration, use animation controllers, and support older YSM versions.
A
Extra Animations in the Animation WheelExtra animations allow players to trigger custom emotes, dances, or poses on demand using the in-game animation wheel. All wheel animations must be stored in a dedicated file named extra.animation.json to be recognized by the Yes Steve Model mod.
A
First-Person Arm Animations and Mod CompatibilityYes Steve Model (YSM) lets you bring your custom character's hands to life in the default first-person view. Since version 2.5.0, you can add dedicated first-person arm animations and configure your model to work smoothly with third-party first-person camera mods. This guide covers how to register these animations, understand bone limitations, and prevent your model's head from blocking the player's view.
A
Model Selection Screen Animations (gui, hover, focus)Since version 2.2.2, Yes Steve Model supports custom preview animations inside the in-game model selection menu. You can make your character pose, react to mouse hover events, or celebrate when selected by adding specific animations to your model files. This adds a polished, interactive feel before a player even equips your model.
A
Parallel animations (blinking, ears, hair physics)Parallel animations in Yes Steve Model (YSM) allow you to run continuous background effects like blinking, ear twitches, or tail wagging alongside standard player actions. These animations loop independently of the main movement states, bringing your character to life without getting interrupted when the player walks, sprints, or attacks.