Compat files

A compat file is a small JSON file in a resource pack that tells Punchy! Moves which clip to play for each moment: walking, jumping, swinging a sword, drawing a bow, riding a boat, waving from the emote wheel. You write one when you have clips and want them to play, or when you want to change how a pack blends them. This page is the whole reference, with a working example for every action. The excerpts come from the example pack provided by Crafto, Fluid & Foolish, which is also the pack behind the clips on this page.

Before you start

• Punchy! Moves installed. See Getting started.
• A resource pack with animation files in assets/punchy_moves/animations/. A compat file only names clips, it does not hold them. See Animation files and Create an animation.
• Names that start with my_ in the examples are placeholders. Replace each one with the name of a clip from your own animation files, spelled exactly the same.

Write your first compat file

This file gives a pack walking, sprinting, jumping, landing, a punch combo, a sword combo and one emote. You can copy it as it is and swap the clip names.

Video coming soon

If a clip does not play, the name is usually spelled differently in the animation file. Nothing in the game warns about that, so see Why a clip does not play.

How the game reads the files

• Which files. Every .json file under assets/punchy_moves/compat/ of each active pack, subfolders included. The file name does not matter, and the file must be a JSON object.
• In what order. All the files of all active packs are put in one list and read in the order of their paths, as text: compat/a_base.json before compat/b_extra.json. The order of your packs does not decide it. Name a file later in the alphabet to let it override an earlier one.
• How they combine. Files merge key by key. A later file that sets only falling.normal replaces that one clip and keeps the fall distances an earlier file set. Lists add up across files: the emotes, the riding rules, the biome rules and the variables. For riding and biome rules, the last rule that matches wins.
• Same path in two packs. When two active packs have a file at the same path, only the higher pack’s copy is read.
• Animation files come after. Once every compat file is read, the animation files load, also in the order of their paths. If two animation files define the same clip name, the one read later wins.
• A format error drops the whole file. One key the format does not accept makes the game skip the entire file. The game’s log gets a line that starts with Could not load animation compat, then the file’s id and the field’s path. The sentence that follows the path is usually written in Portuguese, so read the path and compare it with this page.
• A name with no clip plays nothing. A clip name that no animation file defines simply does not play, and nothing says so. A rule that is only skipped, such as a riding rule with no entities, writes no log line either.
• Comments get through. The game’s JSON reader is more lenient than most, so a comment may load. Keep your files plain JSON anyway, because other tools reject comments.

Press F3+T after every edit. The game rebuilds its animation library as soon as the resource packs reload.

The root of a file

A format 2 file takes these keys at the top and no others.

Which level wins

For a held item, Moves looks at the exact item first, then its item group, then defaults. For an empty hand it looks at empty_hand, then defaults. Clips, numbers and text settings each resolve on their own through those levels, so an item can set one setting and take everything else from its group or from defaults. Overlays, blends and timers are different: they come whole from the first level that has them, and are not merged.

For an empty hand, empty_hand is read for clips, text settings, retrigger_progress, locomotion_influence, base_pose_retain, blends and timers. Overlays and other numbers come from defaults only.

Body actions are read from defaults only. walking, jump, falling, swimming, riding, biomes, emotes and every other moment that is not about the held item go in defaults.animations. Writing them in an item group changes nothing.

This is the attack setup of the example pack provided by Crafto, trimmed. A sword plays its own combo, a pickaxe swings the pickaxe clip, a hoe has no attack of its own and falls back to defaults, and bare hands punch:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "attack": { "variants": ["sword_attack_1", "sword_attack_2"], "retrigger_progress": 30 }
    }
  },
  "empty_hand": {
    "animations": {
      "attack": { "clip": "punch", "retrigger_progress": 65 }
    }
  },
  "item_groups": {
    "SWORD": {
      "animations": {
        "attack": { "variants": ["sword_attack_1", "sword_attack_2"], "retrigger_progress": 10 }
      }
    },
    "PICKAXE": {
      "animations": {
        "attack": { "clip": "pickaxe_attack", "retrigger_progress": 30 }
      }
    }
  }
}

To give one exact item its own clip, put it under items, which beats the group:

{
  "format_version": 2,
  "items": {
    "minecraft:diamond_sword": {
      "animations": { "attack": "my_diamond_slash" }
    }
  }
}

Actions and their values

animations maps an action name to its value. The value is a clip name, or an object. In this file idle is a clip name, attack is an object with variants and mining is an object with a clip and a setting:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "idle": "my_idle",
      "attack": { "variants": ["my_punch_1", "my_punch_2", { "clip": "my_punch_3" }] },
      "mining": { "clip": "my_mine", "locomotion_influence": 0.5 }
    }
  }
}

• clip names the clip. variants lists several. An action has clip or variants, never both, and variants must not be empty.
• For attack, variants play as a combo, in order. Outside a sequence they go back to the first clip after a pause of one second (20 ticks) or when you change item. Inside a sequence the pause is 1.5 seconds (30 ticks).
• Outside a sequence a variant can only be a clip name or an object with just clip. Settings per variant belong to attack in a sequence.
• An action name starts with a lower case letter and then holds lower case letters, digits and underscores. Any other name, a capital letter included, drops the file. A name that is spelled right but that the game does not know plays nothing.
• An array as the value is only for biome, passenger_state and sitting_state, where each element is its own rule. Anywhere else it drops the file.
• one_handed: "<clip>" gives the action another clip for when your other hand holds something. See Left hand and one-handed clips.

The sections below group the actions by what they react to. Every example is a complete file, so you can save it as it is and swap in your own clip names. The action you are reading about sits inside defaults.animations, unless the example says otherwise.

Standing and moving

These actions go in defaults.animations.

idle

The standing loop. It plays while you stand still and fades out as you start to walk. The value is a clip name.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "idle": "my_idle"
    }
  }
}

walking

The walk and the sprint, in four directions. The forward, backward, left and right clips follow the movement keys you hold and are eased from one to the next, so a direction never snaps when a key changes. One direction plays at a time: forward or backward while you hold either of those keys, otherwise left or right.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "walking": {
        "directions": {
          "forward": "my_walk_forward",
          "backward": "my_walk_backward",
          "left": "my_sidestep_left",
          "right": "my_sidestep_right",
          "sprint": { "forward": "my_run_forward" }
        }
      }
    }
  }
}

The walk clips cycle once for each stride_blocks_per_cycle blocks you cover, never faster than max_cycles_per_second. At the default numbers an ordinary walk, sprint or sneak already reaches that limit, so to make the legs step faster or slower at an ordinary pace, change max_cycles_per_second (or the sprint’s and the crouch’s). The stride only matters when you move slowly.

To make the size of the steps follow your speed too, set amplitude_reference_speed. Here a walk is full strength at 0.215 blocks per tick, a sprint can swing up to 20 percent wider, and a sprint gets an extra clip on top:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "walking": {
        "directions": {
          "forward": "my_walk_forward",
          "sprint": { "forward": "my_walk_forward" }
        },
        "amplitude_reference_speed": 0.215,
        "max_amplitude": 1.2,
        "sprint_overlay": "my_sprint_add"
      }
    }
  }
}

Walking candidates

A direction can be a list of candidates, so the walk changes with your speed or with crouching. Each candidate has a clip, and may have a when (an expression that must hold), a weight (an expression for how strongly it plays), reverse and add. A missing when always holds, a missing weight is 1, and a candidate whose weight is 0.0001 or less drops out. A candidate with no clip is skipped.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "walking": {
        "directions": {
          "forward": [
            { "clip": "my_walk", "weight": "1 - crouch_modifier" },
            { "clip": "my_sneak", "when": "crouch_modifier > 0" }
          ]
        }
      }
    }
  }
}

Candidates can also crossfade clips by speed. The weights overlap, so each clip fades in as the last fades out. Here a slow clip gives way to a walk clip as you speed up:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "walking": {
        "directions": {
          "forward": [
            {
              "clip": "my_slow_forward",
              "when": "limb_speed <= 0.30",
              "weight": "1 - smoothstep(0.12, 0.30, limb_speed)"
            },
            {
              "clip": "my_walk",
              "when": "limb_speed <= 0.55",
              "weight": "smoothstep(0.12, 0.30, limb_speed) * (1 - smoothstep(0.25, 0.55, limb_speed))"
            }
          ]
        }
      }
    }
  }
}

