Animation types and triggers

Every clip Punchy! plays starts at a moment in the game: a swing, a bow being drawn, a new item in your hand, a key you press. This page lists those moments, the animation type that names each one, and how Punchy picks a clip when several rules could apply. It is for pack authors who already have a clip (see How to create custom animations) and want it to play at the right time.

Before you start

• A clip in an animation file, in a resource pack, under assets/minecraft/punchy/animations/. The file format is on Animation reference.
• A rules file next to it. Rules are written in a compat file: any .json file in assets/minecraft/punchy/compat/. How the files of several packs combine is on Compat rules.
• Punchy! Studio is optional. It writes the rules for you, and its labels are given next to the JSON names below.

After every change, reload the pack with F3+T.

Bind a clip to a moment

A rule is one entry with a type, which names the moment, and the clip names to play. You can make it in Punchy! Studio or write it by hand.

In Punchy! Studio

By hand

A complete example

This compat file gives swords a three-clip combo, a critical hit clip, an idle pose, an inspect clip and a key-driven flourish. Bows get a draw and a release. The diamond sword has its own list. Every item gets equip clips and an eating animation.

{
  "default_animations": [
    { "type": "hand_out", "name": "hand_out" },
    { "type": "hand_in", "name": "hand_in" },
    { "type": "eating", "start": "eat_start", "looping": "eat_loop", "end": "eat_end" }
  ],
  "emptyHand": {
    "customAnimation": [
      { "type": "attack", "var_1": "punch_1", "var_2": "punch_2" }
    ]
  },
  "item": {
    "SWORD": {
      "customAnimation": [
        {
          "type": "attack",
          "var_1": "sword_slash_1",
          "var_2": "sword_slash_2",
          "var_3": "sword_slash_3",
          "critical_hit": "sword_crit"
        },
        { "type": "idle", "name": "sword_idle" },
        { "type": "inspect", "name": "sword_inspect" },
        {
          "type": "triggerable",
          "id": "mypack:sword_flourish",
          "title": "Sword flourish",
          "name": "sword_flourish",
          "key": "H"
        }
      ]
    },
    "BOW": {
      "customAnimation": [
        { "type": "use_bow", "name": "bow_draw" },
        { "type": "use_bow_shot", "name": "bow_release" }
      ]
    }
  },
  "itemSpecific": {
    "minecraft:diamond_sword": {
      "customAnimation": [
        { "type": "attack", "var_1": "diamond_slash" }
      ]
    }
  }
}

What this does in game:

• An iron sword uses the SWORD list: three swings in order, a critical clip for a falling hit, an idle, the Inspect key and the flourish on H. It also gets the hand_in, hand_out and eating rules from default_animations.
• The diamond sword has its own list, so it uses only diamond_slash for attacks. It does not inherit the idle, the inspect or the flourish from SWORD. Equip and eating still come from the defaults.
• A bow draws with bow_draw and releases with bow_release.
• An empty hand attacks with punch_1 then punch_2.

The names after name, var_1 and the other clip keys are clip names from your animation files. A name that no clip has is not an error: Punchy plays the built-in clip for that moment instead, or nothing if there is none.

Two animation files go with the example, in a pack that has a pack.mcmeta as in By hand. The first is assets/minecraft/punchy/animations/my_clips.json. It holds the flourish and the put-away clip, and the poses are placeholders. The anim_speed_1 token makes a clip play at the speed you authored it; see How fast clips play.

{
  "animations": {
    "sword_flourish": {
      "animation_length": 0.8,
      "loop": false,
      "bones": {
        "right_arm": {
          "rotation": { "0.0": [0, 0, 0], "0.4": [-50, 20, 0], "0.8": [0, 0, 0] }
        }
      },
      "timeline": { "0.0": "anim_speed_1" }
    },
    "hand_out": {
      "animation_length": 0.25,
      "bones": {
        "right_arm": {
          "rotation": { "0.0": [0, 0, 0], "0.25": [-40, 0, 0] }
        }
      },
      "timeline": { "0.2": "swap_end" }
    }
  }
}

The second is assets/minecraft/punchy/animations/bow_clips.json, with the bow draw and the release. The draw is one second long and holds its last pose while you keep drawing. The release plays at the speed you authored it because of its anim_speed_1 token. use_keyframes_v2 marks the current clip layout (see V2 and legacy clips).

