How to create custom animations

This page takes you from nothing to your own clip playing in your hand in game. You will make a short sword swing: a clip that moves the right arm, and a rule that plays it when you attack with an iron sword. It is for anyone who wants to add or replace a first person animation, with or without experience in animation tools.

Choose the tool you work in. Every path ends in the same thing: a resource pack with a clip file and a rule file that Punchy! reads. Punchy! Studio writes both for you. Blockbench and Blender write the clip file, and you write the pack file and the rule by hand in Put the clip in a pack.

Before you start

Install Punchy! 3.0 or newer from Modrinth or CurseForge. The Punchy! Studio steps were checked against Punchy! Studio 1.1.1 with Punchy! 3.0, and the file formats and keys against Punchy! 3.0, all for Fabric on Minecraft 26.3.
Join a world to test in. A creative flat world is the easiest: you can give yourself an iron sword with /give @s iron_sword.
The Studio path needs Punchy! Studio installed, from Modrinth or CurseForge. The Blockbench path needs Blockbench (its menu and panel names on this page are from 5.2.2). The Blender path needs Blender (its menu and panel names are from 5.2) and the Punchy Blender add-on, which the Blender tab shows how to get.
Resource packs live in the resourcepacks folder of your game folder. Resource packs explains how to turn one on.

How a clip reaches your hand

Three things have to exist, and every path below makes them:

Part	Where it goes in the pack	What it does
The clip	`assets/minecraft/punchy/animations/<any name>.json`	Holds the animation: which bones move, when, and by how much. One file can hold many clips.
The rule	`assets/minecraft/punchy/compat/<any name>.json`	Says which item and which action plays the clip. This is the compat file.
The pack	`pack.mcmeta` at the pack’s root	Makes Minecraft list your folder as a resource pack.

Punchy! reads every .json file under those two folders in every active pack. The clips are looked up by name, so a name is all a rule needs.

To replace a clip, give yours the same name as the clip you want to replace. A clip with the same name in a pack higher in the list replaces the whole clip: Punchy! does not merge bones from two packs.

Make the clip

Tool

Punchy! Studio

Blockbench

In Punchy! Studio

Punchy! Studio is the shortest path. You pose the arm on a timeline, try the clip in your own hand while you work, and Studio writes the clip, the rule and the pack for you.

The keys below are those of the Punchy Studio keymap, the default. The first time you open the editor, a window asks which keys you know: press Keep Punchy Studio Keys to follow along. Pick a keymap explains the other three.

Start the clip

Join a world and hold a sword.
Switch to first person.
Press F6 to open the editor.
If the editor opens in the Third Person perspective, pick First Person with the switch between the menus and the workspace tabs.
Choose File > New Animation… (Ctrl+N).
Type my_sword_swing in Name.
Set Length to 0.6.
Untick Set up bindings next, because you will bind the clip in a later step. Leave Loop off.
Press Create.

The New Animation window: a name, a length, and Create.

The rig viewport on the left shows the first person rig with your skin and sword. The camera viewport on the right is the real game camera, with Punchy! drawing your unsaved clip.

Key the swing in Punchy! Studio

In the Outliner, select Right Arm.
Press E for the rotate tool.
With the playhead at the start, press I to insert a key.
Press Right ten times to move ten frames on.
Click the Rotation X field of the Transform panel, type -60 and press Enter. The arm turns, and Studio keys the new value at the playhead. Dragging the gizmo’s ring keys it the same way.
Press Shift+Right to jump to the end.
Type 0 in Rotation X and press Enter to bring the arm back.
Press Space to play.

Keying the right arm at the start, partway and at the end, then playing the swing.

The Speed row of the Animation panel says how fast Punchy! plays the clip. New clips play at a Fixed 1x. The In game line under Playback says how long the clip really lasts in game.

Bind it to sword attacks

Press Ctrl+B, or click the Bindings tab, to open the Bindings workspace.
Press Ctrl+N (New Rule for This Clip).
Keep Target on Held Item to bind the sword in your hand. Or pick Punchy Group and type SWORD in Group, Item or Tag to bind every sword.
Set Type to Attack.
Press Add Rule. The rule opens in the properties column: its Trigger, the Clips it plays, its Item Filter, Conditions and more.
Press Ctrl+Enter (Apply) to keep the draft and go back to the Animation workspace.