Candidates read limb_speed, crouch_modifier, sprint_weight, rare_run, sprint_elapsed, locomotion_phase, stride_distance, forward, backward, left, right and direction_weight. The expressions section says what each one is.

Two more keys work on a direction in its object form, and on each candidate. They work on forward, backward, left, right, on directions.sprint.forward and on each crawling direction.

• reverse (true or false, false when left out) plays the clip backward on the walk’s clock at the same pace, so one forward walk can also be the backward walk.
• add names an extra clip, as text, that plays with the direction’s clip on the same clock (backward too when reverse is set) and with the same weight, added on top of the walk. Use it for a sway or an accent made as a change from the walk pose. On sprint.forward it is ignored when the sprint uses entry_loop or second_stage.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "walking": {
        "directions": {
          "forward": { "clip": "my_walk_forward", "add": "my_walk_sway" },
          "backward": { "clip": "my_walk_forward", "reverse": true, "add": "my_walk_sway" }
        }
      }
    }
  }
}

The example pack provided by Crafto plays one forward cycle and lets amplitude_reference_speed scale it. The backward walk is the forward clip run in reverse, add puts a sway on the forward, backward and sprint walks, and sprint_overlay adds the sprint on top. The sidesteps keep their own clips:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "walking": {
        "directions": {
          "forward": { "clip": "normal_forward", "add": "nf_add" },
          "backward": { "clip": "normal_forward", "reverse": true, "add": "nf_add" },
          "left": { "clip": "sidestep_left" },
          "right": { "clip": "sidestep_right" },
          "sprint": { "forward": { "clip": "normal_forward", "add": "nf_add" } }
        },
        "amplitude_reference_speed": 0.215,
        "max_amplitude": 1.2,
        "sprint_overlay": "sprint_add"
      }
    }
  }
}

Video coming soon

Sprinting

directions.sprint is an object. With forward only, that clip is the sprint loop. For a sprint that changes after a moment, use stages:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "walking": {
        "directions": {
          "sprint": {
            "entry_loop": { "clip": "my_run_in", "duration": 0.5 },
            "second_stage": { "clip": "my_run_loop" }
          }
        }
      }
    }
  }
}

The stages are used only when entry_loop or second_stage gives a clip. Without one of them, forward is the sprint loop. transition and rare_loop do nothing without a stage clip. With sprint_overlay set (see the walking keys above) a sprint plays one forward cycle, so you normally leave the stages out.

run_start and run_stop can also be named directly in defaults.animations. The clips of the sprint’s stages stay in directions.sprint, as shown above. run_stop can also take additive:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "run_start": "my_run_start",
      "run_stop": { "to_idle": "my_run_stop", "to_walk": "my_run_stop", "additive": true }
    }
  }
}

In the example pack, run_stop plays stop_running for both to_idle and to_walk, with additive on.

crawling

The four crawling directions, with the same clip, object or candidates form as walking.directions. Candidates read limb_speed, crouch_modifier (always 1), sprint_weight (always 0), forward, backward, left, right and direction_weight. The other names of the walk are not set while you crawl. The reverse and add keys work here too.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "crawling": { "directions": { "forward": "my_crawl" } }
    }
  }
}

The example pack gives the four directions their own clips:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "crawling": {
        "directions": {
          "forward": { "clip": "crawling_forward" },
          "backward": { "clip": "crawling_backward" },
          "left": { "clip": "crawling_leftward" },
          "right": { "clip": "crawling_rightward" }
        }
      }
    }
  }
}

crouch

The crouch pose, and the clips that go in and out of it.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "crouch": { "clip": "my_crouch", "enter": "my_crouch_in", "exit": "my_crouch_out" }
    }
  }
}

The example pack holds the crouch as one additive pose, 45 percent faster:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "crouch": { "enter": "sneaking", "additive": true, "timer_scale": 1.45 }
    }
  }
}

turn_in_place

When you stand still and look around, your head follows the camera and your body stays. This turns the body with a clip once you have looked far enough. It is off until you set enabled to true, and it stays off unless the left and right clips have tracks for both legs (left_leg and right_leg).

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "turn_in_place": { "enabled": true, "left": "my_turn_left", "right": "my_turn_right" }
    }
  }
}

The clip’s rotation of the root bone around Y decides how the body turns. A clip without that rotation turns the body smoothly over the whole length of the clip, so the body turns as long as the feet step and arrives with the last step. The step_left and step_right clips of the example pack have no root track, so it turns this way. Its turn_in_place sets eight keys:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "turn_in_place": {
        "enabled": true,
        "left": "step_left",
        "right": "step_right",
        "minimum_turn_degrees": 60,
        "look_idle_seconds": 0.25,
        "fade_out_seconds": 0.12,
        "left_overlay": "step_add_left",
        "right_overlay": "step_add_right"
      }
    }
  }
}

Video coming soon

Jumping, landing and falling

These actions go in defaults.animations.

jump

The hop you play when you jump. Sides alternate after each jump, starting on the right.

A sprinting jump tries running first, then moving, then the plain left and right. A walking jump tries moving, then the plain sides, and a standing jump tries idle, then the plain sides. In each family it tries the side that is due, then the other side.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "jump": { "left": "my_jump_left", "right": "my_jump_right" }
    }
  }
}

Give a family its own clips when you want a sprinting hop that differs from a walking jump. Here the sprint has its own pair, and every other jump uses the plain pair:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "jump": {
        "left": "my_jump_left",
        "right": "my_jump_right",
        "running": { "left": "my_hop_left", "right": "my_hop_right" }
      }
    }
  }
}

With a contact clip (landing), the jump clip plays up to the point whose pose is closest to the contact’s first frame, never later than landing_before_seconds, and waits there while you stay in the air. If you land before the jump clip has played landing_before_seconds seconds, the contact plays on top of what plays underneath, at full strength, in place of the landing clips, and the jump stops. Without a contact clip the jump clip plays on and holds its last frame until you land, and the landing clips play. A dive landing never uses the contact.

The example pack provided by Crafto gives the moving and the standing jump a contact clip, and a sprint its own hop:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "jump": {
        "moving": { "left": "jumping", "right": "jumping", "landing": "jump-landing" },
        "idle": { "left": "jumping", "right": "jumping", "landing": "jump-landing" },
        "landing_before_seconds": 0.7,
        "running": { "left": "hoprunning_left", "right": "hoprunning_right" }
      }
    }
  }
}

landing

The landing clip. How hard the landing was, by the distance fallen or the speed on impact, picks light, medium or heavy. Reaching either limit counts.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "landing": { "light": "my_land", "heavy": "my_land_heavy", "heavy_distance": 8 }
    }
  }
}

The example pack plays one squash clip for all three landings, additively, so a soft landing is a small squash and a long fall a full one:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "landing": {
        "light": "squash",
        "medium": "squash",
        "heavy": "squash",
        "additive": true,
        "full_strength_distance": 5
      }
    }
  }
}

falling

The loops that play while you fall a long way.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "falling": { "normal": "my_fall", "free_fall": "my_free_fall", "trigger_distance": 5, "blend_in_response": 1.2 }
    }
  }
}

The example pack writes out every default and sets blend_in_response to 1.2. Here is the same shape with placeholder clip names:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "falling": {
        "normal": "my_fall",
        "free_fall": "my_free_fall",
        "effect": "my_fall_effect",
        "trigger_distance": 5,
        "free_fall_distance": 7,
        "free_fall_velocity": 0.72,
        "effect_distance": 13,
        "effect_velocity": 1.05,
        "blend_in_response": 1.2
      }
    }
  }
}

Gliding and flying

These actions go in defaults.animations.

elytra

The glide with elytra, with a fast version, a layer for turning, and clips for fireworks.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "elytra": { "normal": "my_glide", "high_speed": "my_glide_fast" }
    }
  }
}

