Guide · Animation

Armor Animations

Armor 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.

Where to Place Armor Animations

Armor animations do not require a dedicated animation file and can be placed directly inside your main.animation.json file. The mod will automatically detect and trigger these animations whenever the player equips a matching piece of armor in the corresponding equipment slot.

This setup keeps your project simple because you do not need to register extra animation files just to handle basic equipment visuals.

How to Show and Hide Custom Armor

To make custom 3D armor appear only when equipped, you must hide the armor bones by default and scale them back up inside the specific armor animation. Since all geometry in your model is visible unless told otherwise, managing bone scale is the standard way to toggle armor visibility.

  1. In a parallel animation (an animation that runs continuously in the background), set the scale of all your custom armor bone groups to 0 so they are hidden by default.
  2. Create a specific armor animation for the desired slot and item, and set the scale of the corresponding armor bone group back to 1.
Make sure your armor bones are cleanly grouped by slot (helmet, chestplate, leggings, boots) in Blockbench so you only need to scale a single parent bone per slot.

Armor Slot Prefixes and Naming Rules

Armor animations follow the exact same naming pattern as hand item animations, starting with a slot prefix followed by an item ID or item tag. Vanilla Minecraft divides armor into four equipment slots, and every armor animation must begin with one of these four prefixes: head, chest, legs, or feet.

After the slot prefix, use $ to target a specific item ID, or # to target an item tag. You can create an unlimited number of custom armor animations in your model to cover as many vanilla or modded armor pieces as you want.

<slot>$<namespace>:<item_id>
<slot>#<namespace>:<tag_name>
Pay special attention to the leggings slot prefix: it must be plural (legs), not singular.

Targeting Specific Items and Tags

In the examples above, head$minecraft:iron_helmet plays when a vanilla Iron Helmet is worn in the head slot, and chest$minecraft:diamond_chestplate plays when a Diamond Chestplate is worn in the chest slot. Meanwhile, legs#forge:armor/diamond triggers for any leggings with the forge:armor/diamond tag, and feet#forge:armor/iron triggers for any boots with the forge:armor/iron tag.

head$minecraft:iron_helmet
chest$minecraft:diamond_chestplate
legs#forge:armor/diamond
feet#forge:armor/iron

Default Fallback Armor Animations

You can define a fallback animation for each slot using the :default suffix, which plays whenever the player wears any armor that does not have a specific animation. This animation has the lowest priority, meaning specific item ID ($) or tag (#) animations will always override it if they match what the player is wearing.

The :default rule works for all four armor slots. It is ideal for giving your character a generic visual indicator or a standard armor set appearance without having to make separate models for every armor tier in the game.

head:default
chest:default
legs:default
feet:default

Questions

Why is my custom armor visible even when the player is not wearing any armor?

All model geometry is visible at scale 1 by default. You must set the scale of your armor bone groups to 0 inside a parallel animation first, and then scale them back to 1 inside the specific armor animation.

Why is my leggings animation not playing?

Check the spelling of your slot prefix. The prefix for the leggings slot must be plural (legs), such as legs$minecraft:iron_leggings or legs:default.

What happens if an equipped helmet matches both head$minecraft:iron_helmet and head:default?

The specific animation (head$minecraft:iron_helmet) will play because head:default has the lowest priority and only acts as a fallback when no specific match is found.

Which file should I save my armor animations in?

Armor animations do not have a mandatory separate file; you can place them directly inside your main.animation.json file.

Next: Arrow and projectile animations →

More in Animation

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
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.
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.