A new rule for this clip: the held sword, the Attack type, then Apply.

The right column of the Bindings workspace (Effective) shows, for the test item and each trigger, which rule Punchy! would really use and why.

Try it in your hand

In the right column of the Animation workspace, switch from Properties to Test.
In This Clip, set Plays As to Attack. This is the trigger whose speed and blends the clip gets.
Keep Hand on Main Hand.
Press Play in Game.

Punchy! plays your unsaved clip at its real rate in the camera viewport, and the status bar says how it plays.

The Test tab: Plays As Attack, then Play in Game.

Save and export

Press Ctrl+S to save. This writes an editable copy to punchy-studio/my_sword_swing.ps.json and never changes a resource pack.
Press Ctrl+E to open Export to Resource Pack.
Type a new folder name such as My sword animations in the field at the bottom, or pick an editor pack you made before from the list.
Keep Activate the pack and play it now ticked.
Press Export. The window lists the files it writes, with its Checks and Rules Check, before you press the button.
Wait for the game to reload. Studio turns the pack on, closes the editor and plays your clip once in your hand, and the chat says Testing my_sword_swing.
To see it again, swing the sword. Your clip is the first swing of the combo, and the second and third swings keep the clips they had. After about 1.5 seconds without a swing, the combo starts again with yours.

Export again whenever you change something. Studio remembers the pack. The pack is in resourcepacks/My sword animations, with the clip in assets/minecraft/punchy/animations/punchy_studio_<id>.animation.json and its rules in assets/minecraft/punchy/compat/punchy_studio.json. The hand-written rule further down this page does the same job, so you can read what Studio wrote.

Keep working on a pack you already have

Studio can also continue from a pack that is already in your game folder, including a pack you made with Blockbench.

Press F6 to open the editor.
Click the Library tab in the top bar. In the Animation workspace, Ctrl+O opens it too.
Press Build from Pack… (it is also in the Library’s File menu) and pick the pack you want to continue from.
Keep or change the name in New pack.
Press Build.

Library > Build from Pack: every clip the pack plays comes into a new pack, with its rules and sounds.

Every clip Punchy! plays from the old pack becomes an animation of the new pack, with its rules and sounds. The old pack stays as it is. Open a clip from the Library to edit, bind, test and export it again. The Studio page covers the Library, Clip > Check for Problems and everything else in the editor.

In Blockbench

Blockbench works on the same Bedrock geometry that Punchy! draws your arms with. You key the arm on Blockbench’s timeline, export a Bedrock animation file, and then write the rule and the pack by hand in the next section.

Open the first person rig

Open your Punchy! jar from the mods folder with a zip tool.
Copy assets/punchy/geo/player.geo.json out of it into a work folder. Leave the jar itself as it is.
In Blockbench, choose File > Open Model and pick player.geo.json. It opens as a Bedrock entity model.
Switch to the Animate tab.

Video coming soon

Getting the rig from your own Punchy! jar.

The rig has these bones: camera_animation holds camera, and camera holds body. Under body are right_arm and left_arm, torso, head and both legs. Each arm holds an item_ bone, which holds an itemgrip_ bone, which holds the item’s base_ and top_ bones. The geometry file names no texture, which does not matter for animating. The player rig page describes every bone.

In this guide you key right_arm. The clips that come with Punchy! key five of these bones: camera, right_arm, left_arm, itemgrip_right and itemgrip_left. Punchy! can pose nine bones in all: camera_animation, camera, body, right_arm, left_arm, item_right, item_left, itemgrip_right and itemgrip_left. The player rig page says what each one does. The arms start in the pose the rig is saved in. In a clip with use_keyframes_v2 (you add that token below), a key of [0, 0, 0] means that rest pose.

Add the animation

In the Animations panel, press Add Animation.
Type my_sword_swing in Name.
Keep Loop Mode on Play Once.
Press Confirm.
Click the Animation Length slider in the toolbar of the Animations panel.
Type 0.6 and press Enter.

