Player rig

Every first person clip Punchy! plays moves the bones of one small rig: a camera, a body, two arms and two grips that hold the item. This page gives you that rig as a file, names every bone and says what each one does, so you can key a clip in the tool you like. It is for anyone who animates by hand in Blockbench or Blender. Punchy! Studio already has the rig built in, and the Punchy Blender add-on comes with its own copy in a Blender file.

Before you start

• Punchy! 3.0 or newer for Minecraft 26.3, from Modrinth or CurseForge. The file below is the rig of Punchy! 3.0 for that version. It is also the rig of Punchy! for Minecraft 1.21.11 and 26.1 to 26.4. The jars for 1.21.5 and older carry a different rig file, so take it from your own jar there.
• Blockbench, Blender with the Punchy Blender add-on, or Punchy! Studio, whichever you will animate in. Studio comes from Modrinth or CurseForge. The Blender tab below shows where to get the add-on, which makes first person clips and nothing else.
• A clip file is only half of a working animation. A rule in a compat file plays it. Create an animation walks through both.

Download the rig

The rig is a Bedrock geometry file. It is Punchy Guys Studios’ own file, the same one the mod loads as punchy:geo/player.geo.json.

You can also take it from your own copy of the mod. Open the Punchy! jar from your mods folder (its name starts with punchy-3.0) with a zip tool and copy assets/punchy/geo/player.geo.json out. Leave the jar as it is.

The file holds one model, geometry.player, on a 64 by 64 texture grid. All sizes and pivots are in pixels, where 16 pixels are one block. The model has no texture of its own, so it shows in plain colors in your tool. That does not matter for animating.

Open it in your tool

The bones

The rig is one tree. The camera bones sit at the top (camera_animation, then camera), the body hangs from camera, and the arms hang from the body. Moving a bone moves everything below it. Keep the bone names exactly as they are: Punchy! finds a bone by its name, so a renamed bone does nothing.

camera_animation
  camera
    body
      right_arm
        item_right
          itemgrip_right
            base_right
            top_right
      left_arm
        item_left
          itemgrip_left
            base_left
            top_left
      torso
      head
      right_leg
      left_leg

This table lists every bone with the numbers that are in the file. Pivots are [x, y, z] in pixels. A bone with no rest rotation sits straight.

The arms rest tilted forward by about 100 degrees. That is the pose the file is saved in, and it is what a rotation of [0, 0, 0] means in a clip with use_keyframes_v2 made for this rig.

The bones a clip can move

Punchy! poses nine of these bones, each by its exact name:

• camera_animation, camera and body, which belong to neither hand.
• right_arm, item_right and itemgrip_right, which belong to the right hand.
• left_arm, item_left and itemgrip_left, which belong to the left hand.

A track under any other name, such as torso, head or base_right, moves nothing in game. Those bones are in the file, but Punchy! does not pose them.

In practice you key the camera, the two arms and the two grips. Studio edits those five, and the clips that come with Punchy! key the same ones. Names are exact: lower case, with underscores.

Left, right and one handed clips

Punchy! decides which hand a bone belongs to from its name. A name that starts with left_ or right_, or ends with _left or _right, belongs to that hand. camera_animation, camera and body belong to neither.

This matters when a clip plays from one hand. A clip started by the right hand moves only the right hand’s bones, plus the camera and the body. The left arm stays where it was. To make a clip move both arms, put the dual_handed token in its timeline.

The off hand has a few tokens of its own. With an empty off hand, dual_handed always holds. When the off hand holds an item, start_here_if_off_hand_item (also written start_if_offhand_item) and stop_if_offhand_item open and close a window in the clip, and dual_handed_if_has_off_item makes the clip dual handed when the off hand holds an item. hide_offhand_if_empty and show_offhand_if_empty hide and show the off hand arm while the real off hand is empty. Each one is explained under Hands and the off hand in the animation reference.

How a clip reads the rig

A clip is an animation file with a bones object. Each key under bones is a bone name from the table, and each bone holds up to three channels. Here is a complete clip you can copy. It moves the right arm and rolls the grip in the right hand, then returns both to the rest pose.

{
  "format_version": "1.8.0",
  "animations": {
    "rig_check": {
      "animation_length": 0.8,
      "bones": {
        "right_arm": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.3": [-30, 0, 8],
            "0.8": [0, 0, 0]
          }
        },
        "itemgrip_right": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.3": [0, 0, 40],
            "0.8": [0, 0, 0]
          }
        }
      },
      "timeline": {
        "0.0": "anim_speed_1;use_keyframes_v2;"
      }
    }
  }
}