{
  "format_version": "1.8.0",
  "animations": {
    "bow_draw": {
      "animation_length": 1.0,
      "loop": "hold_on_last_frame",
      "bones": {
        "right_arm": {
          "rotation": { "0.0": [0, 0, 0], "0.5": [-20, 0, 10], "1.0": [-45, 0, 20] }
        }
      },
      "timeline": { "0.0": "use_keyframes_v2;" }
    },
    "bow_release": {
      "animation_length": 0.3,
      "bones": {
        "right_arm": {
          "rotation": { "0.0": [-45, 0, 20], "0.1": [-10, 0, 0], "0.3": [0, 0, 0] }
        }
      },
      "timeline": { "0.0": "use_keyframes_v2;anim_speed_1;" }
    }
  }
}

The rules also name hand_in, eat_start, eat_loop and eat_end. Punchy!‘s own pack already has clips with those names, so they play without any file of yours. The remaining clips the rules name, sword_slash_1 to sword_slash_3, sword_crit, sword_idle, sword_inspect, punch_1, punch_2 and diamond_slash, are clips you make yourself (How to create custom animations). Until a clip of that name exists, Punchy plays the built-in clip for the moment where there is one. The idle and the inspect have none, so they stay silent until you make those two clips. Nothing breaks either way, so the example loads with just the rules file and these two animation files.

Which rule wins

Punchy looks for a clip in this order and stops at the first answer.

1. The item’s own rules. An itemSpecific entry for the held item, such as minecraft:diamond_sword. If that entry has a customAnimation list, even an empty one, it is the list. The group list is not used for that item at all, and group types are not inherited, except for the walk, sprint, jump, fall and landing types (see Walking, sprinting, jumping and landing).
2. The item’s group. The item map, with a key such as SWORD. A custom group, or a group picked by name, works the same way (see below).
3. default_animations. These are added to the list above. A default is skipped when the list already has a rule with the same type and key.
4. The built-in clip name for the moment, such as attack or use_bow_right. It plays only if a loaded animation file has a clip with that name.

An item can also have a customItemAnimations list. Where Punchy uses it, it is checked before customAnimation, and the group lists and the defaults follow. The key is on Compat rules and Flags reference.

Inside one list, when several rules have the same type, Punchy keeps the ones whose filters fit the moment and sorts them from most to least specific. An items filter counts 100. Each of in_water, inside_water, block_detection, weather_detection, time_detection and biome_detection counts 1. Ties keep the order of the list. A rule can also carry variations: among the variations that fit, the highest priority wins, and a tie keeps the first. Conditions and variations are explained on Flags reference.

Groups

The item map is matched against the exact upper-case group name. SWORD works and sword is ignored. The groups are:

All 38 group names

EMPTY_HAND, AXE, PICKAXE, HOE, SWORD, SHOVEL, SHIELD, BLOCK, FULL_BLOCK, BUILDING_BLOCKS, COLORED_BLOCKS, NATURAL_BLOCKS, FUNCTIONAL_BLOCKS, CHEST, TORCH, LANTERN, FLOWER_PENDULUM, CREATURE_BUCKET, BUCKET, MINECART, BOAT, BUTTON_PLATE, TRAPDOOR, CARPET, BED, BOW, ARROW, CROSSBOW, SPYGLASS, FLINT, FOOD, SHUBBA_DUCK, MACE, SPEAR, TRIDENT, FISHING_ROD, REDSTONE, INGREDIENT.

item.EMPTY_HAND.customAnimation and emptyHand.customAnimation are the same list.

Two more ways to make a group of your own:

{
  "customGroups": [
    { "name": "my_swords", "items": ["minecraft:iron_sword", "minecraft:diamond_sword"] }
  ],
  "item": {
    "my_swords": {
      "customAnimation": [
        { "type": "attack", "var_1": "sword_slash_1" }
      ]
    },
    "related:shovel": {
      "customAnimation": [
        { "type": "attack", "var_1": "shovel_swing" }
      ]
    }
  }
}