Hold On Last Frame and Loop are the other two modes. Punchy! repeats a clip when its loop key is true.

Key the swing in Blockbench

In the Outliner, open camera_animation, camera and body.
Select right_arm.
In the Timeline panel, click the ruler at 0.
Press the + beside Rotation to key the start pose.
Click the ruler near 0.2.
Press the + beside Rotation again.
Select that key.
Click the Timecode slider in the Keyframe panel.
Type 0.2 and press Enter.
Type 40, 0 and 10 in the X, Y and Z fields of the Keyframe panel.
Add a key at 0.35 the same way, with -35, 0 and -10.
Add a key at 0.6 with 0, 0 and 0. This returns the arm to its rest pose.
Press the play button in the Timeline panel to watch it.

Video coming soon

Keying the right arm in the Timeline panel.

Blockbench also keys the bone for you when you move it with the rotate tool while the playhead is on a time. With the Auto Keyframe setting on (the default), it adds a keyframe with default values at the start of the timeline the first time you transform a bone at a later time. Typing the numbers in the Keyframe panel gives the same result and is easier to repeat.

Set the speed and the layout

Punchy! plays most clips faster than they were authored, at the player’s Animation Speed setting (5.5 times by default). A clip says its own speed with a token. The same token line also tells Punchy! how to read your rotations. Blockbench keeps these tokens in the Instructions channel.

Choose Animation > Animate Effects. An Effects row with Particle, Sound and Instructions appears in the Timeline panel.
At time 0, press the + beside Instructions.
In the Script field of the Keyframe panel, type anim_speed_1;dual_handed;use_keyframes_v2;.

Video coming soon

The Instructions channel holds Punchy!'s timeline tokens.

Here is what each token does:

anim_speed_1 plays the clip at its real length, so your 0.6 second swing lasts 0.6 seconds.
use_keyframes_v2 makes Punchy! add your rotations to the rig’s rest pose, which is how Blockbench shows them.
dual_handed makes both arms follow the clip. Without it the clip moves only the arm of the hand that started the action. Studio writes it into every new clip.

Export the clip in Blockbench

Choose Animation > Export Animations….
In Select Animations to Export, keep my_sword_swing ticked (every animation starts ticked) and untick any others.
Press Confirm.
Save the file as my_sword_swing.animation.json in resourcepacks/My swing pack/assets/minecraft/punchy/animations/. Make the folders in the save window if they do not exist yet.

Video coming soon

Export Animations writes a Bedrock animation file.

The file has this shape (a trimmed example: Blockbench may write more keys, and it may format the numbers a little differently):

{
  "format_version": "1.8.0",
  "animations": {
    "my_sword_swing": {
      "animation_length": 0.6,
      "bones": {
        "right_arm": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.2": [-40, 0, 10],
            "0.35": [35, 0, -10],
            "0.6": [0, 0, 0]
          }
        }
      },
      "timeline": {
        "0.0": "anim_speed_1;dual_handed;use_keyframes_v2;"
      }
    }
  }
}

Blockbench mirrors the X and Y rotations when it exports a Bedrock animation, and the X of a position. The Z rotation is kept as typed. In this example the 40 you typed is -40 in the file, and -35 is 35. That is expected, and Punchy! reads the file as written. Work in Blockbench and export again after a change. Do not copy numbers into a file you exported by hand, because the mirroring is easy to get wrong. The block above is a complete clip file, though: if you only want to try the pack, save it as my_sword_swing.animation.json in the same folder and skip the Blockbench steps.

Now go to Put the clip in a pack to write the pack and the rule.

In Blender

The Punchy Blender add-on, made by one of the Punchy Guys Studios creators, turns an action in Blender into a Punchy! first person clip file. It writes that clip file, plus a small note file described below, and it writes no pack file or rule, so you write the pack file and the rule by hand in the next section. This tab keys the same 0.6 second swing as the other two.

Get the add-on and open its rig

The add-on is not something you install in Blender’s Preferences. It is a script inside PunchyBlender.blend, a Blender file that also holds the first person rig. The script runs when you let Blender run the file’s scripts.

