Item sequence

An item sequence gives one item its own small story: you pick it up, hold it, draw it and let it go, and a different clip plays for each moment. This recipe builds the draw and release of a bow from two clips and one compat file. It then shows how a mace keeps its raised pose under its swings with over_idle, and how a bucket plays other clips when your other hand is full. It is for pack makers who have made a clip before. If you have not, start with Create an animation.

The clips and excerpts come from the example pack provided by Crafto, Fluid & Foolish, the Punchy! Moves animation pack used for every demo on this wiki. The excerpts keep that pack’s clip names, which only it has. To run one with your own clips, put your own clip names in their place.

Before you start

• Punchy! Moves installed, and a resource pack with an assets/punchy_moves/ folder. Getting started makes one, and so does New Pack in Punchy! Studio.
• A world where you can hold a bow and shoot an arrow, to test.
• If the example pack provided by Crafto is on, turn it off while you test, so that only your own bow plays.

How a bow sequence runs

A sequence sits on an item group (here BOW) or on one exact item. Its behavior decides when each phase plays, and the group’s animations give each phase a clip. A phase with no clip plays nothing, so the walk and the idle you already have show instead. For a bow:

The draw clip does not play at its own speed. Moves sets its time from how long you have held the use button: after charge_ticks (20 by default, which is one second) the clip stands on its last frame. So the last frame of your draw clip is the full draw. If you let go without a shot, the bow goes back to idle.

A hold clip is optional. Without it the draw clip stays on its last frame while you keep holding. The example pack’s bow gives hold the draw clip with hold_last_frame, so the full draw is a phase of its own, with its own blend and settings.

The other behaviors are trident, mace, flint, shears, fishing, bucket and throwable. Their phases are in The behaviors and their phases.

The compat file

This is the file you will end up with. It is the example pack’s bow, trimmed, with placeholder clip names: my_bow_draw and my_bow_release are the two clips you make in the next section.

{
  "format_version": 2,
  "item_groups": {
    "BOW": {
      "static_when_using": true,
      "sequence": {
        "behavior": "bow",
        "charge_ticks": 20,
        "legs_locomotion_retain": 1,
        "defaults": {
          "transition_seconds": 0.16,
          "locomotion_retain": 0.08
        }
      },
      "animations": {
        "charge": "my_bow_draw",
        "hold": { "clip": "my_bow_draw", "hold_last_frame": true },
        "release": { "clip": "my_bow_release", "locomotion_retain": 0.15 }
      }
    }
  }
}

• BOW is the item group of bows. Crossbows are their own group and do not use a sequence.
• static_when_using draws the item you use in its ordinary held place while you use it, instead of Minecraft’s own placement for a used item. The example pack’s bow, mace and buckets all have it.
• behavior is bow, in lower case. charge_ticks is how long the use button must be held for the draw clip to reach its last frame.
• legs_locomotion_retain is how much of the walk shows on the legs during every phase. At 1 the legs keep the whole walk.
• defaults holds settings that every phase shares. transition_seconds is the blend into a phase, in seconds, and locomotion_retain is how much of the walk shows during the phase. A phase’s own value wins, so release lets a little more of the walk through.
• hold plays the draw clip again with hold_last_frame, so it shows the draw’s last frame and stays there.

Build it

Your clips can have a left and a right version. Name the pair my_bow_draw_left and my_bow_draw_right and keep writing my_bow_draw in the compat file: Moves plays the one for the arm that does the action. A clip with only a plain name plays for both arms and is not mirrored. See Left and right clips.

Play it

Video coming soon

If nothing plays, go down Things that go wrong.

Keep a pose under a phase with over_idle

Some clips are animated as changes from a pose that another clip sets, not as full poses. The example pack’s mace is held raised: its mace_idle clip ends on that raised pose, and the group holds that last frame as its idle. The charge, the slam and the swings are animated as changes from that idle pose, and add their motion onto the raised mace. Played alone, such a clip drops the idle pose while it plays.

over_idle fixes that. With true, the phase’s clip plays on top of the last frame of the item’s idle clip. This is the example pack’s mace. Its defaults turn over_idle on for every phase:

{
  "format_version": 2,
  "item_groups": {
    "MACE": {
      "static_when_using": true,
      "sequence": {
        "behavior": "mace",
        "charge_height": 3,
        "smash_distance": 1.5,
        "defaults": {
          "transition_seconds": 0.16,
          "locomotion_retain": 0.15,
          "retrigger_progress": 70,
          "over_idle": true
        }
      },
      "animations": {
        "equip": { "clip": "mace_idle" },
        "idle": { "clip": "mace_idle", "hold_last_frame": true, "transition_seconds": 0.22 },
        "charge": {
          "clip": "mace_charge",
          "one_handed": "mace_charge_alt",
          "transition_seconds": 0.05,
          "locomotion_retain": 0.05
        },
        "slam": {
          "clip": "mace_slam",
          "one_handed": "mace_slam_alt",
          "transition_seconds": 0.05,
          "locomotion_retain": 0,
          "retrigger_progress": 85
        },
        "attack": {
          "variants": [
            { "clip": "mace_attack_1", "one_handed": "mace_attack_alt_1" },
            { "clip": "mace_attack_2", "one_handed": "mace_attack_alt_2" }
          ]
        }
      }
    }
  }
}