The elytra of the example pack provided by Crafto, with its camera:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "elytra": {
        "normal": "elytra_loop",
        "high_speed": "elytra_intense_loop",
        "firework_use": "elytra_use_firework",
        "firework_hold": "elytra_hold_firework",
        "high_speed_threshold": 0.9,
        "bank_degrees": 30,
        "bank_sensitivity": 5,
        "bank_response": 5,
        "camera": { "horizontal": 0.92, "vertical": 0.36, "depth": 3.63, "fov": 70, "response": 3.5 }
      }
    }
  }
}

creative_fly

The pose while you fly in creative mode. clip is the pose (pose is read as the same key), and idle is the base loop under it.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "creative_fly": { "clip": "my_fly" }
    }
  }
}

Water and lava

These actions go in defaults.animations.

swimming

The three swim clips, and how the body sits in the water.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "swimming": { "surface": "my_swim_surface", "underwater": "my_swim_under", "vertical": "my_swim_up" }
    }
  }
}

water_dive

The dive when you jump into water from a height.

A dive needs air (or alternate_air). Without a fall clip nothing plays, whatever contact and loop say.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "water_dive": { "air": "my_dive_in", "loop": "my_dive_loop" }
    }
  }
}

A dive can also pick another set of clips at random. alternate_chance is the chance of the alternate:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "water_dive": {
        "air": "my_dive_in",
        "contact": "my_dive_pose",
        "loop": "my_dive_loop",
        "alternate_air": "my_cannonball",
        "alternate_loop": "my_cannonball_loop",
        "alternate_chance": 0.5
      }
    }
  }
}

Sneaking while you fall picks a tuck instead, once per dive. Sneak within sneak_window_seconds of the start and the dive turns into sneak_air, sneak later and it turns into late_sneak_air. A pack with sneak_air or late_sneak_air always starts the dive as the plain dive, so it needs air, and it never uses alternate_air, alternate_loop or alternate_chance. A tuck plays no contact clip: in the water it keeps its last pose with its own loop. If the tuck you pick has no air clip, the dive stays the plain dive.

Video coming soon

The dive of the example pack provided by Crafto turns into a cannonball when you sneak early and a belly flop when you sneak later:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "water_dive": {
        "air": "dive",
        "loop": "dive_loop",
        "trigger_distance": 3,
        "sneak_air": "cannonball",
        "sneak_loop": "cannonball_loop",
        "late_sneak_air": "belly_flop",
        "late_sneak_loop": "belly_loop",
        "sneak_window_seconds": 0.3,
        "entry_blend_seconds": 0.45,
        "swim_blend_seconds": 0.6
      }
    }
  }
}

lava_dive

The same idea for lava.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "lava_dive": { "pose": "my_lava_pose" }
    }
  }
}

walk_on_water

The pose while you wade through water one block deep, with your head above it. clip is the pose (pose is read as the same key) and idle is the base loop under it.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "walk_on_water": { "clip": "my_water_walk" }
    }
  }
}

Climbing and fences

These actions go in defaults.animations.

climbing

The climb on a ladder, a vine or another climbable block.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "climbing": { "clip": "my_climb" }
    }
  }
}

With one shared clip, going down plays that clip forward, unless timer_effect is vertical_delta, which plays it backward. To use two separate clips, leave climbing.clip and climbing.up out and name the clips with the top-level actions climb_up and climb_down:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "climb_up": "my_climb_up",
      "climb_down": "my_climb_down"
    }
  }
}

The example pack provided by Crafto uses one clip and lets your speed drive it:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "climbing": {
        "clip": "climbing_up",
        "timer_effect": "vertical_delta",
        "timer_scale": 8,
        "camera": { "horizontal": 0, "vertical": 0.11, "depth": 2.34, "fov": 70, "response": 4 }
      }
    }
  }
}

fence

The pose while you stand on a fence. clip is the pose (pose is read as the same key), and camera, the timers and blending work as on other actions. The loop under it is your general idle.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "fence": { "clip": "my_fence_hold" }
    }
  }
}

The fence pose of the example pack also frames the camera:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "fence": {
        "pose": "fence_position",
        "camera": { "horizontal": 0, "vertical": 0.75, "depth": 2.94, "fov": 85, "response": 4 }
      }
    }
  }
}

Riding and sitting

passenger_state, sitting_state and mount_state are three names for the same rule. Use the one that reads best for the vehicle. Each rule names the entities it is for and the clips to play while you ride them. They go in defaults.animations, either as one object or, for passenger_state and sitting_state, as a list of rules. When two rules match, the last one wins.

A rule needs entities and at least one of pose, idle and moving. Otherwise it is skipped.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "passenger_state": [
        { "entities": ["minecraft:boat"], "pose": "my_boat_sit" }
      ],
      "sitting_state": { "entities": ["minecraft:pig"], "pose": "my_sit" },
      "mount_state": { "entities": ["minecraft:horse"], "pose": "my_mount" }
    }
  }
}

The example pack provided by Crafto seats you in any boat, raft or minecart with wildcards, and gives the nautilus its own ride, with a camera and a lean. Its sit_idle loop plays only in minecarts, because that rule has no moving clip and so keeps the loop at any speed. Boats and rafts get the sit pose alone:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "sitting_state": {
        "entities": [
          "minecraft:boat", "minecraft:chest_boat", "minecraft:*_boat", "minecraft:*_chest_boat",
          "minecraft:*_raft", "minecraft:*_chest_raft", "minecraft:*minecart"
        ],
        "pose": "sit",
        "idle": "sit_idle"
      },
      "passenger_state": {
        "entities": ["minecraft:nautilus", "minecraft:zombie_nautilus"],
        "idle": "idle_nautilus",
        "moving": "sprint_nautilus",
        "speed_threshold": 0.12,
        "camera": { "horizontal": 0.88, "vertical": -0.65, "depth": 3.91, "fov": 68, "response": 3.5 },
        "dynamics": {
          "rider_vertical_offset": 10,
          "bank_degrees": 28,
          "bank_sensitivity": 1.5,
          "vertical_tilt_degrees": 22,
          "vertical_sensitivity": 4,
          "response": 6
        }
      }
    }
  }
}

The riding recipe builds a rule step by step.

Biomes, idle moments and music

These actions go in defaults.animations.

biome

A pose, or a clip now and then, for the biome you stand in. The value is one rule, or, under biome, a list of rules. biome_animation is read as the same key but takes one rule only. A rule needs pose or event, otherwise it is skipped. When several rules match, the last one wins.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "biome": [
        { "biomes": ["minecraft:desert"], "event": "my_heat_event" }
      ]
    }
  }
}

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "biome_animation": { "pose": "my_snow_pose" }
    }
  }
}

The example pack provided by Crafto has the character shiver in cold biomes, with no biome list, so the temperature does the choosing:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "biome": {
        "temperature_max": 0.15,
        "pose": "cold_effect",
        "pose_layer": "full_body",
        "event": "cold",
        "event_layer": "upper_body",
        "min_interval_seconds": 12,
        "max_interval_seconds": 28,
        "chance": 1,
        "event_while_moving": true
      }
    }
  }
}

idle_events

A clip that plays now and then while you stand still: a stretch, a look around. A timer picks a wait between the two intervals, and then, with chance, plays one of the variants at random, never the same one twice in a row. Moving cancels it.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "idle_events": { "variants": ["my_look_1", "my_look_2"], "chance": 1 }
    }
  }
}

The example pack plays an event every 8 to 15 seconds:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "idle_events": {
        "variants": ["idle_event_one_backup", "idle_event_two_backup"],
        "min_interval_seconds": 8,
        "max_interval_seconds": 15,
        "chance": 1
      }
    }
  }
}

music_listening

Your character listens when a jukebox plays nearby and you stand still.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "music_listening": { "loop": "my_listen", "source": "active_jukebox" }
    }
  }
}