Open the Punchy Blender page on GitHub and choose Code > Download ZIP.
Unzip it into a folder you can write to. Keep PunchyBlender.blend, Scripts and images together.
In Blender, choose File > Open and pick PunchyBlender.blend.
Blender says that automatic execution of Python scripts in this file was disabled, and names the text PunchyRig_ui.py. Press Allow Execution. The same script is in the download’s Scripts folder if you want to read it first.
In the Outliner, click Arm_PlayerModel. This is the rig.
Move the pointer over the 3D viewport and press N.
Open the Punchy Exporer tab. The add-on spells it that way. Its Animation System panel has Import JSON and Export JSON.

Blender 5.2.0 also shows a note that the file was written by a newer Blender binary. That is normal.

Opening PunchyBlender.blend, allowing its script, selecting Arm_PlayerModel and opening the Punchy Exporer tab.

Key the swing in Blender

The add-on turns frames into seconds with the scene’s frame rate. The scene in PunchyBlender.blend runs at 60 frames per second, so 0.2, 0.35 and 0.6 seconds are frames 12, 21 and 36. Keep that frame rate.

With the rig selected, switch the 3D viewport from Object Mode to Pose Mode in its header.
Click the right arm bone in the viewport. Its name, right_arm, shows in the Properties editor.
If the Action Editor at the bottom already shows an action such as attack, press the X beside its name to unlink it from the rig.
Press New, click the new action’s name, type my_sword_swing and press Enter. The add-on names the clip after the action.
In the Properties editor, open the Bone tab. Under Transform, check that the rotation Mode is XYZ Euler.
With the playhead on frame 0, hold the pointer over the Rotation X field and press I to key it.
Click the ruler of the Action Editor at frame 12. Type 40 in Rotation X, press Enter, then hold the pointer over the field and press I.
Go to frame 21 and do the same with -55.
Go to frame 36. With the pointer over the viewport, press Alt+R to clear the rotation, then hold the pointer over Rotation X and press I.
With the pointer over the viewport, press Space to play the swing, and again to stop it.

Frame	Time	Rotation X	What it is
0	0 s	`0`	The start.
12	0.2 s	`40`	The windup.
21	0.35 s	`-55`	The chop.
36	0.6 s	`0`	Back to rest.

In this rig a positive Rotation X on right_arm raises the arm toward the camera, and a negative one swings it forward and down.

Pose Mode on right_arm, a new action named my_sword_swing, Rotation X keys at frames 0, 12, 21 and 36, then playing the windup and the chop.

Add the two markers

Markers on the action carry what keys cannot: the timeline tokens and the loop mode. The exporter reads the text of each marker.

In the Action Editor, open the Marker menu and make sure Show Pose Markers is ticked, so the markers belong to the action.
Put the playhead on frame 0 and press M in the Action Editor. Move the pointer to the marker row at the bottom, press F2, type T:"anim_speed_1;" and press Enter.
Put the playhead on frame 36, add a marker the same way and name it L:"play_once".

The two markers on the action: the timeline marker at frame 0 and the loop marker at frame 36.

T:"anim_speed_1;" writes "timeline": {"0.0": "anim_speed_1;"}. anim_speed_1 plays the clip at its keyed speed, so the swing lasts 0.6 seconds in game. Without it a clip like this plays at the player’s Animation Speed setting, 5.5 times faster by default.
L:"play_once" writes "loop": "play_once", and Punchy! plays the clip once. The add-on writes that for a clip with no L: marker too. Use L:"true" to repeat the clip or L:"hold_on_last_frame" to stay on the last frame.
Do not add dual_handed to this clip. It makes the clip control both arms, and this swing keys only the right one, so the left arm would sit at rest in the lower left of the screen. Do not copy the dual_handed;anim_speed_1; example from the add-on’s README for this clip.
Never add use_keyframes_v2 to a Blender clip. The add-on writes the older key layout, and Punchy! plays it as Blender shows it. With the token added, a turn about the arm’s Y or Z axis plays 9 to 11 degrees off.

Export the clip from Blender