Video coming soon

How it behaves:

• Put over_idle on one phase, or in sequence.defaults for every phase. A phase’s own value wins. The same keys work on an exact item under items.
• It is true or false without quotes. Text such as "true" is ignored.
• It does nothing on equip and idle, and it needs an idle phase with a clip. Without one there is nothing to play on top of.
• The clip’s values are added to the idle’s last frame. A clip that already holds the raised pose in its own keys would raise it twice, so leave over_idle off for a clip animated from the full pose.

To use it on one phase only, write it on that phase:

{
  "format_version": 2,
  "item_groups": {
    "MACE": {
      "sequence": { "behavior": "mace" },
      "animations": {
        "idle": { "clip": "my_mace_idle", "hold_last_frame": true },
        "slam": { "clip": "my_mace_slam", "over_idle": true }
      }
    }
  }
}

To see it with two clips of your own:

When your other hand is full

one_handed on a phase names the clip that plays instead when your other hand holds something. It is a clip name, or an object with a clip and settings of its own. The mace above gives most phases a one-handed twin. The example pack’s filled bucket does the same for equip, idle and use, and gives the idle’s one-handed clip an object so that it can have its own blend:

{
  "format_version": 2,
  "item_groups": {
    "FILLED_BUCKET": {
      "static_when_using": true,
      "sequence": {
        "behavior": "bucket",
        "defaults": {
          "transition_seconds": 0.16,
          "locomotion_retain": 0.15,
          "retrigger_progress": 70
        }
      },
      "animations": {
        "equip": {
          "clip": "bucket_full_dual_handed_intro",
          "one_handed": "bucket_full_one_handed_intro"
        },
        "idle": {
          "clip": "bucket_full_dual_handed_intro",
          "one_handed": { "clip": "bucket_full_one_handed_intro", "transition_seconds": 0.16 },
          "hold_last_frame": true,
          "transition_seconds": 0.22
        },
        "use": {
          "clip": "bucket_full_dual_handed_action",
          "one_handed": "bucket_full_one_handed_action"
        }
      }
    }
  }
}

The bucket behavior plays use when you use the bucket. An empty bucket is its own group, EMPTY_BUCKET, with a sequence of its own.

Video coming soon

Overlays follow the same split. one_handed_overlays is a list of overlay objects, written like overlays, with a clip, a mode and bones. While the phase’s one-handed clip plays, it replaces overlays. Without it, the one-handed clip plays the ordinary overlays. An empty list plays none. For a use phase, the overlays are chosen when it starts and kept until it ends.

The example pack provided by Crafto uses it on held actions outside a sequence: the attack and mining of its AXE group name pickaxe clips as one_handed, with the pickaxe overlays in one_handed_overlays. On a phase it is written the same way. The overlay clips here are placeholders:

{
  "format_version": 2,
  "item_groups": {
    "FILLED_BUCKET": {
      "sequence": { "behavior": "bucket" },
      "animations": {
        "use": {
          "clip": "bucket_full_dual_handed_action",
          "one_handed": "bucket_full_one_handed_action",
          "overlays": [{ "clip": "my_bucket_use_add", "mode": "additive", "bones": ["head"] }],
          "one_handed_overlays": [{ "clip": "my_bucket_use_one_hand_add", "mode": "additive", "bones": ["head"] }]
        }
      }
    }
  }
}

one_handed_overlays goes on a phase, never in sequence.defaults: there it drops the whole file.

The keys used here

These are the keys this recipe uses. Every other key of a sequence is in Sequences of the compat file reference.

Things that go wrong

• The whole file is dropped. The game skips a file with any of these: a behavior that is not one of the eight, or is not in lower case; a key a sequence or a phase does not take; a clip or a one_handed_overlays in sequence.defaults; a hold_last_frame that is not true or false; an overlays or one_handed_overlays that is not a list; variants on any phase but attack; an action named attack_1 or ending in _one_handed in a sequenced item (keep variants and one_handed inside the phase); a sequence on empty_hand. The full list is Things that drop a whole file. In Punchy! Studio the line under the raw JSON says The game drops this file, or what is wrong with the JSON, before you export.
• The draw is too quick or too slow. The clip follows how long you hold the use button, not its own length. Change charge_ticks.
• The arms jump when a phase starts. Raise transition_seconds for that phase.
• over_idle does nothing. It is ignored on equip and idle, it needs an idle clip, and "true" in quotes is text, which is ignored.
• An overlay on an arm does not show. An overlay’s bones list matches root, waist, head and body. A name with an underscore, such as right_arm, never matches, so let the phase’s own clip move the arms.
• A crossbow has no sequence. It has its own crossbow action.
• Nothing plays in game. Check that the pack is on, that the example pack provided by Crafto is off while you test, that the clip names are spelled exactly as in the animation file, and that you pressed F3+T after the last edit. Why a clip does not play has the rest.

Related pages

• Compat files is the whole reference, with Sequences for every phase and behavior.
• Camera and features lists the sequence keys among the held-item actions.
• Create an animation makes the clips this recipe wires up.
• Animation files explains what a clip file holds and how Moves finds a clip.
• Punchy! Studio for Moves covers the Bindings workspace.
• Other recipes: walk cycle, emote, riding and swimming.