A key in item that matches a customGroups name applies its list to every item named there. A key that starts with related: (or a group with a pattern_matching text) applies to every item whose id, path or translation key contains that text, in lower case. Longer texts are applied first, and an item that already has an itemSpecific entry is not overwritten.

Rules of the same type collapse

When an item or group list and default_animations both exist, Punchy merges them and keeps one rule per type and key. If you write two attack rules in that list, only the last one is kept. Without default_animations, every rule in the list is kept as written. Use one rule with var_1 to var_3, or variations, instead. When you really need two rules of one type, give them different key values. interaction rules are told apart by their filters and conditions as well, and triggerable rules by their key.

Clips with the same name

When two packs both have a clip named sword_slash_1, the pack that is higher in the resource pack list wins, and its whole clip is used. Bones are not mixed between the two. Choosing between packs per item is on Mix the packs.

Left and right hands

A rule names a clip once, and Punchy looks for three clips: name, name_right and name_left. If either side exists, the one for the hand that acts is used, falling back to the plain name. The built-in names work this way too, such as use_bow_right and use_bow_left. Which side is the right one follows your main arm setting.

Every type and its moment

Types are matched after lower-casing and dropping _, - and spaces, so use_bow, useBow and usebow are the same type. mining and mining_v2 are one type. The Studio column is the name in the Type list of the Bindings workspace. The last column is the clip name Punchy looks for when no rule names a clip.

Items on the Item Blacklist in Punchy’s menu keep the normal Minecraft look and never play these rules.

Equip

Attack

A pickaxe, shovel or hoe with no attack rule at all plays its mining swing instead of an attack unless the swing hits an entity or disable_mining_animation is set for it. With an attack rule, it plays the attack clip on a block too.

Mining

With one name, the clip loops while you keep mining and ends when you let go. With phases, the start clip plays when you begin, the loop repeats while you hold the key, and the end clip plays after you let go. All three clips must exist, or the phases are not used. Add stop_immediate to end the loop the moment you let go instead of at the end of the loop.

Use and interaction

Holding the use key keeps a useItem clip going until you let go. With loop set to hold_on_last_frame the clip stays on its last frame for as long as you hold the key. A goat horn plays its clip once.

Thrown items are splash and lingering potions, experience bottles, snowballs, eggs, ender pearls and eyes of ender. For them, a useItem rule can name a throw clip. Without a rule, throw_item plays.

An interaction rule can narrow itself to blocks and block states:

{
  "item": {
    "EMPTY_HAND": {
      "customAnimation": [
        {
          "type": "interaction",
          "items": ["minecraft:chest", "minecraft:barrel"],
          "animation": "open_container",
          "closeAnimation": "close_container",
          "interfaceDelay": 0.3
        }
      ]
    }
  }
}

For an interaction rule, items lists the blocks you click, not the item in your hand. blockState is an object of block properties that must match, for example { "open": "false" } on a barrel. closeAnimation plays when you close the container screen you opened. interfaceDelay waits that many seconds before the container screen opens, so the opening clip has time to play.

Eating and drinking

With phases, the start clip plays first, the loop repeats while you consume, and the end clip plays when you stop, whether you finish or let go. All three must exist. A single clip works too: use useEat or useDrink with a name. Thrown items are not eating or drinking.

Bows, crossbows and shields

Spears and tridents

A trident with Riptide plays the clip named use_trident_throw_riptide when you launch. Name your clip that, and no rule is needed.

A spear moves from stage 1 to stage 3 by the thresholds that the spear item itself defines. A spear without charge data stays on stage 1. Spear swings use the attack rule like any other weapon, with attack_spear as the built-in clip.

Movement and environment

For falling, the ground must be at least 2 blocks below, or you must be descending and have fallen at least half a block, or be moving down at 0.04 blocks per tick or faster. The clip loops until you land. Falling checks the item in your main hand first, then your off hand. See Falling tiers for min_blocks.

Walking, sprinting, jumping and landing

These types replace Punchy’s own walk motion with your clips. They work only when Resource Pack Movement (the Movement tab of Punchy’s menu, F8) is switched on, which is not the default. A clip with no animation_length, or a length of 0, is ignored.

Each type takes a name, so a rule can give one item its own walk: { "type": "walk_forward", "name": "sword_walk" }. The idle clip of this layer is punchy_moves_idle.