With Arm_PlayerModel selected, press Export JSON in the Animation System panel.
In the file browser, go to resourcepacks/My swing pack/assets/minecraft/punchy/animations/ in your game folder. Make the folders if they do not exist yet.
Type my_sword_swing.animation.json in the file name field at the bottom.
In the options on the right, make sure my_sword_swing is ticked under Select Actions to Export:, and untick any other action. Leave Export Action Timeline MetaData and Optimized Export (Simplify Curves) off.
Press Export Blockbench JSON. The status bar says Punchy JSON Exported Successfully!

Export JSON, the pack's animations folder, my_sword_swing ticked, Export Blockbench JSON and the success message.

The export also writes a small exportMeta.json next to your .blend, so keep the .blend in a folder you can write to. Punchy! never reads it.

The file has this shape. The add-on writes the rotation as a key on every frame, 37 in all for this clip, and keeps only the first and last key of a position or scale that does not change. This trimmed example shows only the four rotation keys you made:

{
  "format_version": "1.8.0",
  "animations": {
    "my_sword_swing": {
      "loop": "play_once",
      "animation_length": 0.6,
      "bones": {
        "right_arm": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.2": [-40, 0, 0],
            "0.35": [55, 0, 0],
            "0.6": [0, 0, 0]
          },
          "position": {
            "0.0": [0, 0, 0],
            "0.6": [0, 0, 0]
          },
          "scale": {
            "0.0": [1, 1, 1],
            "0.6": [1, 1, 1]
          }
        }
      },
      "timeline": {
        "0.0": "anim_speed_1;"
      },
      "hyp_metadata": {
        "fps": 60.0
      }
    }
  }
}

The add-on writes a rotation as [-X, Z, Y] of the Blender values, so the 40 you keyed is -40 in the file and -55 is 55. That is expected, and Punchy! reads the file as written. hyp_metadata is the add-on’s own note, and Punchy! ignores it. Work in Blender and export again after a change instead of editing numbers in the file.

Now go to Put the clip in a pack to write the pack and the rule. The rule plays your clip as var_1 of the iron sword’s attack. Once the pack is on, the swing plays like this:

Three attacks play my_sword_swing in first person, with only the right arm on screen.

Put the clip in a pack

Studio did this for you. For Blockbench and Blender the clip file is already exported, so you write the pack file and the rule by hand. Create this folder layout in your resourcepacks folder, with the clip you exported in place:

My swing pack/
  pack.mcmeta
  assets/minecraft/punchy/animations/my_sword_swing.animation.json
  assets/minecraft/punchy/compat/my_sword_swing.json

The pack file

pack.mcmeta for Minecraft 26.3:

{
  "pack": {
    "description": "My sword swing",
    "pack_format": 97,
    "min_format": 97,
    "max_format": 97
  }
}

For another Minecraft version, use the format numbers of that version. Studio writes the right pack.mcmeta for your game when it exports.

The rule

The rule goes in assets/minecraft/punchy/compat/my_sword_swing.json. It plays your clip when you attack with an iron sword:

{
  "itemSpecific": {
    "minecraft:iron_sword": {
      "customAnimation": [
        {
          "type": "attack",
          "var_1": "my_sword_swing",
          "var_2": "attack_2",
          "var_3": "attack_3",
          "critical_hit": "attack_critical"
        },
        {
          "type": "mining_v2",
          "start": "new_mining_st_start",
          "looping": "new_mining_st_loop",
          "end": "new_mining_st_end"
        }
      ]
    }
  }
}

Read it from the inside out:

type says which action the entry is for. attack is a melee swing.
var_1 to var_3 are the clips of the swing combo. Punchy! plays them in that order and starts again after the last. Your clip is the first swing. attack_2 and attack_3 are clips of the built-in pack, so swings two and three stay as they were.
critical_hit is the clip for a critical swing. Punchy! picks it when the swing starts and you are falling with the attack charged, and you are not sprinting, riding, blind, climbing or in water or lava.
The mining_v2 entry copies the built-in sword’s mining entry, with a clip for the start, the loop and the end, so your list has the same types. Swords have disable_mining_animation set, so a swing at a block plays the attack clips, yours included, and the mining clips are not played for a sword.
minecraft:iron_sword is the item. The key is an item id in lower case.

Try it in game