The example pack sets every key:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "music_listening": {
        "loop": "listening_song",
        "source": "active_jukebox",
        "radius": 12,
        "scan_interval_ticks": 10,
        "start_delay_seconds": 1,
        "movement_stop_delay_seconds": 1,
        "item_hand": "main_hand"
      }
    }
  }
}

cold

A shiver one-shot while you freeze, for example in powder snow.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "cold": { "clip": "my_cold", "trigger_progress": 0.05 }
    }
  }
}

Body state and one-shots

These actions go in defaults.animations.

low_hunger

A loop while your food level is low. It plays for your own player only, and only while you stand still on the ground. Nausea takes the place when both apply.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "low_hunger": { "clip": "my_hungry", "food_level_at_most": 6 }
    }
  }
}

nausea

A loop while you have the Nausea effect. It plays only while you stand still on the ground, and not while you fly in creative, climb, crawl, fall, swim, or dive into water or lava. The value is a clip name.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "nausea": "my_nausea"
    }
  }
}

hurt_forward and hurt_backward

One-shots played on your own player when you are hit. A hit from the front tries hurt_backward first, and any other hit tries hurt_forward first. The other one is the fallback. A hit on another player plays no clip.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "hurt_forward": "my_hurt_front",
      "hurt_backward": "my_hurt_back"
    }
  }
}

armor and armor_helmet

One-shots that play when armor goes on. armor_helmet is for a helmet.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "armor": "my_armor_on",
      "armor_helmet": "my_helmet_on"
    }
  }
}

alignment

A full-body clip for checking a pack. Press G in game and it plays, and a message above the hotbar tells you whether the clip was found.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "alignment": "my_preview"
    }
  }
}

Held-item actions

These actions go in animations of defaults, empty_hand, an item group or an item. With an item in your hand, the exact item wins, then its group, then defaults. With an empty hand, empty_hand wins, then defaults. The clip plays on the arm that does the action, and a clip named <name>_left or <name>_right is played for that arm when it exists. See Left hand and one-handed clips.

attack

The swing when you click. The value is a clip, or variants for a combo that plays in order. It goes back to the first clip after a pause of a second, or when you change item.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "attack": "my_punch"
    }
  }
}

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "attack": { "variants": ["my_punch_1", "my_punch_2"], "retrigger_progress": 60 }
    }
  }
}

It takes retrigger_progress (default 50), locomotion_influence, base_pose_retain, the timers, blending, overlays, one_handed and one_handed_overlays. Each is explained under Settings many actions take. Bare hands use attack in empty_hand. In the example pack provided by Crafto, the fists keep the left arm and the legs where the walk puts them, keep 70 percent of the walk on the head and 35 percent on the body, and let the punch drive the right arm:

{
  "format_version": 2,
  "empty_hand": {
    "animations": {
      "attack": {
        "clip": "punch",
        "retrigger_progress": 65,
        "base_pose_retain": {
          "right_arm": 0, "left_arm": 1, "body": 0.35, "head": 0.7, "right_leg": 1, "left_leg": 1
        }
      }
    }
  }
}

mining

The loop while you hold the attack button on a block. It takes the same settings as attack, with retrigger_progress 50 and a locomotion_influence of 0.15 walking, 0.15 sprinting and 0.2 jumping.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "mining": "my_mine"
    }
  }
}

The example pack gives each tool its own mining clip:

{
  "format_version": 2,
  "item_groups": {
    "PICKAXE": { "animations": { "mining": "pickaxe_mining" } },
    "AXE": { "animations": { "mining": "axe_mining" } },
    "SHOVEL": { "animations": { "mining": "shovel_mining" } },
    "HOE": { "animations": { "mining": "mining_hoe" } }
  }
}

hand_in

The equip clip, played when you change the hotbar slot or get a new item in your main hand. It also takes waist_blend, fence_balance_influence, the timers, blending, overlays, one_handed and one_handed_overlays. Its locomotion_influence is 1 for walking, sprinting and jumping, which means the walk shows fully.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "hand_in": { "clip": "my_equip", "waist_blend": "my_waist" }
    }
  }
}

item_switch and item_change

Clips for swapping hands. item_change plays for each arm that changes. item_switch is the clip used when there is no item_change. The values are clip names, and item_change also reads pose and clip.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "item_switch": "my_swap",
      "item_change": "my_swap_arm"
    }
  }
}

{
  "format_version": 2,
  "item_groups": {
    "PICKAXE": {
      "animations": {
        "hand_in": "tool_item_in",
        "item_change": "tool_item_in"
      }
    }
  }
}

pose

A pose you hold while the item is in your hand. The clip is read from clip, pose or idle.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "pose": { "clip": "my_hold", "pose_duration": 3 }
    }
  }
}

The example pack holds a shovel across the body with both hands, so its arms stay on the pose while you walk (see locomotion_influence). The pose only needs the clip:

{
  "format_version": 2,
  "item_groups": {
    "SHOVEL": {
      "animations": {
        "pose": { "clip": "shovel_pose" }
      }
    }
  }
}

A pose held with one hand is where locomotion_influence matters. The example pack uses a trick for lanterns and torches: a locomotion_influence above 1 is read as percent, so 10 is 0.1, and hand_only keeps that influence to the arm that holds the item, so the rest of the body walks normally:

{
  "format_version": 2,
  "item_groups": {
    "LANTERN": {
      "animations": {
        "pose": {
          "clip": "my_lantern_pose",
          "locomotion_influence": { "walk": 10, "sprint": 10, "jump": 10, "transition": 10, "hand_only": true }
        }
      }
    }
  }
}

idle for an item

An item can have its own idle loop. It plays only when the item or its group declares an idle, so write it under an item group or an item. An idle in defaults is the standing idle for every player, not an item idle. The value is a clip name.

{
  "format_version": 2,
  "item_groups": {
    "SWORD": {
      "animations": {
        "idle": "my_item_idle"
      }
    }
  }
}

useitem and interact

useitem is a general clip for using an item. interact is the first choice for the gesture of using a block. Both take a clip name. If neither clip exists, the attack clip of an empty hand plays.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "useitem": "my_use",
      "interact": "my_interact"
    }
  }
}

In the example pack, interact is a punch, in defaults:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "interact": { "clip": "punch" }
    }
  }
}

eating and drinking

The loops while you eat or drink. The clip is read from clip, pose or looping.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "eating": "my_eat",
      "drinking": "my_drink"
    }
  }
}

{
  "format_version": 2,
  "item_groups": {
    "CONSUMABLE": {
      "static_when_using": true,
      "animations": {
        "eating": { "looping": "eat" },
        "drinking": { "looping": "drink" }
      }
    }
  }
}

crossbow

One object with the five stages of the crossbow.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "crossbow": {
        "charge": "my_xbow_draw",
        "charge_idle": "my_xbow_hold",
        "idle": "my_xbow_idle",
        "charged": "my_xbow_loaded",
        "shoot": "my_xbow_fire"
      }
    }
  }
}

The CROSSBOW group of the example pack is this object with its own clip names (crossbow_charge, crossbow_charged for both the hold while charging and the loaded hold, crossbow_idle and crossbow_shoot).

spear

The charge and the lunge clip of a spear.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "spear": { "charge": "my_spear_hold", "attack": "my_spear_attack" }
    }
  }
}

The spear group of the example pack sets static_when_using too:

{
  "format_version": 2,
  "item_groups": {
    "SPEAR": {
      "static_when_using": true,
      "animations": {
        "spear": {
          "charge": "spear",
          "attack": "spear_lunge_var_1",
          "locomotion_influence": { "walk": 0.15, "sprint": 0.2, "jump": 0.3 }
        }
      }
    }
  }
}

trident

The draw and the throw of a trident, for a trident that has no sequence.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "trident": { "charge": "my_trident_draw", "release": "my_trident_throw" }
    }
  }
}

throwable

The throw clip of a throwable item, for an item that has no sequence. It plays only when the item or its group declares it, so write it under an item group or an item, not in defaults. The key is throw (release is read as the same key).

{
  "format_version": 2,
  "item_groups": {
    "THROWABLE": {
      "animations": {
        "throwable": { "throw": "my_throw" }
      }
    }
  }
}