These types are the exception to the rule that an item’s own list hides its group’s list. Punchy looks for each one separately, in the item’s own list, then in its group’s list, then in default_animations, so an item with its own list still gets the group’s walk unless it has a walk rule of its own.

Keys

Clips Punchy plays by name

These moments have no rule type. Name a clip exactly as below, in any active animation file, and Punchy plays it. All of them are for first person.

A horse riding clip can carry the absolute_riding_pose token, which makes the arm follow the clip’s pose as written instead of the normal riding pose (see Flags reference). The clip for the empty hand in a Spatial GUI screen is spatial_gui_compat, also on that page.

Attacks and combos

Each swing plays one clip. For one swing, Punchy chooses in this order:

1. critical_hit, if the swing is a critical hit and the rule names one.
2. A Better Combat combo, if Better Combat is installed, Better Combat Support is on, and a betterCombat list applies to the item: its own, its group’s, or a melee_combo entry in default_animations.
3. The combo of the attack rule: var_1, var_2 and var_3 in that order, one per swing, then back to var_1. If all three are empty, name plays.
4. The built-in clip: attack, or attack_mace, attack_trident or attack_spear for those weapons.

Video coming soon

A swing counts as critical when the attack is charged to at least 90 percent and you are falling: not on the ground, not sprinting, not in water or lava, not on a ladder, not riding and not blinded.

The combo starts again at var_1 when you have not swung for 30 ticks (a second and a half), and when the number of clips in the combo changes. Punchy starts a new attack clip at most about 3.5 times a second, so a very fast clicker does not restart the clip on every tick. Set trigger_on_input to true on the rule to start a clip on every click instead.

With Better Combat

Add a betterCombat list to the group or item. It holds up to six clip names.

{
  "item": {
    "SWORD": {
      "betterCombat": [
        {
          "type": "melee_combo",
          "attack_1": "sword_slash_1",
          "attack_2": "sword_slash_2",
          "attack_3": "sword_slash_3",
          "attack_4": "sword_slash_2",
          "attack_5": "sword_spin_1",
          "attack_6": "sword_spin_2"
        }
      ]
    }
  }
}

With a weapon in one hand, Punchy alternates the clips that attack_1 and attack_3 name (or the whole list if neither is set). The numbers belong to the keys, not to the clip names: in Punchy!‘s own list attack_3 names the clip attack_2, so a sword swings attack_1, attack_2, attack_1. With a weapon in each hand it plays all six in order. In default_animations you can also write the same thing as an entry with the type melee_combo and the keys attack_1 to attack_6. For an item or a group, use the betterCombat list as above.

Turning block swings into attacks

With disable_mining_animation set to true on a group such as SWORD, hitting a block does not play a mining clip. The swing plays the item’s attack clips instead. Swords usually want this.

Bows, crossbows and shields

Video coming soon

Draw. The use_bow clip starts as soon as the bow starts drawing and keeps playing while you hold the use key. It loops, unless the clip has loop set to hold_on_last_frame, in which case it stays on its last frame. A bow takes one second to draw fully, so key the draw about one second long and hold the last frame. It always plays at the speed you authored.

Release. When you let go, Punchy plays the use_bow_shot clip, but only if all of these are true:

• The item has a use_bow_shot rule. Without one, nothing plays.
• The draw power is at least 0.1 on the game’s own bow scale. A bow released after only a moment does not play the shot clip.
• You have a projectile, or you are in creative mode.

If any one is missing, the draw clip blends out in a quarter of a second. The shot clip is name of the rule, or a clip named use_bow_shot.

Crossbow. The use_crossbow clip plays while you load, and finishes when the crossbow is charged. The shot clip plays when you fire a loaded crossbow. A clip named use_crossbow_shot plays without any rule.

Shield. The use_shield clip plays while the shield is raised.

{
  "item": {
    "CROSSBOW": {
      "customAnimation": [
        { "type": "use_crossbow", "name": "crossbow_load" },
        { "type": "use_crossbow_shot", "name": "crossbow_fire" }
      ]
    },
    "SHIELD": {
      "customAnimation": [
        { "type": "use_shield", "name": "shield_raise" }
      ]
    }
  }
}

Equip and put away

