How to create custom animations

You can make your own full-body animation for Punchy! Moves and see it play on your player in third person. This page takes you from the rig to a clip that plays in game, in Blockbench or in Punchy! Studio. It is for anyone who wants to add a wave, a bow, a sword swing or a new walk to a pack.

The clips on this page come from the example pack provided by Crafto, Fluid & Foolish, the animation pack used for the Punchy! Moves demos on this wiki. You can follow along with your own clips or look at how the example pack’s are made.

Before you start

• Punchy! Moves installed (Getting started has the steps). Finished clips play in game, so you need the mod to see your work.
• For the Blockbench path: Blockbench 4.8 or newer (checked in 5.2.2), plus the Punchy! Moves rig and plugin. You get them from The Blockbench rig or from Punchy! Studio.
• For the Punchy! Studio path: Punchy! Studio. It works inside Minecraft, so you animate on your own skin and see the result in the game itself.
• Blender: the Blender tab has no steps yet, so the steps here are for Blockbench and Punchy! Studio.

A clip is only half of the job. The clip says how the body moves. A compat file says when it plays. Both paths below end with the two together, and the sections after them show other ways to wire a clip.

Make your first clip

Wire a clip to an action

A clip does nothing by itself. A compat file in assets/punchy_moves/compat/ names the clip for a moment: a held item, walking, climbing or an emote. Every compat file is a complete JSON file, starts with "format_version": 2, and its action names go under defaults.animations or an item group. The whole format is on Compat files.

The examples below use clips from the example pack provided by Crafto and are trimmed to the settings that matter, so the pack’s own compat file has more. They play those clips as they stand with that pack on, except the emote, which plays the bow_greeting clip you made above. Put each example in its own file, or merge their objects into one file.

An emote

The emote you made above, with the common keys. keybind gives the emote its own key. Without it, the emote is on the wheel only.

{
  "format_version": 2,
  "emotes": {
    "menu_key": "C",
    "entries": [
      {
        "id": "bow_greeting",
        "display_name": "Bow",
        "animation": "bow_greeting",
        "keybind": "H",
        "face": "happy"
      }
    ]
  }
}

Emotes start only while the player stands still on the ground, and only you see your own emotes.

A sword swing

Held items go in an item group. The example pack’s SWORD group plays two swings in turn. After more than 20 ticks without a swing, the combo starts again from the first clip.

{
  "format_version": 2,
  "item_groups": {
    "SWORD": {
      "animations": {
        "attack": {
          "variants": ["sword_attack_1", "sword_attack_2"],
          "retrigger_progress": 10
        }
      }
    }
  }
}

retrigger_progress is the percent of the clip that must play before the next click can start the next swing.

Video coming soon

Walking

Body actions go under defaults. This is trimmed from the example pack’s walking entry, which also layers extra clips on top and sets how walking blends. It plays the normal_forward loop when you walk forward, plays the same loop in reverse when you walk backward (reverse), and uses the two sidestep clips for left and right. All three clips loop in the example pack.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "walking": {
        "directions": {
          "forward": "normal_forward",
          "backward": { "clip": "normal_forward", "reverse": true },
          "left": "sidestep_left",
          "right": "sidestep_right"
        }
      }
    }
  }
}

For sprinting, more walking clips and how they blend, see Recipe: a walk cycle.

Climbing

One clip serves for climbing. With timer_effect set to vertical_delta, it follows your vertical speed and plays backward when you climb down. timer_scale calibrates that speed: your climbing speed is a small number, so without it the clip plays very slowly. The example pack uses 8.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "climbing": {
        "clip": "climbing_up",
        "timer_effect": "vertical_delta",
        "timer_scale": 8
      }
    }
  }
}

A mace sequence

A mace has phases. This is the example pack’s group, trimmed to the clips that matter. Its clip names, such as mace_slam, are written without a side: the pack holds mace_slam_right and mace_slam_left, and the mod picks the one for the arm that does the action.

{
  "format_version": 2,
  "item_groups": {
    "MACE": {
      "static_when_using": true,
      "sequence": {
        "behavior": "mace",
        "charge_height": 3,
        "smash_distance": 1.5,
        "defaults": { "over_idle": true }
      },
      "animations": {
        "equip": { "clip": "mace_idle" },
        "idle": { "clip": "mace_idle", "hold_last_frame": true },
        "charge": { "clip": "mace_charge" },
        "slam": { "clip": "mace_slam" },
        "attack": { "variants": ["mace_attack_1", "mace_attack_2"] }
      }
    }
  }
}

over_idle is for phases whose clips were animated as a change from the idle pose. The example pack sets it for every phase of its mace, so the swings, the charge and the slam add onto the raised mace of mace_idle. With "over_idle": true, such a phase plays on top of the last frame of the idle clip. Without it, the clip drops the idle pose while it plays. Put it on one phase, or in sequence.defaults for every phase, as here. It takes the JSON value true or false without quotes (text is ignored), and it does nothing on equip and idle.

More sequences (a bow, a bucket and more) are in Recipe: an item sequence. Every other action is in Compat files, and emotes in particular are in Recipe: an emote.