spyglass_use and shield_pose

Holds for the spyglass and the shield. Each takes a clip name.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "spyglass_use": "my_spyglass",
      "shield_pose": "my_shield"
    }
  }
}

map_view

The pose while you hold a filled map and look down. It plays only for a map in your main hand, and only while the Map third-person camera switch on the Features page is on. The map is not raised while you glide, swim, climb or ride.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "map_view": { "pose": "my_map_look", "look_down_enter": 42, "look_down_exit": 32 }
    }
  }
}

The MAP group of the example pack starts the pose later, holds it until you look higher than 18 degrees below level, and shows no walk through the arms. Its camera spells out the built-in map framing:

{
  "format_version": 2,
  "item_groups": {
    "MAP": {
      "animations": {
        "map_view": {
          "look_down_enter": 55,
          "look_down_exit": 18,
          "locomotion_influence": { "walk": 0, "sprint": 0, "jump": 0 },
          "camera": { "horizontal": 0, "vertical": 0.68, "depth": 1, "fov": 55, "response": 4.5 }
        }
      }
    }
  }
}

Keys of an item group or an item

Two keys sit next to animations in an item group or an item, not inside it.

• static_when_using draws the item you are using as it is held, instead of Minecraft’s own use look. It is also read in defaults and empty_hand. Write true or false, without quotes. A number such as 1 reads as false.
• camera is the camera while a timed pose runs, a pose with a pose_duration above 0, and while you hold a throwable whose group has a throwable sequence.

{
  "format_version": 2,
  "item_groups": {
    "SPYGLASS": {
      "static_when_using": true,
      "animations": { "spyglass_use": "spy_glass_use" }
    },
    "SHIELD": { "static_when_using": false }
  }
}

A timed pose with a camera of its own, on one exact item:

{
  "format_version": 2,
  "items": {
    "minecraft:clock": {
      "animations": { "pose": { "clip": "my_check_time", "pose_duration": 3 } },
      "camera": { "horizontal": 0, "vertical": 0.75, "depth": 2.94, "fov": 85, "response": 4 }
    }
  }
}

sequence and better_combat are the other two, and have their own sections below.

Settings many actions take

Most actions are an object where a clip name would do, and then can take these settings next to clip.

locomotion_influence

How much of the walk, the run and the jump shows on your arms while the action plays. 1 means the walk shows fully, and 0 means the arms follow the action only. The legs, body and head keep the walk. cold is the exception: its value covers the whole body. A number sets walking, sprinting and jumping together. An object sets them one by one.

The other exception is a hold with both hands. A held pose, a crossbow hold, or an attack, mining, spear or trident clip whose last frame turns both arms 20 degrees or more from rest holds the item with both hands. While it plays, the arms keep none of the walk, whatever locomotion_influence says, and the landing, the run stop and the run start leave the arms alone too.

When you do not set it, attack, useitem, idle, map_view, cold and hand_in use 1 for walking, sprinting and jumping. mining uses 0.15, 0.15 and 0.2, pose uses 0.65, 0.75 and 0.65, and crossbow, spear and trident use 0.05, 0.05 and 0.1.

A value above 1 is read as percent, so 50 is 0.5. Every result is held between 0 and 1.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "attack": { "clip": "my_punch", "locomotion_influence": { "walk": 0.5, "sprint": 0.2, "jump": 0.5 } }
    }
  }
}

The sword swing of the example pack provided by Crafto ignores the walk on the arms, so the arms follow the swing:

{
  "format_version": 2,
  "item_groups": {
    "SWORD": {
      "animations": {
        "attack": {
          "variants": ["sword_attack_1", "sword_attack_2"],
          "locomotion_influence": { "walk": 0, "sprint": 0, "jump": 0 }
        }
      }
    }
  }
}

retrigger_progress

A percent of the clip that must play before the next click can start the next swing. 0 lets you start the next at once and 100 waits for the end. It is read for attack, mining, spear, sequence phases and attacks while riding. Other actions ignore it. The default is 50, and 70 for a sequence phase. It resolves on its own through the item, the group and defaults.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "attack": { "clip": "my_punch", "retrigger_progress": 60 }
    }
  }
}

blending

A weight ramp for an action. While the action plays, its weight goes from from to to, then the pose it makes counts that much.

blending works for hand_in, pose, idle, mining, throwable, attack, fence, spear and trident.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "pose": { "clip": "my_hold", "blending": { "from": 0, "to": 1 }, "blending_progression": 0.3 }
    }
  }
}

timer_modifier and timer_condition

A speed factor for the clip’s own clock, and a condition that freezes it. They take expressions, or a plain number and a boolean.

• timer_modifier is the speed factor. Not below 0. It is 1 when left out or when the expression fails.
• timer_condition holds the clock still while it is false.

Both are read for hand_in, pose, idle, attack, mining, throwable, spear, trident and fence. On other actions they are accepted and do nothing. Here the punch runs one and a half times faster, and its clock stops while you sneak:

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "attack": { "clip": "my_punch", "timer_modifier": 1.5, "timer_condition": "!is_sneaking" }
    }
  }
}

Two more timer keys work only on some actions:

• timer_effect is read for climbing, where vertical_delta makes the clip follow your vertical speed.
• timer_scale is read for climbing, crouch and swimming, as a speed factor. It is 1 when left out.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "climbing": { "clip": "my_climb", "timer_effect": "vertical_delta" }
    }
  }
}

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "crouch": { "clip": "my_crouch", "timer_scale": 1.2 }
    }
  }
}

overlays

More clips played over the action. overlays is a list. Anything else drops the file.

In overlays on an action or a sequence phase, a bones list matches the one-word bones: root, waist, head and body. A name with an underscore, such as right_arm, never matches, so leave the arms and the legs to the action’s own clip.

attack, mining, hand_in, pose, idle, throwable, spear and trident overlays never cover the two item bones.

An action takes its overlays from the first level that has any (item, group, then defaults), and the list is not merged with the lists of the levels below. An empty hand reads defaults only: overlays and one_handed_overlays written under empty_hand are not read.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "attack": {
        "clip": "my_punch",
        "overlays": [{ "clip": "my_wobble", "mode": "override", "bones": ["body"] }]
      }
    }
  }
}

one_handed_overlays takes the same list. It is used instead of overlays while the action’s one_handed clip plays, which is when your other hand holds something. Without it, the one-handed clip plays the ordinary overlays. An empty list plays none. The first level that has it (item, group, then defaults) wins, and an action keeps the overlays it started with until it ends. Like overlays it must be a list, anything else drops the file, and it cannot go in sequence.defaults (a sequence phase can take it).

{
  "format_version": 2,
  "item_groups": {
    "AXE": {
      "animations": {
        "attack": {
          "clip": "my_axe_swing",
          "one_handed": "my_axe_swing_one_hand",
          "overlays": [{ "clip": "my_axe_swing_add" }],
          "one_handed_overlays": [{ "clip": "my_axe_swing_one_hand_add" }]
        }
      }
    }
  }
}

The axe of the example pack plays its pickaxe clips and overlays when your other hand is busy.

The bow of the example pack adds a head movement when the arrow is released, in the release phase of the BOW sequence (see Sequences):

{
  "format_version": 2,
  "item_groups": {
    "BOW": {
      "sequence": { "behavior": "bow" },
      "animations": {
        "release": {
          "clip": "bow_shoot",
          "overlays": [{ "mode": "additive", "bones": ["head"], "clip": "bow_shoot_head_movement" }]
        }
      }
    }
  }
}

base_pose_retain

How much of the pose underneath each bone is kept while the action plays. It works for attack, mining and the phases of a sequence, and in no other action. Each entry is a bone name and a number from 0 to 1.

The bones are root, waist, head, body, left_arm, right_arm, left_leg and right_leg. For a left-handed player the game swaps left and right. Any other bone name, a value that is not a number, or a number outside 0 to 1 drops the file.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "attack": { "clip": "my_punch", "base_pose_retain": { "waist": 0.5 } }
    }
  }
}

