Animation files

This page is the reference for the animation files that Punchy! Moves plays in third person. Use it when you write a clip by hand, when you edit a file that Blockbench or Punchy! Studio made, or when a clip plays differently from what you keyed.

A clip file is plain JSON in the Bedrock animation format, the same format Blockbench writes with Animation > Export Animations. The file only says how a motion looks. A separate compat file decides when a clip plays, and that is on the compat files page. Where a recording shows a real pack, it is the example pack provided by Crafto, Fluid & Foolish.

Before you start

• Punchy! Moves installed. If it is not installed yet, start with getting started.
• A resource pack folder in your resourcepacks folder, with its pack.mcmeta. Getting started shows how to make one.
• A plain text editor. Keep the clip file plain JSON, because one wrong character can cost you the whole file (see the pitfalls below).

Write and play your first clip

This pack has two clips and puts both on the emote wheel. The first waves the right arm. The second nods the head and then snaps it, to show a sudden change.

The folder inside your resourcepacks folder:

My Moves Clips/
  pack.mcmeta
  assets/
    punchy_moves/
      animations/
        my_clips.json
      compat/
        my_clips.json

The pack’s pack.mcmeta, at the top of the My Moves Clips folder. The three 75s are the resource format of Minecraft 1.21.11. On another version, put that version’s number from the table on Resource packs in their place:

{
  "pack": {
    "description": "My Punchy Moves clips",
    "pack_format": 75,
    "min_format": 75,
    "max_format": 75
  }
}

The clip file, animations/my_clips.json:

{
  "format_version": "1.8.0",
  "animations": {
    "wave": {
      "animation_length": 1.2,
      "loop": true,
      "bones": {
        "right_arm": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.3": { "post": [0, 0, 140], "lerp_mode": "catmullrom", "easing": "easeOutBack" },
            "0.6": { "post": [0, 0, 110], "lerp_mode": "catmullrom" },
            "0.9": { "post": [0, 0, 140], "lerp_mode": "catmullrom" },
            "1.2": [0, 0, 0]
          }
        },
        "head": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.3": [0, 0, 8],
            "1.2": [0, 0, 0]
          }
        }
      }
    },
    "nod_snap": {
      "animation_length": 1.0,
      "bones": {
        "head": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.4": { "post": [25, 0, 0], "easing": "easeInOutSine" },
            "0.5": { "pre": [25, 0, 0], "post": [-10, 0, 0] },
            "1.0": [0, 0, 0]
          },
          "scale": {
            "0.0": [1, 1, 1],
            "0.5": { "post": 1.15 },
            "1.0": [1, 1, 1]
          }
        }
      }
    }
  }
}

The compat file, compat/my_clips.json, which lists both clips as emotes:

{
  "format_version": 2,
  "emotes": {
    "entries": [
      { "id": "wave", "display_name": "Wave", "animation": "wave", "face": "happy" },
      { "id": "nod_snap", "display_name": "Nod", "animation": "nod_snap" }
    ]
  }
}

What the wave does:

• wave is the clip’s name. The compat file calls it by this exact name.
• animation_length is 1.2 seconds, and loop makes it repeat.
• right_arm has a rotation channel with keys at 0.0, 0.3, 0.6, 0.9 and 1.2 seconds. The arm goes up to 140 degrees around Z and waves between 110 and 140.
• The keys that carry lerp_mode make the motion a smooth curve. The key at 0.3 also has easing, so the arm swings past 140 and settles back.
• head tilts a little at 0.3 seconds and returns, so the loop closes where it started.

What the nod does: the head eases down to 25 degrees by 0.4 seconds and holds there until 0.5. At 0.5 the key’s pre says the head arrives at 25, and its post says it leaves at -10, so it snaps up in one frame. The scale key uses a single number, 1.15, which sets all three scale parts at once.

Make the file in a tool

Blockbench and Punchy! Studio both write this format, so you rarely type a whole file. The steps below cover the format-specific parts: easing a key and exporting. For a clip from nothing, see how to create custom animations.

