Animated Items

Fabric 1.20.1 · 1.20.4 · 1.21.1 · 1.21.4 · 1.21.5 · 1.21.8 · 1.21.11 · 26.2 NeoForge 1.20.1 · 1.20.4 · 1.21.1 · 1.21.4 · 1.21.5 · 1.21.8 · 1.21.11 · 26.2 Forge 1.20.1 · 1.20.4

Requires GeckoLib (and Fabric API on Fabric). Client side only.

Turn any item into a 3D animated model with nothing but a resource pack.

Animated Items swaps items with a matching custom_model_data for GeckoLib models made in Blockbench, with first person animations, your own skin on the arms and a camera that moves with the animation.

Nothing is needed on the server, and players without the mod just see the normal item. The same resource pack works on every version, from 1.20.1 to 26.2.

Features

• Automatic animations: idle, walk, run, sneak, jump, fall, swim, crawl, climb, glide, riptide, sleep and hurt, picked from what you're doing
• Keybind actions: play animations with any key or mouse button, with cooldowns, held (looping) actions and random animations
• Combos: chain attacks with next (attack1 → attack2 → attack3)
• Your skin on the arms: right_arm / left_arm bones are drawn with your own skin in first person
• Animated camera: a camera bone moves your view on top of where you're looking
• Sounds and commands: play a sound when an action starts, run commands when it starts or ends
• Cancel vanilla keys: block the vanilla attack, use or drop while an action plays
• Hide the other hand: visible_offhand hides the off hand, its item and its arm pose, great for two handed weapons
• Per view visibility: show an animation only in first person, only in the hotbar, or both (also for animations played by command)
• Models on command: put any model of your pack on your hand with /animated_items model set <model>, whatever you're holding

Getting started

The first time you start the game, AnimatedItemsExample.zip shows up in your resourcepacks folder (it's not turned on). Turn it on and run /animated_items model set punch_global, then open the zip to see how a pack is made.

Making an animated item

Pack layout:

assets/minecraft/
  animated_items/death_scythe.json          the item config
  geo/death_scythe.geo.json                 Blockbench GeckoLib model
  animations/death_scythe.animation.json    Blockbench GeckoLib animations
  textures/animated_items/death_scythe.png  texture

animated_items/death_scythe.json:

{
  "item": "netherite_sword",
  "custom_model_data": 66,
  "model": "geo/death_scythe.geo.json",
  "texture": "animated_items/death_scythe",
  "animations": "animations/death_scythe.animation.json",
  "item_hotbar_model": false,
  "visible_offhand": false,
  "actions": [
    {
      "id": "attack1",
      "keybind": "key.attack",
      "animation": "attack1",
      "next": "attack2",
      "chain_window_ticks": 5,
      "sound": "item.trident.throw;vol:60;pitch:1.2"
    },
    {
      "id": "attack2",
      "keybind": "key.attack",
      "animation": "attack2",
      "cooldown_ticks": 20
    },
    {
      "id": "inspect",
      "keybind": "key.keyboard.g",
      "animation": "inspect",
      "held": true,
      "cancel_keybind": true,
      "visible_thirdperson": false
    },
    {
      "id": "special",
      "keybind": "key.keyboard.r",
      "random_animation": "spin, slam",
      "cooldown_ticks": 100,
      "command_onstart": "effect give @s speed 3 1",
      "command_onfinish": "particle minecraft:explosion ~ ~1 ~"
    }
  ]
}

Item options

Action options

Name your animations idle, walk, run, sneak, jump... and they play by themselves.

Get the item in game:

1.20.1 - 1.20.4:  /give @s netherite_sword{CustomModelData:66}
1.21.1:           /give @s netherite_sword[custom_model_data=66]
1.21.4 and up:    /give @s netherite_sword[custom_model_data={floats:[66]}]

Commands

• /animated_items model set <model>: put any model of your pack on your hand with its actions, whatever you hold (autocompletes every model)
• /animated_items model remove <model>: take it off
• /animated_items trigger <model|item> <animation>: play an animation on that model or on the item you're holding

Servers

With the AnimatedItemsPlugin (Paper/Spigot), servers can play animations for players with selectors and tags, like @a[tag=boss] or tag:vip.

API for other mods

AnimatedItemsApi.setStandaloneModel("punch_global");
AnimatedItemsApi.playOnStandaloneModel("punch_global", "attack1");
AnimatedItemsApi.clearStandaloneModel();

AnimatedItemsApi.playOnHeldItem("minecraft:netherite_sword", "attack1");
AnimatedItemsApi.isAnimated(stack);
AnimatedItemsApi.modelOf(stack);
AnimatedItemsApi.animations("death_scythe");
AnimatedItemsApi.currentAnimation();
AnimatedItemsApi.stopAnimation();

AnimatedItemsEvents.onAction((model, action, animation) -> ...);
AnimatedItemsEvents.onFinished((model, action, animation) -> ...);
AnimatedItemsEvents.onReload(() -> ...);

• Models: setStandaloneModel puts any model of the loaded packs on the player's hand with its actions, the same as /animated_items model set; models() lists every model and activeStandaloneModel() tells which one is on
• Playing animations: playOnHeldItem and playOnStandaloneModel work like /animated_items trigger, and keep the visibility settings of the action that uses that animation
• Reading items: isAnimated, modelOf and animations tell if a stack has an animated model, which one, and what animations it has
• Events: onAction / onFinished when an animation starts or ends (from a key, a command or the API), and onReload when the packs are loaded again
• Same everywhere: com.cotii.animateditems.api is identical on Fabric, Forge and NeoForge, from 1.20.1 to 26.2