The trident attack of the example pack keeps the left arm and both legs as the walk puts them:

{
  "format_version": 2,
  "item_groups": {
    "TRIDENT": {
      "animations": {
        "attack": {
          "variants": ["trident_attack_1", "trident_attack_2"],
          "base_pose_retain": { "right_arm": 0, "left_arm": 1, "body": 0.35, "head": 0.5, "right_leg": 1, "left_leg": 1 }
        }
      }
    }
  }
}

waist_blend

A clip that plays on the waist while hand_in, pose or a throw plays. It is a clip name.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "hand_in": { "clip": "my_equip", "waist_blend": "my_waist" }
    }
  }
}

fence_balance_influence

How much of the fence balance shows while hand_in or pose plays. The default is 100, which is full. A value above 1 is read as percent.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "hand_in": { "clip": "my_equip", "fence_balance_influence": 40 }
    }
  }
}

The camera block

A camera is five numbers. Four of them match the Horizontal, Vertical, Depth and Field of View sliders on the Camera page, and response has no slider.

A fence, ladder, elytra, nearby-block or aiming camera needs all five numbers. A block with a missing number, or a response of 0 or less, stays off, and the view keeps your own framing. The map camera is different: a number you leave out takes the built-in value (horizontal 0, vertical 0.68, depth 1, fov 55, response 4.5), and a response of 0 or less counts as 0.1. A riding camera needs horizontal, vertical, depth and fov, and its response is 4 when left out. Camera and features shows what each pack camera frames.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "elytra": {
        "normal": "my_glide",
        "camera": { "horizontal": 0.5, "vertical": 0.1, "depth": 1.4, "fov": 65, "response": 5 }
      }
    }
  }
}

Item groups

Each held item belongs to the first group it matches in this list. Write a group’s key in any case, with or without underscores.

Everything else has no group. The key _ matches those items, so a rule under "_" is the rule for every item with no group.

{
  "format_version": 2,
  "item_groups": {
    "_": { "animations": { "hand_in": "my_general_equip" } }
  }
}

Sequences

A sequence gives an item group or an item a full cycle of phases that Moves runs from what you do: pick the item up, hold it, draw it, release it. The clips of the phases go in animations of the same group or item, under the phase names. Sequences go on item groups and items only, never on empty_hand.

{
  "format_version": 2,
  "item_groups": {
    "BOW": {
      "sequence": { "behavior": "bow", "charge_ticks": 20, "defaults": { "transition_seconds": 0.12 } },
      "animations": {
        "equip": "my_bow_equip",
        "idle": "my_bow_idle",
        "charge": "my_bow_draw",
        "hold": { "clip": "my_bow_hold", "hold_last_frame": true },
        "release": "my_bow_release"
      }
    }
  }
}

Any other key in sequence drops the file.

Anything else on a phase drops the file. sequence.defaults takes only the seven settings listed under Keys of sequence. In a sequenced item, an action named attack_1, attack_2 and so on, or one that ends in _one_handed, drops the file too: keep variants and one_handed inside the action.

The behaviors and their phases

Every behavior plays equip when you pick the item up and idle as its resting loop. The phase names are equip, idle, charge, hold, release, slam, attack, use, cast, fishing and reel. Other actions of the item, such as mining, stay ordinary actions.

The attack phase plays for every behavior except flint and shears. Its variants play as a combo, which goes back to the first clip after 1.5 seconds without a swing.

Each phase has a minimal example:

{
  "format_version": 2,
  "item_groups": {
    "BOW": {
      "sequence": { "behavior": "bow" },
      "animations": {
        "equip": { "clip": "my_bow_equip", "one_handed": "my_bow_equip_one" },
        "idle": "my_bow_idle",
        "charge": { "clip": "my_bow_draw", "locomotion_retain": 0.15 },
        "hold": { "clip": "my_bow_hold", "hold_last_frame": true },
        "release": "my_bow_release"
      }
    }
  }
}

The phases of the other behaviors, in three groups:

{
  "format_version": 2,
  "item_groups": {
    "MACE": {
      "sequence": { "behavior": "mace" },
      "animations": {
        "slam": { "clip": "my_slam" },
        "attack": { "variants": ["my_slash_1", { "clip": "my_slash_2", "transition_seconds": 0.05 }] }
      }
    },
    "FLINT": {
      "sequence": { "behavior": "flint" },
      "animations": {
        "use": { "clip": "my_use", "overlays": [{ "clip": "my_overlay", "mode": "additive" }] }
      }
    },
    "FISHING_ROD": {
      "sequence": { "behavior": "fishing" },
      "animations": {
        "cast": "my_cast",
        "fishing": "my_fishing_idle",
        "reel": "my_reel"
      }
    }
  }
}

And the mace settings, which sit in sequence:

{
  "format_version": 2,
  "item_groups": {
    "MACE": {
      "sequence": { "behavior": "mace", "charge_height": 3, "smash_distance": 1.5 },
      "animations": { "slam": "my_slam" }
    }
  }
}

A bow

This is the bow of the example pack provided by Crafto, trimmed. The defaults set the blend, how much of the walk shows and the retrigger point, and legs_locomotion_retain lets your legs keep walking. The release adds a head movement:

{
  "format_version": 2,
  "item_groups": {
    "BOW": {
      "static_when_using": true,
      "sequence": {
        "behavior": "bow",
        "charge_ticks": 20,
        "minimum_charge_ticks": 3,
        "legs_locomotion_retain": 1,
        "defaults": {
          "transition_seconds": 0.16,
          "locomotion_retain": 0.08,
          "retrigger_progress": 70
        }
      },
      "animations": {
        "charge": { "clip": "bow_charge" },
        "hold": { "clip": "bow_charge", "hold_last_frame": true },
        "release": {
          "clip": "bow_shoot",
          "locomotion_retain": 0.15,
          "overlays": [{ "mode": "additive", "bones": ["head"], "clip": "bow_shoot_head_movement" }]
        }
      }
    }
  }
}

A trident

The trident’s idle holds the last frame of a pose and keeps the left arm as the walk puts it. The attack has two variants, and the second one blends in at once:

{
  "format_version": 2,
  "item_groups": {
    "TRIDENT": {
      "static_when_using": true,
      "sequence": {
        "behavior": "trident",
        "charge_ticks": 10,
        "minimum_charge_ticks": 10,
        "legs_locomotion_retain": 1,
        "defaults": { "transition_seconds": 0.16, "locomotion_retain": 0.15, "retrigger_progress": 70 }
      },
      "animations": {
        "idle": {
          "clip": "spear_pose",
          "hold_last_frame": true,
          "transition_seconds": 0.22,
          "base_pose_retain": { "right_arm": 0, "left_arm": 1, "body": 0.5, "head": 0.7 }
        },
        "charge": { "clip": "trident_charge", "locomotion_retain": 0.08, "moving_legs_influence": 0 },
        "release": { "clip": "trident_throw", "moving_legs_influence": 0 },
        "attack": {
          "variants": ["trident_attack_1", { "clip": "trident_attack_2", "transition_seconds": 0 }],
          "transition_seconds": 0.08,
          "retrigger_progress": 0
        }
      }
    }
  }
}

A mace

This is the mace of the example pack, trimmed. It charges while you fall and slams when you land a hit from high enough. Most phases have a one-handed twin for when your other hand is full. The defaults set over_idle, so every phase other than equip and idle plays on top of the last frame of the idle clip, the raised mace, and does not drop that pose:

{
  "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", "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" }
          ]
        }
      }
    }
  }
}

Flint and steel, and shears

The click plays use. Here moving_legs_influence of 0 lets your legs keep walking while the arms work, and the exclusive overlay on the head takes over the head:

{
  "format_version": 2,
  "item_groups": {
    "FLINT": {
      "static_when_using": true,
      "sequence": { "behavior": "flint", "defaults": { "locomotion_retain": 0.15, "retrigger_progress": 70, "moving_legs_influence": 0 } },
      "animations": {
        "equip": { "clip": "flint_in", "transition_seconds": 0.16 },
        "idle": { "clip": "flint_pose", "transition_seconds": 0.2 },
        "use": {
          "clip": "flint_use",
          "one_handed": "flint_use_alt",
          "transition_seconds": 0.08,
          "retrigger_progress": 0,
          "overlays": [{ "mode": "exclusive", "bones": ["head"], "clip": "flint_use_head" }]
        }
      }
    }
  }
}