More actions you can wire

Body actions go under defaults.animations. Held-item actions go under animations in an item group, as in the sword example. Each row is the shortest form that works, with placeholder clip names for you to swap for your own.

Every row goes inside a complete compat file with "format_version": 2, like the examples above. The keys of each action, and the many actions not listed here, are on Compat files.

How the pack folder fits together

When two packs have a clip or compat file at the same path, the copy from the higher pack in the player’s resource pack list is the one read. Reaction changes in faces/triggers.json from every pack are combined, and the higher pack wins for each reaction it sets.

What a clip file holds

Punchy! Moves reads the Bedrock animation format, which is what Blockbench writes and Punchy! Studio writes too. Here is a small hand-written clip in the format the two tools export:

{
  "format_version": "1.8.0",
  "animations": {
    "wave_right": {
      "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.9": { "post": [0, 0, 120], "lerp_mode": "catmullrom" },
            "1.2": [0, 0, 0]
          }
        },
        "head": { "rotation": [0, 0, 8] }
      }
    }
  }
}

Here is a real excerpt from the example pack provided by Crafto, the first two keys of the arm in sword_attack_1 (0.8333 seconds long, it does not loop):

{
  "animation_length": 0.8333,
  "bones": {
    "right_arm": {
      "rotation": {
        "0.0": { "post": [-154.7935, 41.0047, -36.8323], "lerp_mode": "catmullrom" },
        "0.0833": { "post": [-24.0428, -4.4934, -84.4029], "lerp_mode": "catmullrom" }
      }
    }
  }
}

A key written as three bare numbers, like "0.0": [0, 0, 0], is linear and has no easing. To ease or smooth a key, write it as an object.

The bones

Positions are in pixels, rotations in degrees, and scale is a factor where 1 is the normal size. A positive X rotation swings a hanging arm backward and tips the head down. The skin’s second layer (hat, jacket, sleeves, pants) is not keyed on its own, so keys on those names do nothing. A clip reads only its length, loop, bones and face. There is no Molang, no sound and no particle in a clip.

The full format, with every easing curve, is on Animation files.

Left and right clips

Many actions play a clip for the arm that does them. Moves looks for <name>_right or <name>_left first, then the plain <name>. A clip whose name ends in _alt also looks for <base>_right_alt and <base>_left_alt. That is how mace_slam in the compat file finds mace_slam_right in the example pack.

Clips are not mirrored for you, so a _left clip has to be keyed for the left side. In Studio, Clip > Mirror to Twin (Ctrl+Shift+M) builds one from the other. In Blockbench, key both.

Things that stop a clip from playing

• The name does not match. Clip names are case-sensitive. Bow_Greeting in the compat file will not find bow_greeting in the animation file. A clip name that no file defines plays nothing, and the log says nothing about it. Blockbench’s default name for a new animation starts with animation. and the model name, so rename it to the plain name before you export.
• The clip does not loop. Only "loop": true loops. In Blockbench, set Loop Mode to Loop. Hold On Last Frame plays the clip once.
• A whole compat file is dropped. Any error in a format 2 file drops the file: a format_version other than 2, a root key the format does not know, an action name with a capital letter, an unknown key inside sequence or turn_in_place. Nothing in that file applies. Look in logs/latest.log for a line that says Could not load animation compat and your file’s name. After the colon, the text starts with Compat and the field path in English, then a message that may be in Portuguese. Studio’s Verdict panel tells you before you export.
• Broken JSON drops an animation file. A file that is not valid JSON, or whose root is not an object, adds no clips at all. If one clip cannot be read, the clips before it stay and the rest of that file is skipped. Animation files log nothing when they fail, so check the JSON in Blockbench or Studio, which write valid JSON for you.
• A changed emote key does not move. The emote wheel key and each emote key are set up once, when the game first installs them, and the key the game saved earlier can win over a new default from the pack, even after a restart. After you change keybind for an emote the game already knows, or change menu_key, set the key under Options, Controls, Key Binds.
• The pack is off, or not reloaded. Turn the pack on under Options, Resource Packs, then press F3+T. Studio’s export does this for you when Turn the pack on and reload is ticked.
• A higher pack has the same file. Packs are read in the player’s pack order, and for the same clip or compat path the highest pack wins. Give your files their own names.
• An emote does nothing. Emotes start only when you stand still on the ground, and they are not sent to other players. An emote whose clip no file defines is not on the wheel.
• The face stays Happy. An emote’s face takes the lower-case name of a built-in look. A look only your pack has plays Happy.
• Two clips with one name. The later file in path order wins. Rename one.

Related pages

• Animation files has every key of a clip and every easing curve.
• Compat files lists every action you can wire a clip to.
• The Blockbench rig has the rig, its face board and the plugin.
• Punchy! Studio and the Game view cover the editor.
• Faces in packs and clips shows how to key a face in a clip.
• Keys and emotes explains the emote wheel and its keys.
• Recipe: a walk cycle, an emote and an item sequence go step by step through the common clips.
• Troubleshooting helps when something still does not play.