Start the game.
Open Options, then Resource Packs.
Move My swing pack to the right-hand list.
Press Done.
Already in a world? Press F3+T to reload resources.
Hold an iron sword in first person and left-click. The first swing plays your clip, the second and third play the built-in ones, and then the combo starts again.

The combo also starts again from your clip after about 1.5 seconds without a swing. Punchy! starts an attack clip at most about every 0.3 seconds, so a very fast click can look ignored while you test.

Video coming soon

The finished pack, switched on and played in the hand.

Your pack can sit anywhere in the list while it only adds a new clip name and one item entry. When two packs set the same thing, the pack higher in the list wins.

More ways to bind the clip

Every sword. Use the group key SWORD. It must be written in capital letters. This list changes the types you write for every sword. Other built-in sword types, such as inspect, stay as they are, so you only need to repeat a type when you want to change it:

{
  "item": {
    "SWORD": {
      "customAnimation": [
        {
          "type": "attack",
          "var_1": "my_sword_swing",
          "var_2": "attack_2",
          "var_3": "attack_3",
          "critical_hit": "attack_critical"
        },
        {
          "type": "mining_v2",
          "start": "new_mining_st_start",
          "looping": "new_mining_st_loop",
          "end": "new_mining_st_end"
        }
      ]
    }
  }
}

A key. A triggerable entry plays a clip when the player presses a key. The key shows in the game’s Key Binds screen (Options > Controls > Key Binds) under its title, and the player can change it there:

{
  "itemSpecific": {
    "minecraft:iron_sword": {
      "customAnimation": [
        {
          "type": "attack",
          "var_1": "my_sword_swing",
          "var_2": "attack_2",
          "var_3": "attack_3",
          "critical_hit": "attack_critical"
        },
        {
          "type": "mining_v2",
          "start": "new_mining_st_start",
          "looping": "new_mining_st_loop",
          "end": "new_mining_st_end"
        },
        {
          "type": "triggerable",
          "id": "my_swing_pack_show_off",
          "title": "Sword show off",
          "name": "my_sword_swing",
          "key": "H"
        }
      ]
    }
  }
}

This list repeats the attack and mining_v2 entries for the same reason as the first rule: a list for one item replaces the list of its group, so this sword does not keep the built-in sword types you leave out.

The compat rules page explains every part of the file, and types and triggers lists the actions a rule can play a clip for.

Add a sound

A clip can play a sound at a moment you choose. In Punchy! Studio, double-click the Sounds lane (or use Key > Insert Sound…), and drop an .ogg file onto the game window to bring in your own. Export copies the file and writes the rest into the pack.

By hand, a sound takes three parts. First, the clip names the sound at a time in seconds, in sound_effects. In Blender, put a marker named S:"my_swing_whoosh" on frame 12, which is 0.2 seconds, and the add-on writes the entry for you as "0.2": {"effect": "my_swing_whoosh"}. Punchy! reads that form and the plain string form below, which is the form to type by hand. The clip below is a Blockbench or Studio clip: a Blender clip keeps anim_speed_1; and leaves out use_keyframes_v2.

{
  "format_version": "1.8.0",
  "animations": {
    "my_sword_swing": {
      "animation_length": 0.6,
      "bones": {
        "right_arm": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.2": [-40, 0, 10],
            "0.35": [35, 0, -10],
            "0.6": [0, 0, 0]
          }
        }
      },
      "timeline": {
        "0.0": "anim_speed_1;dual_handed;use_keyframes_v2;"
      },
      "sound_effects": {
        "0.2": "my_swing_whoosh"
      }
    }
  }
}

Second, the sound file goes in the punchy namespace, not in minecraft:

assets/punchy/sounds/animationssounds/my_swing_whoosh.ogg

Third, the pack needs a sound event for it in assets/punchy/sounds.json. Punchy! Studio writes this for you:

{
  "animationssounds/my_swing_whoosh": {
    "sounds": ["punchy:animationssounds/my_swing_whoosh"]
  }
}

A few things to know:

Name a sound with lower case letters, digits, _, - and . only. The name in the clip is the file name without .ogg.
A name with no matching .ogg file is skipped without a message.
A clip that plays once shows its last frames and plays every sound keyed on it, one at the very end included, before it blends out.
A sound keyed after the clip’s animation_length never plays.
A sound at time 0.0 plays when the clip starts, also in a clip that blends in from the current pose, and again each time a looping clip wraps around.

The animation reference has the full rules for sounds.

Clip file keys

Key	What it does
`format_version`	Written by Blockbench, Blender and Studio as `1.8.0`. Keep it as they write it.
`animations`	An object that maps each clip name to its clip. A file with no `animations` key gives no clips.
clip name	The key under `animations`. Rules refer to it, and it is case sensitive.
`animation_length`	The length in seconds.
`loop`	`true` repeats the clip. `hold_on_last_frame` stays on the last frame. Leave it out to play once. The Blender add-on writes `play_once`, which also plays once.
`bones`	An object that maps a bone name to its channels.
`rotation`, `position`, `scale`	The channels of a bone. Each is an object keyed by time in seconds, or a plain array that counts as one key at time 0. Rotations are in degrees. Position and rotation default to `0`, and scale to `1`.
key value	Three numbers, or Molang expressions as strings. Any other count of numbers drops the clip.
`post`, `pre`, `lerp_mode`	A key can be an object: `post` is its value, `pre` a separate value before the key (rotation in v2 clips), and `lerp_mode` how it blends to the next key.
`timeline`	An object that maps a time to a string of tokens separated by `;`. A token stays active from its time to the end of the clip.
`effects`	Tokens that act at every time of the clip.
`sound_effects`	An object that maps a time to a sound name, or to an object with an `effect` key. See Add a sound.

Key interpolation (lerp_mode)
Key	Type	Default	What it does
`linear`	string	`linear`	A straight line between two keys, when neither key asks for another mode. A key written as a plain array has no mode of its own, so the segment between two plain keys is linear.
`catmullrom`	string		A smooth curve through the keys. A segment uses it when either of its two keys has this mode. The key is written as an object with `post` and `lerp_mode`.
`spherical_linear`	string		A rotation that turns along the shortest arc. Only for rotations in v2 clips (`use_keyframes_v2`).
`spherical_squad`	string		A smooth spherical curve. Only for rotations in v2 clips (`use_keyframes_v2`).

Rule keys used on this page

Keys of an animation entry
Key	Type	What it does	Example
`type`Required	string	The action the entry is for. Case, underscores and dashes do not matter, so `use_bow` and `useBow` are the same type.	`attack`
`name`	string	The clip to play, for a single clip. For an attack it is used only when `var_1` to `var_3` are all empty.
`animation`	string	The clip to play, for a single clip. It wins over `name`.
`var_1, var_2, var_3`	string	The clips of an attack combo, played in this order and cycled.
`critical_hit`	string	The clip played when a swing meets the conditions of a critical hit: the attack is charged and you are falling, and you are not sprinting, riding, blind, climbing or in water or lava.
`start, looping, end`	string	The three clips of a phased type such as `mining_v2`: how it starts, what repeats while the action goes on, and how it ends.
`key`	string	The default key of a `triggerable` entry, such as `H` or `F7`. The entry shows in the Key Binds screen only when it has a key.
`id`	string	The stable identity of a `triggerable` entry. Rules with the same id share one key binding.
`title`	string	The name of a `triggerable` entry in the Key Binds screen. It falls back to `name`.

Where an entry goes
Key	Type	What it does	Example
`itemSpecific`	object	A map from an item id, in lower case, to its entry. The entry of one item beats its group's entry.	`minecraft:iron_sword`
`item`	object	A map from a group name to its entry. The name must be a kind written in capitals, such as `SWORD`, `AXE`, `PICKAXE` or `BOW`, or a name from `customGroups`. A lower case key is ignored.
`customGroups`	list	Your own groups: each has a `name` and a list of `items`, and an `item` key with that name then applies to all of them.
`default_animations`	list	Entries for every item. They fill only the types that the item's own list does not have.
`emptyHand`	object	The same as an item entry, for your bare hand. Its `customAnimation` list is where punches go.

