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.
- 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.
- Create a specific armor animation for the desired slot and item, and set the scale of the corresponding armor bone group back to 1.
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>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/ironDefault 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:defaultQuestions
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.