Where Punchy! Moves loads clip files

Moves reads every .json file at any depth under this folder of every active resource pack:

assets/punchy_moves/animations/

The folder name is spelled punchy_moves, all in lower case with an underscore. A file in another namespace is not read. Blockbench names its exports something.animation.json, and that works, because only the .json ending counts.

• Order. Files are read in the order of their full path text. When a later file has a clip with the same name as an earlier one, the later clip replaces the earlier one completely. Clips are never merged.
• Compat first. Moves reads the compat files before the animation files. Both are read again whenever resources reload.
• One path, two packs. When two active packs have a file at the same path, only the copy from the higher pack in the player’s resource pack list is read.
• Different paths, two packs. Files at different paths are all read, and the path order above decides which clip wins. To replace a clip from another pack, give your file the same path as the file that defines it, or a path that sorts after it.
• Reload. Press F3+T after editing a file, or change the resource packs. Studio’s export does this for you when Turn the pack on and reload is ticked.

A clip

Each member of animations is one clip, named by its key. Clip names are case-sensitive: compat files and emotes must spell a name exactly as it is written here. Moves reads four members of a clip.

The format_version line at the top of a file is not read by Moves. Blockbench writes it, so leave it in. Any other member of a clip is left alone and changes nothing.

The bones

A clip moves the bones of the player rig. Bone names are read in any case, so Right_Arm and right_arm are the same bone.

Units and directions:

• Position is in pixels, a sixteenth of a block. X points toward the player’s left, Y up and Z toward the back.
• Rotation is in degrees. A positive X rotation swings a hanging arm backward and tips the head down.
• Scale is a factor. 1 is the normal size and 2 doubles the part.
• Item bones move in the arm’s own frame. Their scale Y is forward and back, and Z runs along the arm.

The skin’s second layer (hat, jacket, sleeves, pants) follows its part, so keys on those names do nothing. Key the part itself. A bone that is not in the rig and is not a face_ bone, such as one an artist added, is kept and nothing follows it. When the clip has no animation_length, its last key still counts toward the clip’s length. A bone with no keys stays at its rest pose.

Channels and keys

Each bone has up to three channels. A channel you leave out holds its default for the whole clip.

A channel is either one value for the whole clip, such as "rotation": [0, 0, 8], or an object of keys by time. A key’s name is a time in seconds, written as text. A key’s value is three numbers or an object.

Every way to write a key

A key with nothing in it, { }, holds the channel’s default at that time.

Sudden changes with pre and post

Between two keys, Moves goes from the first key’s post to the second key’s pre. Give a key different pre and post values and the motion jumps at that key’s time:

{
  "format_version": "1.8.0",
  "animations": {
    "head_snap": {
      "animation_length": 1.0,
      "bones": {
        "head": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.5": { "pre": [0, 0, 0], "post": [0, 0, 90] },
            "1.0": [0, 0, 0]
          }
        }
      }
    }
  }
}

In this clip, the head stays at 0 until 0.5 seconds, jumps to 90 degrees around Z, then returns to 0 by 1.0 second. Use this for a hit, a snap or a blink-fast pose change. A key with only post arrives and leaves with the same value, so it never jumps.

Time and holds

• Key times are read as decimal numbers. "1" and "1.0" are the same time, so two keys written that way collide and the one written last in the file wins.
• Before the first key, the bone holds the first key’s pre. After the last key, it holds the last key’s post.
• A key placed after the end of a clip that does not loop is never reached, but it still shapes the curve of the last segment.
• A bone, or a channel, with no keys holds its default (position and rotation 0, scale 1).

Read a real clip

The example pack provided by Crafto has a clip called shears_use_one_handed_right. It is 1.2083 seconds long and plays once. This is a trimmed copy of it that keeps only the rotation of its right_item bone:

{
  "animations": {
    "shears_use_one_handed_right": {
      "animation_length": 1.2083,
      "bones": {
        "right_item": {
          "rotation": {
            "0.0": { "post": [0, 0, 0], "lerp_mode": "catmullrom" },
            "0.2083": [2.3516, 38.3394, -86.0029],
            "0.9167": { "pre": [2.3516, 38.3394, -86.0029], "post": [2.3516, 38.3394, -86.0029], "lerp_mode": "catmullrom" },
            "1.2083": { "post": [0, 0, 0], "lerp_mode": "catmullrom" }
          }
        }
      }
    }
  }
}

It shows three of the forms at once: an object with only post, three numbers, and an object with pre and post. The key at 0.2083 is plain three numbers and has no lerp_mode, yet both segments next to it curve, because the key at the other end of each one says catmullrom. It is an item bone, so it counts only while an action holds an item, which here is the shears being used.

lerp_mode

lerp_mode says how the motion goes from one key to the next.

A segment is smooth when either key at its ends says catmullrom: the key it starts from or the key it ends on. A smooth segment also looks at the key before it and the key after it to shape the curve. At the ends of a clip that does not loop there is no neighbor, so the curve uses its own end. In a looping clip, the neighbor before the first key wraps around to the last key that comes before the clip’s end (a key at exactly the end does not count). The neighbor after the last key wraps around to the key that follows the first key, but only when the channel has more than two keys. Otherwise the curve uses the segment’s own end.

A smooth curve can swing a little past a key’s value between keys when its neighbors pull it. If a value must not go past a key, make that key and the keys next to it linear.

Any other lerp_mode text, such as bezier or step, plays as linear. For a sudden change use pre and post. That is what Punchy! Studio’s Constant interpolation writes: step on the key, and a pre with the same values on the next key, so the pose holds until that key and then jumps.

Easing

A key’s easing reshapes the segment that ends on that key. Moves works out how far through the segment the clip is, bends that progress with the curve, and then runs the segment’s own interpolation, linear or smooth, with the bent progress. So easing goes on the key the motion arrives at.

{
  "bones": {
    "right_arm": {
      "rotation": {
        "0.0": [0, 0, 0],
        "0.3": { "post": [0, 0, 140], "lerp_mode": "catmullrom", "easing": "easeOutBack" }
      }
    }
  }
}

The key at 0.3 is the one the arm arrives at, so the swing from 0.0 to 0.3 follows the curve.

• The motion from the key before to this one follows the curve. The motion after this key does not.
• A key with nothing before it has no motion arriving, so its easing is never used.
• A key written as three numbers cannot carry easing. Turn it into an object first: { "post": [0, 0, 140], "easing": "easeOutBack" }.
• Names are read without case, underscores, dashes or spaces. easeOutBack, ease_out_back and Ease Out Back are the same curve.
• No easing, linear or a name Moves does not know leaves the segment at an even pace.
• Back and Elastic curves go past the key’s value and come back. Check that a limb does not pass through the body when you use them.

All 30 curves

The 30 curves are the ones on easings.net, in 10 families with three directions each. In curves start slowly and arrive fast. Out curves start fast and arrive slowly. In and out curves do both. The numbers show how far through the move the motion is (0 is the start, 1 is the end) after a quarter, half and three quarters of the time. An even pace would read 0.25, 0.50 and 0.75.

Values below 0 mean the motion goes behind its start, and values above 1 mean it goes past its target.

Loops and length

• Length. animation_length in seconds. Without it, the clip lasts until its last key. In Studio, From Keys in the clip’s properties removes the written length so the keys decide it.
• Looping. "loop": true makes the clip start over when it reaches its length. The clip’s time wraps around, so a key after the length is never reached. Only the JSON value true loops.
• Not looping. A clip without loop plays once and ends on its last pose. What follows, such as a fade back to idle, is up to the action that played it.
• Closing a loop. Key the first pose again at the end of the clip, as the wave above does with "1.2": [0, 0, 0]. Without it, the loop jumps from the last pose back to the first. In Studio, copy the pose at 0 with Ctrl+C and paste it at the end with Ctrl+V.

