Arrow and projectile animations
Customizing 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.
Overview and Version History
YSM first introduced custom arrow models and animations in version 1.2.0, requiring file declarations in ysm.json starting from version 2.2.1. As of version 2.5.0, the old arrow system is deprecated and has been migrated to the new Projectile Animation system.
While the legacy system only allowed you to replace standard arrows, the 2.5.0+ projectile system lets you replace tridents, splash potions, snowballs, eggs, fireworks, fishing bobbers, and even projectiles added by other mods. This matters because it lets you theme your character's entire combat kit without needing extra mods.
Declaring Projectiles (YSM 2.5.0 and Newer)
To replace a projectile in YSM 2.5.0+, open your model's ysm.json file and add a projectiles object inside the files section. Each key inside the projectiles object must be the exact entity ID of the projectile you want to replace, such as minecraft:arrow or minecraft:fishing_bobber.
Inside each entity ID block, you define the paths to its model, texture, optional animation file, and even an optional animation controller. You are not limited to vanilla entities; modded entity IDs like twilightforest:seeker_arrow work the exact same way.
- Open your model's ysm.json file in a text editor.
- Locate the files object.
- Add a projectiles object inside files.
- Add the target entity ID as a key, and specify your model, texture, animation, and controller file paths.
{
"files": {
"projectiles": {
"minecraft:arrow": {
"model": "models/arrow.json",
"texture": "textures/arrow.png",
"animation": "animations/arrow.animation.json",
"controller": "controllers/arrow.controller.json"
},
"twilightforest:seeker_arrow": {
"model": "models/seeker_arrow.json",
"texture": "textures/seeker_arrow.png",
"animation": "animations/seeker_arrow.animation.json"
}
}
}
}Adding PBR Textures to Projectiles
If you play with shaders via Oculus or Iris, you can give your projectiles normal and specular maps for realistic lighting and reflections. To use PBR materials, replace the simple texture string with a texture object containing uv, normal, and specular paths.
The uv field is mandatory and points to your base color texture. The normal and specular fields are optional; if you leave both out, YSM will simply render the projectile using the standard base texture.
"minecraft:fishing_bobber": {
"model": "models/fishing_bobber.json",
"texture": {
"uv": "textures/fishing_bobber.png",
"normal": "textures/fishing_bobber_n.png",
"specular": "textures/fishing_bobber_s.png"
}
}Projectile Animation Names and Priorities
In your projectile's animation file (for example, arrow.animation.json), YSM automatically triggers specific animations based on what the projectile is doing in the world. There are four main state animations: air, ground, water, and fire.
Here is how the main animations behave and prioritize over one another:
1. air: Plays while the projectile is flying through the air. It has low priority and is overridden by other state animations.
2. ground: Plays when the projectile hits and sticks into a block. It also has low priority.
3. water: Plays when the projectile enters water. It has high priority and overrides air or ground states.
4. fire: Plays when the projectile is burning. It has high priority and overrides air or ground states.
Parallel Animations and Roaming Variables
Just like player models, projectiles support parallel animations that run independently alongside the main state animations using special animation blending. You can define parallel0 through parallel7 in your animation file, where priority increases with the number (meaning parallel7 has the highest priority over parallel0).
Parallel animations are divided into two categories: pre_parallel and parallel. Animations in pre_parallel have a lower priority than the main state animations and will be overridden by them, whereas standard parallel animations have a higher priority than main animations and will override them.
Additionally, when a projectile is fired, it automatically copies the player's current roaming variables. This is extremely useful because it allows your projectile animations or controllers to change appearance or behavior based on the player's state at the exact moment they took the shot.
Legacy Arrow Configuration (YSM 2.2.1 to 2.4.x)
If you are building a model for an older version of YSM (between 2.2.1 and 2.4.x), the projectiles field does not exist. In versions prior to 2.5.0, you must declare custom arrows using the arrow field inside the files object of ysm.json, or by using the Arrow Related Files tab in the Blockbench YSM plugin.
Just like the modern system, if you fail to declare these files in ysm.json (required since 2.2.1), your custom arrow model and animations will not show up in-game. PBR textures are also supported inside this legacy block using the exact same uv, normal, and specular format.
"files": {
"player": {
},
"arrow": {
"model": "models/arrow.json",
"animation": "animations/arrow.animation.json",
"texture": "textures/arrow.png"
}
}Questions
Why isn't my custom arrow or projectile showing up in-game?
Since version 2.2.1, custom projectiles will not load unless they are explicitly declared inside the files section of your ysm.json file. If you are on YSM 2.5.0+, make sure you are using the projectiles key with the entity ID (like minecraft:arrow) rather than the deprecated arrow key.
Can I customize tridents, snowballs, or projectiles from other mods?
Yes, starting in YSM 2.5.0. By adding the specific entity ID (such as minecraft:fishing_bobber or twilightforest:seeker_arrow) under the projectiles field in ysm.json, you can replace the model, texture, and animations of almost any vanilla or modded projectile.
Can projectile animations react to my player's custom states?
Yes. When a projectile is spawned/fired, it automatically copies the player's current roaming variables. You can read these variables inside your projectile's animation file or animation controller.
What is the difference between pre_parallel and parallel animations on a projectile?
Both run independently of main animations using special blending, but pre_parallel has a lower priority than main state animations (air, ground, water, fire) and gets overridden by them. Standard parallel animations (parallel0 to parallel7) have higher priority and override the main animations.