Timeline tokens used on this page
Key	Type	What it does	Example
`anim_speed_<n>`	token	Plays the clip at `n` times its authored speed from its time on, from 0.5 to 5.5. The player's Animation Speed setting is ignored for that clip.	`anim_speed_1`
`use_keyframes_v2`	token	Reads the clip in the v2 layout: rotations are added to the rig's rest pose and keys can have separate `pre` and `post` values. Do not use it in a clip exported from Blender.
`dual_handed`	token	The clip controls both arms.

The animation reference lists every timeline token and every key a clip or an entry can have.

Why a clip does not play

Go through these in order. Studio’s Effective column in the Bindings workspace answers most of them for you.

The pack is off, or the game has not reloaded. Check Options > Resource Packs, then press F3+T.
A file is in the wrong folder. Clips go in assets/minecraft/punchy/animations/ and rules in assets/minecraft/punchy/compat/. The pack’s pack.mcmeta sits next to assets, not inside it.
The clip name does not match. Names are case sensitive. My_Sword_Swing is not my_sword_swing.
The item does not match. Item ids go in lower case with their namespace (minecraft:iron_sword). A group name must be written in capitals (SWORD).
Another list replaces yours. The entry of one item replaces the list of its group, and when two packs set the same thing, the pack higher in the list wins. Check which rule is in force before you edit more.
A clip from Blender looks a few degrees off. If it turns about the arm’s Y or Z axis, take use_keyframes_v2 out of its timeline markers and export again. The Blender add-on writes the older key layout.
The clip plays too fast to see. Without an anim_speed_ token a clip runs at the player’s Animation Speed setting, 5.5 times faster than authored by default.
It is a walk, sprint, jump, fall or landing clip. These play only while Resource Pack Movement is on, and it is off by default. Turn it on in the Movement tab of Punchy!‘s menu (F8). Then a clip named punchy_moves_walk_forward, punchy_moves_sprint_forward, punchy_moves_jump, punchy_moves_fall or punchy_moves_land is used without a rule. Types and triggers lists every clip name of this group.
A sound is silent. Check that the .ogg file is in assets/punchy/sounds/animationssounds/, that its name is lower case and that assets/punchy/sounds.json has its event. See Add a sound.

Things that drop a whole file

Punchy! shows no message in the game for any of these. Open the file in an editor that checks JSON before you test.

A rule file: JSON Punchy! cannot read, such as a comma after the last property of an object, a duplicate key in a map, a value of the wrong type, a decimal where a whole number is needed, text after the last brace, or a root that is not an object. None of its rules load, and nothing is written to the log either.
A clip file Punchy! cannot read as JSON, such as a missing brace or a comma after the last property of an object, or whose root is not an object. The file gives no clips, and a warning that starts [Punchy] Could not read animations goes to logs/latest.log in your game folder.
A clip file with no animations key. It gives no clips, and there is no warning.

Inside a clip file, these drop that one clip while the rest of the file still loads. A warning that starts [Punchy] Could not load animation and names the clip goes to the log:

A bone value that is not an object.
A timeline that is not an object.
A key value with a number of items other than three.
A time key in a channel that is not a number.
A Molang expression that does not compile.
An animation_length that is not a number.

Punchy! Studio for Punchy! packs: the whole editor, including the Library and the Test panel.
Animation reference: every key and timeline token of a clip.
Types and triggers: which action plays which type of entry.
Compat rules: the rule file in full.
Resource packs: turning packs on and ordering them.
Player rig: the bones of the first person rig.
Model parts: custom models for held items.
Troubleshooting and the FAQ.

Before you start

How a clip reaches your hand

Make the clip

In Punchy! Studio

Start the clip

Key the swing in Punchy! Studio

Bind it to sword attacks

Try it in your hand

Save and export

Keep working on a pack you already have

In Blockbench

Open the first person rig

Add the animation

Key the swing in Blockbench

Set the speed and the layout

Export the clip in Blockbench

In Blender

Get the add-on and open its rig

Key the swing in Blender

Add the two markers

Export the clip from Blender

Put the clip in a pack

The pack file

The rule

Try it in game

More ways to bind the clip

Add a sound

Clip file keys

Rule keys used on this page

Why a clip does not play

Things that drop a whole file

Related pages