{
  "format_version": 2,
  "item_groups": {
    "SHEARS": {
      "static_when_using": true,
      "sequence": { "behavior": "shears", "defaults": { "locomotion_retain": 0.15, "retrigger_progress": 70 } },
      "animations": {
        "equip": { "clip": "shears_intro", "transition_seconds": 0.16 },
        "idle": { "clip": "shears_intro", "hold_last_frame": true, "transition_seconds": 0.22 },
        "use": { "clip": "shears_use", "one_handed": "shears_use_one_handed", "transition_seconds": 0.08, "retrigger_progress": 0 }
      }
    }
  }
}

A fishing rod

{
  "format_version": 2,
  "item_groups": {
    "FISHING_ROD": {
      "static_when_using": true,
      "sequence": { "behavior": "fishing", "defaults": { "transition_seconds": 0.16, "locomotion_retain": 0.15, "retrigger_progress": 70 } },
      "animations": {
        "equip": { "clip": "fishing_rod_intro" },
        "idle": { "clip": "fishing_rod_intro", "hold_last_frame": true, "transition_seconds": 0.22 },
        "cast": { "clip": "fishing_rod_throw", "overlays": [{ "mode": "exclusive", "bones": ["head"], "clip": "fishing_rod_throw_head" }] },
        "fishing": { "clip": "fishing_rod_cast_fish_torso", "transition_seconds": 0.24 },
        "reel": { "clip": "fishing_rod_cast", "overlays": [{ "mode": "exclusive", "bones": ["head"], "clip": "fishing_rod_cast_head" }] }
      }
    }
  }
}

Buckets and throwables

The full bucket of the example pack has a two-handed clip and a one-handed clip for each of equip, idle and use. In idle, the one-handed clip is an object, so 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" }
      }
    }
  }
}

A throwable is the same shape, with equip, idle and use, and its overlays can work on the waist:

{
  "format_version": 2,
  "item_groups": {
    "THROWABLE": {
      "sequence": { "behavior": "throwable", "defaults": { "transition_seconds": 0.16, "locomotion_retain": 0.15, "retrigger_progress": 70 } },
      "animations": {
        "equip": { "clip": "throwable_item_in", "overlays": [{ "mode": "exclusive", "bones": ["head", "waist"], "clip": "throwable_item_in_waist_movement" }] },
        "idle": { "clip": "throwable_item_pose" },
        "use": { "clip": "throw_throwable", "transition_seconds": 0.12 }
      }
    }
  }
}

Video coming soon

The item sequence recipe builds one from nothing.

Cameras

A pack can frame the camera for some moments. cameras is a root key and takes proximity and aiming only. Any other key drops the file. Each holds a camera block (see The camera block).

aiming takes a camera. It is the camera while you draw a bow, hold a loaded crossbow or hold a throwable, and for a timed held pose, when the item has no camera of its own. It needs the Bow and crossbow camera switch on the Features page. It also frames charging a spear or a trident, and that uses the Spear and trident camera switch instead.

The cameras of the example pack provided by Crafto, with the nearby-block timings written out:

{
  "format_version": 2,
  "cameras": {
    "proximity": {
      "camera": { "horizontal": 0.44, "vertical": 0.33, "depth": 2.85, "fov": 80, "response": 4 },
      "instant_distance": 1,
      "enter_distance": 2.2,
      "mining_hold_seconds": 2,
      "blend_in_response": 5,
      "blend_out_response": 3.2
    },
    "aiming": {
      "camera": { "horizontal": 0, "vertical": 0.75, "depth": 2.94, "fov": 85, "response": 4 }
    }
  }
}

The other cameras sit inside the action they belong to: elytra, fence, climbing, map_view, a riding rule, and the camera of an item group or item. The Features page has a switch for the fence, ladder, nearby-block, elytra and map cameras. The camera of an item group or item frames a timed held pose and a throwable in your hand, and follows the Bow and crossbow camera switch. A riding rule’s camera has no switch. Camera and features explains which camera wins when more than one applies.

Emotes

The emotes object is a root key. The emote wheel opens on the key you pick, and each emote can have a key of its own.

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

• Key names. The name is lower cased and given the prefix key.keyboard., so H is key.keyboard.h and F7 is key.keyboard.f7. A mouse button needs its full name, such as key.mouse.left. A name the game does not know leaves the emote with no key. The word unknown does the same.
• In the controls. Players can change every emote key under Punchy Moves in the key binds. Each is listed as Emote: followed by its display name, for example Emote: Wave. The game sets an emote’s key the first time it sees the emote. A later change to keybind in a reloaded pack does not override a key that is already set.
• The wheel’s key is created once per session. A later reload with another menu_key does not move it until you restart the game.
• When an emote plays. Only while you stand still on the ground. Moving cancels it, and a press made while you move is dropped, not queued. It is also dropped while you are using an item, swinging or mining, or any other action clip is playing.
• Who sees it. Only you. Emotes are not sent to other players.

The example pack provided by Crafto has four emotes. The last one plays its music listening loop as a dance:

{
  "format_version": 2,
  "emotes": {
    "menu_key": "C",
    "entries": [
      { "id": "hello", "display_name": "Hello", "animation": "hello_nleg", "keybind": "H" },
      { "id": "hello_b", "display_name": "Hello B", "animation": "hello_nlegB", "keybind": "J" },
      { "id": "hello_with_legs", "display_name": "Hello With Legs", "animation": "hello_wleg", "keybind": "K" },
      { "id": "dance_emote", "display_name": "Dance", "animation": "listening_song", "keybind": "L" }
    ]
  }
}

The emote recipe goes through it step by step, and Keys and emotes covers the wheel itself.

Better Combat

With Better Combat installed, a better_combat block gives its attacks your pack’s clips. It goes in defaults, an item group or an item. Timing belongs to Better Combat here, so the block takes no retrigger_progress.

{
  "format_version": 2,
  "defaults": {
    "better_combat": {
      "attacks": ["my_slash_1", { "clip": "my_slash_2", "impact_time": 0.25 }],
      "animations": { "bettercombat:one_handed_slash_horizontal_right": "my_slash_wide" },
      "transition_seconds": 0.08
    }
  }
}

How the game looks for an attack:

• It looks at the item, then its group, then defaults, and uses the first rule that gives an attack for the swing. A rule that is switched off with enabled: false stops the search. A rule with no attack for this swing passes it on to the next level. The levels do not merge field by field.
• The player’s Better Combat pack attacks setting on the Features page of Moves’ settings (F7) has the last word. It offers Automatic, On and Off, one click cycling to the next, and shows Automatic as Automatic (ON) or Automatic (OFF) for what it resolves to. Automatic plays pack attacks only when the pack has Better Combat clips, On always plays them and Off never does.
• An unknown key in the block, in an attack object or in an overlay, a number written as text, an impact_time of 0 or less, an attack or overlay without a clip, an id without a namespace, or a transition_seconds or locomotion_retain outside 0 to 1 drops the whole file.

Here is a sword with a three-step combo, with the second step landing a little late:

{
  "format_version": 2,
  "item_groups": {
    "SWORD": {
      "better_combat": {
        "attacks": [
          "my_slash_1",
          { "clip": "my_slash_2", "impact_time": 0.3 },
          { "clip": "my_slash_3", "transition_seconds": 0.05, "locomotion_retain": 0.2 }
        ]
      }
    }
  }
}

And two small ones: pack attacks off for an item, and a changed blend:

{
  "format_version": 2,
  "items": {
    "minecraft:diamond_sword": {
      "better_combat": { "enabled": false }
    }
  }
}

{
  "format_version": 2,
  "defaults": {
    "better_combat": { "transition_seconds": 0.08, "locomotion_retain": 0.0 }
  }
}