Set the loop in Blockbench in the animation’s properties, and in Studio with Loop or Not looping in the clip’s properties.

How Moves finds a clip

Moves does not play a clip because it exists. Something has to name it.

• A compat file names it. An action such as attack, walking or idle holds a clip name, and an emote lists one in animation. The name must be spelled exactly as in the animation file, capitals included. See compat files.
• An emote needs a loaded clip. An emote whose clip no file defines is not on the wheel.
• A missing name is silent. An action that names a clip nobody defines just does not play. Nothing warns about it in game.

Left and right clips

Clips for held-item actions, such as attacks, mining, equipping and using items, are played per arm. For a name in the compat file, Moves looks for these, in order, and plays the first it finds:

1. <name>_right or <name>_left, for the arm that does the action.
2. If the name ends in _alt: <base>_right_alt or <base>_left_alt, where <base> is the name without _alt.
3. The plain <name>.

So one clip can serve both arms, or you can give each side its own. In the example pack provided by Crafto, the compat file says "clip": "punch" for an empty hand attack, and the animation files define punch_right and punch_left. The arm decides which one plays: a right-handed player’s main hand uses _right and the off hand uses _left. A left-handed player’s main hand uses _left, and the off hand uses _right.

Moves does not mirror these clips. A _left clip has to be keyed for the left side. In Studio, Clip > Mirror to Twin (Ctrl+Shift+M) builds the other side from the open clip. It adds the twin next to it with the arm, leg and item bones swapped and the keys mirrored. In Blockbench, key both sides.

Body clips such as walking, jumping, an emote and idle are played by the name you give, with no side suffix.

Things that drop a key or a whole file

Moves does not log a problem with an animation file. When something is wrong, the only sign is that a clip does not play or moves wrongly. Studio’s Checks panel reads your clip the way the game does and lists these cases while you key.

Numbers only

Every part of a key must be a plain number. A part that is text and not a number, such as a Molang expression like Math.sin(query.anim_time * 90) * 10, is replaced by the channel’s default: 0 for position and rotation, 1 for scale (or by the matching part of the key’s pre, when a key object has its own valid pre). An expression does not stop the key from loading, so the clip plays but the motion is wrong. Bake an expression into keys before you export.

Why my clip does not play

Go through the list in order.

1. Is the pack on, and reloaded? Turn it on under Options, Resource Packs, then press F3+T.
2. Is the file in the right folder? It must be under assets/punchy_moves/animations/ and end in .json.
3. Does something name the clip? Check the compat action or the emote entry. A missing clip in an emote leaves the emote off the wheel.
4. Is the name spelled the same? Clip names are case-sensitive: Wave is not wave. For an arm action, check the _right and _left names.
5. Did an earlier problem drop it? A bones that is not an object loses its clip and every clip after it in the file. Move the suspect clip to the end of the file, or fix it.
6. Is another file defining the same name? The file that sorts later by path wins, even if it comes from another pack.
7. Does it play but not move? Check that the bone is one of the rig’s bones, that it is not the skin’s second layer, that item bones are used in an item action, and that the keys are objects with a post when you give lerp_mode or easing.
8. Does it move too little? Rotation is in degrees and position in pixels. A position of 1 is a sixteenth of a block.

To watch a clip on your own player while you edit it, use Studio’s Game view. See the Game view.

Related pages

• How to create custom animations takes you from the rig to a clip playing in game.
• Compat files lists every action a clip can be wired to.
• Faces in packs and clips shows the face member and the face_ bones.
• The Blockbench rig has the rig, the plugin and its easing menu.
• Punchy! Studio and the Game view cover the editor.
• Keys and emotes explains the emote wheel.
• Recipe: a walk cycle and recipe: an emote go through two common clips step by step.
• Troubleshooting helps when a clip still does not play.