The timeline line holds two tokens. use_keyframes_v2 makes Punchy! add the rotations to the rest pose, and anim_speed_1 plays the clip second for second, as you keyed it. The clip has no dual_handed, so it moves only the hand that starts the action, and it keys only right hand bones: test it with the right hand.

This clip is for Blockbench and Studio, where use_keyframes_v2 is the right layout. A clip exported from Blender leaves the token out, as the Blender tab above explains.

Save it as rig_check.animation.json in assets/minecraft/punchy/animations/ of a resource pack. To see it play, make a pack with these files:

Rig check pack/
  pack.mcmeta
  assets/minecraft/punchy/animations/rig_check.animation.json
  assets/minecraft/punchy/compat/rig_check.json

Copy the pack.mcmeta from The pack file and the rule from The rule on the Create an animation page. In the rule, change "var_1": "my_sword_swing" to "var_1": "rig_check". Switch the pack on as in Try it in game, then left-click with an iron sword in your right hand. The first swing plays rig_check.

A key can also be written as an object instead of an array, for example { "post": [-40, 0, 0], "lerp_mode": "catmullrom" }. post (or vector) holds the value, lerp_mode or easing picks how the channel blends to the next key, and in a clip with use_keyframes_v2 a rotation key can carry a separate pre value. A plain array key has no mode of its own, so it counts as linear, but a segment still uses catmullrom when the key at its other end asks for it. In a clip with use_keyframes_v2 the same holds for the rotation modes spherical_linear and spherical_squad. Ways to write a key and Interpolation modes list every form and mode. How the player’s own arm tuning behaves during a clip is described under Arm tuning and physics.

The camera bone

Keys on camera move both arms, because the body hangs from the camera, and they also move your view, which gives a camera shake. This works in both layouts, and rotation and position keys both count. Your view follows only while Enable Camera Animations is on, on the General tab of the Punchy menu. On Minecraft 1.21.11 even a shake of half a degree shows. On the other versions a turn reaches your view only when it is bigger than about 1.6 degrees or the bone also moves, so key a gentle shake a little stronger there.

Keys on camera_animation do not do this. The arms and the view follow camera and body only, so key camera for a camera move.

Things that go wrong

• Nothing moves. The bone name is wrong or belongs to a bone Punchy! does not pose. Compare it with the nine names above, letter by letter.
• The whole clip is dropped. A bones entry that is not an object, a rotation key whose time is not a number, a vector that does not have three values or a Molang value that does not compile drops the clip. The rest of the pack still loads.
• The arm jumps or points the wrong way. A clip made in Blockbench or Studio has no use_keyframes_v2, so Punchy! reads the keys in the older layout and does not add them to the rest pose. Add the token to the timeline.
• A clip exported from Blender turns the wrong way. Its timeline has use_keyframes_v2. The add-on writes the older layout, so take the token out and export again.
• Only one arm moves. That is how a one handed clip works. Add dual_handed when both arms should follow the clip.
• The clip plays too fast. Without an anim_speed_<n> token, most clips follow the player’s Animation Speed setting. Add anim_speed_1 to the first timeline entry.
• The item still swings while the clip plays. Pendulum physics move the arm and the held item. Add disable_pendulum to the timeline to turn them off while the token is active.
• The numbers in Blockbench do not match the file. Blockbench flips the sign of x for pivots and of x and y for rotations, as described in the Blockbench tab. Read the exported clip, not the numbers Blockbench shows for the bone, to see what Punchy! gets.
• I moved a pivot in my tool and nothing changed in game. A clip file holds no pivots. Punchy! reads the rig from punchy:geo/player.geo.json through the game’s resource manager, so only a resource pack that ships assets/punchy/geo/player.geo.json changes the rig in game. Keep the pivots and names of the rig you animate on, or a clip would not look the same in game as it does in your tool.
• My clip is fine in my tool but does not play. A clip needs a rule. See compat rules and types and triggers.

Related pages

• Create an animation: from the first key to a clip playing in your hand, in Studio or Blockbench.
• Animation reference: every key and timeline token of a clip file.
• Punchy! Studio: the editor that loads this rig for you.
• Geometry and textures: the geometry of held items, which is a separate file from this rig.
• Troubleshooting: why a clip does not play.