Expressions and variables

Some fields take a small expression instead of a number: a walking candidate’s when and weight, timer_modifier, timer_condition, blending_condition, blending_modifier, and the members of variables. An expression is read as text, such as "limb_speed <= 0.30".

• Operators. + - * /, %, the comparisons < <= > >= == !=, &&, ||, !, a minus sign in front of a value, and brackets. A division or a remainder by zero gives 0.
• Constants. true, false and pi. A true value is 1 and a false value is 0 inside an expression.
• Functions. sin(x) and cos(x) in radians, abs(x), sqrt(x) (never below 0), round(x), random(x), min(a, b), max(a, b), clamp(x, low, high), smoothstep(edge0, edge1, x) and lerp(t, a, b). Up to three arguments are read and any a function does not need are ignored. Too few arguments, more than three, or a function the game does not know makes the expression fail.
• Names are not case sensitive. There is no Molang and no a ? b : c.
• A failed expression falls back to the field’s default: when counts as true, weight as 1, and the timers and blends as their default.

Walking, crawling and sprint candidates read these names in when and weight:

Crawling candidates read only limb_speed, crouch_modifier (always 1), sprint_weight (always 0), forward, backward, left, right and direction_weight. A candidate’s when can also be written condition or blending_condition, and its weight can be written effect or blending_effect.

Variables

variables is a root list of objects. A member named var.<name> holds a number expression, and a member named varb.<name> a switch expression. Other members of the object are ignored.

{
  "format_version": 2,
  "variables": [
    { "var.swing": "sin(limb_speed * 10) * 0.5", "varb.sneaky": "is_sneaking" }
  ]
}

• A name is lower cased. Read it as var.swing or varb.sneaky in timer_modifier, timer_condition, blending_condition, blending_modifier and in other variables. A walking candidate’s when and weight cannot read variables.
• Variables are worked out once every tick, in the order they are written, and can read the ones above them. A variable that reads one further down sees last tick’s value.
• A variable that is part of a loop, or depends on one, is never worked out. It stays at 0, or false for a switch.
• A variable whose text does not read as an expression is 0, or false.
• Variables from every file are added together.

Here a variable speeds the punch up when you sprint, and the punch clip’s clock reads it:

{
  "format_version": 2,
  "variables": [
    { "var.hurry": "1 + is_sprinting * 0.5" }
  ],
  "defaults": {
    "animations": {
      "attack": { "clip": "my_punch", "timer_modifier": "var.hurry" }
    }
  }
}

Left hand and one-handed clips

• For the arm that does an action, Moves plays <clip>_left or <clip>_right when that clip exists, and the plain name when it does not. Name the pair my_punch_left and my_punch_right and write "my_punch" in the compat file. Held-item and attack clips are not mirrored for you. Only the music_listening loop and the map pose are mirrored for a left arm.
• one_handed picks another clip while your other hand holds something. It takes a clip name on any action. On a phase of a sequence it can be an object with its own settings. Moves keeps a phase’s one-handed clip under the name <phase>_one_handed. You do not write that name yourself: an action with that name in a sequenced item drops the file.
• The game finds an action’s one_handed by trimming the action name one part at a time, so one_handed on attack covers the combo clips of attack_1 and attack_2 as well.
• A body action remembers its clip name for the whole pack, so any other action that plays the same clip is swapped to that clip’s one-handed version too. Give each action its own clip name when their one_handed clips differ.
• one_handed_overlays is a list of overlay objects, like overlays, used instead of overlays while the action’s one_handed clip plays. Without it, the one-handed clip plays the ordinary overlays. An empty list plays none. Like overlays, the first level that has it (item, group, defaults) wins, and an action keeps the overlays it started with until it ends. A sequence phase takes it too, but sequence.defaults does not. See overlays for an example.

{
  "format_version": 2,
  "defaults": {
    "animations": {
      "attack": { "clip": "my_punch", "one_handed": "my_punch_one" }
    }
  }
}

Older files

A file without format_version is read in the older layout, which has default_animations as a list of entries with a type, emptyHand.customAnimation, item.<GROUP> and itemSpecific.<id>. Older packs keep working. A file in the older layout cannot use the keys of format 2: if it has defaults, item_groups, items, empty_hand, cameras or emotes and no format_version, the game drops it. Punchy! Studio opens both kinds and keeps an older file exactly as it is until you change it. Write new files in format 2.

Things that drop a whole file

One of these makes the game skip the entire file, with a Could not load animation compat line in the log. Punchy! Studio’s Bindings workspace marks the member that does it, and its Verdict says The game drops this file.

• The file is not valid JSON, or its top level is not an object.
• format_version is anything but 2 or "2", or the keys of format 2 appear in a file without it.
• A root key outside the list above, a key cameras does not take, a key defaults, an item group or an item does not take, or a key in empty_hand other than animations, static_when_using, camera and better_combat (those last two are accepted there and do nothing).
• An action name that is not lower case letters, digits and underscores starting with a letter, or one that starts with sequence_ or is item_sequence.
• clip and variants together, an empty variants, or settings inside a variant outside a sequence attack.
• type, name, start_at_end or var_<n> on an action. Those belong to the older layout.
• An array as the value of any action but biome, passenger_state and sitting_state.
• hold_last_frame or an object one_handed outside a sequence phase, or a hold_last_frame that is not true or false.
• base_pose_retain on any action but attack, mining and sequence phases, a bone name it does not know, or a value that is not a number from 0 to 1.
• A sequence on empty_hand, a behavior that is not one of the eight in lower case, an unknown key in sequence, in sequence.defaults or in a phase, variants on a phase other than attack, or an action named attack_<n> or ending in _one_handed in a sequenced item.
• overlays or one_handed_overlays that is not a list, or one_handed_overlays inside sequence.defaults.
• turn_in_place with only one of left and right, with a left, right, left_overlay or right_overlay that is an object or empty text, with an unknown key, or with an enabled that is not true or false.
• An unknown key in a better_combat block, in an attack object or in an overlay, a number written as text there, an impact_time of 0 or less, an attack or overlay without a clip, a Better Combat id without a namespace, an enabled that is not true or false, or an overlay mode there that is not additive, override or exclusive.

Video coming soon

Why a clip does not play

The game does not warn about most of these, so go down the list.

• The name is spelled differently. A clip name that no animation file defines plays nothing, and an emote with such a clip is left out of the wheel. Copy the name from the animation file.
• The file was dropped. Open the game’s log and search for Could not load animation compat. The field’s path after the file name tells you where to look. The sentence after it is usually in Portuguese.
• The pack did not reload. Press F3+T after every edit, and check the pack is turned on. If two packs have a file at the same path, only the higher pack’s copy is read.
• A body action sits in an item group. walking, jump, falling, swimming, crouch, riding rules, biomes and the other body actions are read from defaults only.
• An item id has no namespace. Write minecraft:trident under items, not trident.
• The item is in another group. Each item belongs to the first group it matches, so a milk bucket is CONSUMABLE and not a bucket.
• A later file overrode it. Files read later win for a single key. Look at the file names in the folder: they are read in the order of their paths.
• The animation file did not load. An animation file with a mistake in its JSON is skipped without a message, and its clips are missing.
• The two sides are missing. The game plays <clip>_left and <clip>_right for an arm when they exist. When only one exists, the other arm plays the plain name.
• Better Combat is on Automatic. With the Better Combat pack attacks setting on Automatic, pack attacks play only when the pack has Better Combat clips.
• An emote does not start while you move. Emotes need you to stand still on the ground. A press is also dropped while you use an item, swing or mine, or any other action clip plays.

Related pages

• Animation files holds the clips that a compat file names.
• Create an animation makes a clip from nothing.
• Camera and features shows what the pack cameras frame and how the switches work.
• Keys and emotes covers the emote wheel and the keys.
• Punchy! Studio for Moves edits compat files in the Bindings workspace.
• Faces in packs and clips explains the face an emote plays.
• Recipes that build on this page: walk cycle, emote, item sequence, riding and swimming.
• Troubleshooting lists more things that go wrong.