Video coming soon

When the item in a hand changes, for example when you pick another hotbar slot or swap hands, two clips play in a row. First hand_out plays for the item that leaves. Then the item in the hand is swapped, and hand_in plays for the new item.

Put a swap_end token on the hand_out clip’s timeline at the moment the item should change. Until the clip reaches it, the old item stays in the hand. (swap_items and swap_item mean the same.) The example animation file above does this at 0.2 seconds.

Equip clips always play at the speed you authored them, whatever the Animation Speed setting. If you scroll through the hotbar quickly, Punchy cuts the put-away short so the new item comes up right away.

An action that starts during an equip, such as a swing or a draw, cuts the equip short. A rule can set skip_hand_equip to true to skip the hand_out and hand_in swap clips after its action.

Equip rules read well in default_animations, because the same two clips can serve every item:

{
  "default_animations": [
    { "type": "hand_out", "name": "hand_out" },
    { "type": "hand_in", "name": "hand_in" }
  ],
  "item": {
    "SPEAR": {
      "customAnimation": [
        { "type": "hand_in", "name": "hand_in_spear" }
      ]
    }
  }
}

Idle

An idle rule gives an item a pose or a loop that runs in the background. Punchy plays it on the arm of the item in your main hand. When the main hand is empty or its item has no idle, the item in your off hand can play its idle on the off arm instead. An idle plays only when nothing else is going on: no action clip, no swimming, no walking on water, no mining and no use. When an action ends, the idle blends back in over about a quarter of a second. It stops again the moment an action begins.

Set loop to true in the clip so the idle keeps running for as long as you hold the item.

Punchy looks for an idle rule in the item’s own list and group first, and in default_animations only if there is none. The rule can keep some of Punchy’s own movement under the clip. This one is for a single item, so it sits in itemSpecific (shears are not one of the groups):

{
  "itemSpecific": {
    "minecraft:shears": {
      "customAnimation": [
        {
          "type": "idle",
          "name": "shears_idle",
          "customFlags": { "movement_influence": 50 }
        }
      ]
    }
  }
}

customFlags.movement_influence is a whole number from 0 to 100, and 100 when you leave it out. At 100 the walk and sprint motion of the active hand is kept in full. At 0 it is switched off while the clip plays. Values in between keep that percentage.

Falling tiers

Several falling rules can share an item, each with its own min_blocks. Punchy measures the height the player is going to fall, which is the distance already fallen plus the distance to the ground below, and uses the rule with the highest min_blocks that is not above that height. A rule with no min_blocks counts as 0.

{
  "default_animations": [
    { "type": "falling", "key": "short", "name": "fall_short" },
    { "type": "falling", "key": "long", "name": "fall_long", "min_blocks": 10 }
  ]
}

The key is only a label here. It keeps the two rules apart: when lists are merged with default_animations, Punchy keeps one rule per type and key, so tiers with the same key would collapse into one (see Rules of the same type collapse). When no tier fits, a clip named falling plays if one exists. A new tier restarts the clip, so a long fall passes through the lower tiers first.

Key-driven animations

Inspect

The Inspect key is in the Punchy! group of Minecraft’s key list: open Options, then Controls, then Key Binds. When you press it with no screen open, Punchy plays the inspect rule of the item in your main hand, or of your off hand if the main hand has none. With no rule, a clip named inspect plays.

Triggerable animations

A triggerable rule plays a clip when the player presses a key, and adds an entry to Key Binds.

{
  "type": "triggerable",
  "id": "mypack:sword_flourish",
  "title": "Sword flourish",
  "name": "sword_flourish",
  "key": "H"
}

Video coming soon

In Punchy! Studio, pick Custom Key as the Type of a new rule. The Trigger panel then shows the Key field, Binding Id (the id) and Title in Controls (the title). The Key field takes the key names in the table below.

How it behaves:

• The clip plays once for each press. It does not loop.
• Keys are ignored while a screen is open.
• Punchy looks at the rules of the item in your main hand and of the item in your off hand. A press fires the first rule whose key was pressed.
• id is the binding’s name. It is lower-cased, : becomes _, and any character other than a letter, a digit, . or - becomes _, so a / becomes _ as well. Without an id, Punchy uses name, then animation, then key.
• All rules with the same id share one Key Binds entry, even on different items. Give every rule that shares an id the same title and key. If they differ, Punchy picks one of them and you cannot tell which. That is how one flourish can be on every sword with a single key.
• The title in Key Binds is title, then name, then animation, then the id, then “Triggerable animation”.
• The key you write is only the default. When a player changes it in Key Binds, their choice wins. Punchy stores it in config/punchy/triggerable-keybindings.json in the game folder. That file belongs to the player: do not ship it with the pack.
• Pick a key that no other entry uses. Punchy!‘s own pack already puts two sword inspect clips on G and J, and Key Binds does not warn you when two of these entries share a key.

Key names are not case sensitive. Spaces, - and _ are ignored, and a KEY.KEYBOARD. or KEY.KEYPAD. prefix is dropped.

Rule keys that pick the clip and the moment

The rest of the flags are on Flags reference.

How fast clips play

Punchy plays most clips at its Animation Speed setting (General tab of Punchy’s menu), 5.5 times faster than authored by default. The speed depends on the clip’s name, and for a few actions on the action itself:

• Clips named use_bow, use_shield, use_crossbow, use_crossbow_shot, use_trident, use_trident_throw, use_trident_throw_loyalty, use_trident_throw_riptide, attack_mace, swiming, swiming_above and dry_out play at the speed you authored. So do the equip clips: hand_in, hand_out and names that start with hand_in_ or hand_out_.
• use_eat, use_drink and falling_in_water play at the authored speed too.
• Some actions keep the authored speed whatever their clips are named: equip and put away, eating and drinking, the bow draw, the crossbow load and shot, the spear charge, and the put_out_fire clip. Your own crossbow_load or eat_loop clip plays as you authored it.
• A clip named interact plays at 5.4 times the authored speed, whatever the setting.
• Every other clip plays at the Animation Speed setting.

A clip that has an anim_speed_<number> token in its timeline, such as anim_speed_1, plays at that speed from the token onward and ignores the setting. The number is from 0.5 to 5.5. Studio writes the token for you when you pick a fixed speed.

Things that stop a rule working

• A mistake in the compat file drops the whole file. One wrong value type, or a comma after the last entry of an object, and Punchy reads none of it and writes nothing to the log. Check the JSON before you test. Studio’s lint reports this.
• item keys are upper case. SWORD works. sword is ignored.
• An item’s own list replaces its group’s list. Copy the types you still want into the item’s list. The walk, sprint, jump, fall and landing types are the exception: they are still taken from the group when the item’s list has no rule of that type.
• Two rules of one type and key become one when the list is merged with default_animations. Only the last stays. Give them different key values to keep both.
• A wrong clip name is not reported. Punchy plays the built-in clip of the moment instead. Check the spelling, and that the clip is in an active pack. Clip names are case sensitive.
• Phased types need three clips. mining, eating, drinking and walk_on_water_v2 with start, looping and end are used only when all three exist.
• A bow release needs a use_bow_shot rule. The draw alone does not play a release.
• An idle plays only when nothing else does, and for the item in your main hand. The off hand’s item plays its idle only when the main hand is empty or its item has no idle. Set loop to true so it keeps moving.
• A triggerable without a key has no Key Binds entry, so the player cannot press it. A key name that is not in the table gives no default key.
• Walk, sprint, jump and landing types are off by default. Turn Resource Pack Movement on in the Movement tab of Punchy’s menu.
• A blacklisted item never animates. Check the Item Blacklist tab in Punchy’s menu.
• A clip plays at the wrong speed. Look at How fast clips play: your clip’s name may not be one of the built-in names.
• You did not reload. Press F3+T after every edit to the pack.

Related pages

• How to create custom animations: make the clip.
• Animation reference: the clip file format, loop modes, timeline tokens and sounds.
• Compat rules: how files from several packs combine.
• Flags reference: every flag and token, plus conditions and variations.
• Mix the packs: choose between the clips of several packs.
• Punchy! Studio: the Bindings workspace in full.
• Settings and controls: Animation Speed, the Item Blacklist and the keys.
• Tuning editor and debug position: move an item or arm into place with the Hand Editor.
• Troubleshooting: when nothing plays.