Flags reference

This is the lookup page for Punchy! 3.0. The flags and tokens that Punchy! acts on in its settings, compat files, tuning profiles, clip files, model part definitions, particles and physics sit in the tables below, with the file each goes in, its default and a link to the page that teaches it. The keys of a geometry file are on Geometry and textures. Use it when you know what you want to switch and need the exact spelling, or when a pack acts in a way you did not expect and you want to check a key.

It is for pack makers who write JSON by hand, and for Punchy! Studio users who want to know what a field writes. A flag is a key in a JSON file. A token is a short word inside a clip’s timeline.

Before you start

• This page was checked against Punchy! 3.0 for Fabric on Minecraft 26.3. A key that works on only some versions says so in its row.
• You need a resource pack to put files in. If you have none, start with Resource packs.
• A key that works only with another mod says so in its row. These are Better Combat and Spatial GUI.

Read the tables

• The heading above a table tells you which file it is for. A Goes in column appears when one flag can sit in more than one place.
• Several names in one cell are usually spellings of the same flag, and any one works. A few cells list related flags instead, such as the four proxy maps or the left and right keep keys. The row says what each does.
• Default is what Punchy! uses when you leave the key out. none means the feature is off or nothing is set.
• Key names and clip names are case sensitive. Timeline tokens are not, because Punchy! lowercases them.
• Punchy! ignores a key it does not know, without a message. When a flag seems to have no effect, check the spelling first.
• A value of the wrong JSON type can make Punchy! drop a whole file. Things that drop a whole file lists them.
• A name in angle brackets, such as <id>, stands for text you choose.

Try a few flags

This pack uses flags from several of the tables below. It makes sword swings alternate between two clips, plays a critical hit with the second clip, adds an inspect clip, and swings the sword like a pendulum.

The clip file:

{
  "animations": {
    "flag_swing_1": {
      "animation_length": 0.6,
      "bones": {
        "right_arm": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.2": [-70, 0, 0],
            "0.45": [35, 0, 0],
            "0.6": [0, 0, 0]
          }
        }
      },
      "timeline": {
        "0.0": "use_keyframes_v2;anim_speed_1;blend_from_current_origin;keep_arm_tuning;sync_walk_arms;"
      }
    },
    "flag_swing_2": {
      "animation_length": 0.6,
      "bones": {
        "right_arm": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.2": [-50, 25, 0],
            "0.45": [30, -20, 0],
            "0.6": [0, 0, 0]
          }
        }
      },
      "timeline": {
        "0.0": "use_keyframes_v2;anim_speed_1.5;blend_from_current_origin;"
      }
    },
    "flag_inspect": {
      "animation_length": 1.2,
      "bones": {
        "right_arm": {
          "rotation": {
            "0.0": [0, 0, 0],
            "0.5": [-20, 40, 15],
            "1.2": [0, 0, 0]
          }
        }
      },
      "timeline": {
        "0.0": "use_keyframes_v2;anim_speed_1;dual_handed;hide_offhand_if_empty;",
        "0.9": "show_offhand_if_empty;"
      }
    }
  }
}

The rule file:

{
  "item": {
    "SWORD": {
      "disable_sprint_lateral_tilt": true,
      "disable_mining_animation": true,
      "physics": { "name": "FORWARD_PENDULUM", "limitDeg": 25.0, "speed": 8.0 },
      "customAnimation": [
        {
          "type": "attack",
          "var_1": "flag_swing_1",
          "var_2": "flag_swing_2",
          "critical_hit": "flag_swing_2",
          "skip_blend_out": true,
          "customFlags": { "movement_influence": 40 }
        },
        { "type": "inspect", "name": "flag_inspect" }
      ]
    }
  }
}

What each flag does here:

• In the clip file. use_keyframes_v2 picks the V2 layout. anim_speed_1 plays the clip at the speed you drew it, and anim_speed_1.5 plays the second swing a half faster. blend_from_current_origin starts the blend from where the arm is now. keep_arm_tuning keeps your Hand Editor offsets during the swing. sync_walk_arms lets the walk arm motion follow the clip. dual_handed makes the inspect clip move both arms, and hide_offhand_if_empty and show_offhand_if_empty hide an empty off hand for most of it.
• In the rule file. disable_sprint_lateral_tilt stops the sideways tilt while you sprint. disable_mining_animation makes a sword swing at a block play the attack clips. physics sets the pendulum. var_1 and var_2 are the combo, and critical_hit is the clip for a critical hit. skip_blend_out cuts out of the clip without a blend out. movement_influence keeps 40 percent of Punchy!‘s own walk motion on the arm.

In Punchy! Studio, hover any field in the Properties tabs of the Model workspace. The tooltip names the JSON key it writes and the other spellings Punchy! accepts.

A model part definition uses the same idea. This one is the lantern from Model part definitions, with a bone physics spec and a particle that fires while you walk. The geometry, the texture and the clip file are the ones on that page. Save this definition as assets/minecraft/punchy/model_parts_items/definitions/lantern.json, beside the geo, textures and animations folders that page builds.

{
  "items": ["minecraft:lantern"],
  "geo": "minecraft:punchy/model_parts_items/geo/lantern.geo.json",
  "texture": "minecraft:punchy/model_parts_items/textures/lantern",
  "animations": [
    "minecraft:punchy/model_parts_items/animations/lantern.animation.json"
  ],
  "modelPartsAnimation": [
    { "type": "idle", "name": "lantern_sway" },
    {
      "type": "idle",
      "name": "lantern_still",
      "inside_water": true,
      "disable_all_particles": true,
      "skip_blend_in": true,
      "skip_blend_out": true
    },
    { "type": "attack", "name": "lantern_swing" }
  ],
  "bone_emission": { "strength": 100, "blur": true, "flame": 100 },
  "bone_physics": {
    "flame": { "pendulum_mode": "forward", "limit_deg": 25 }
  },
  "particles": [
    {
      "type": "minecraft:smoke",
      "bone": "flame",
      "rate": 3,
      "life": 1.5,
      "triggers": { "walking": true }
    }
  ]
}

Here items, geo, texture and animations name the files. Each modelPartsAnimation entry picks a clip for a moment, and the second one cuts to a still clip under water with no blend and no particles. bone_emission makes the flame bone glow with a halo. bone_physics lets the flame swing forward. The particle releases three times a second while you walk. Every key has a row below.

Which setting wins

When two keys or two files disagree, this table says which one Punchy! uses.

Settings that switch features

These keys live in config/punchy/punchy_config.json, and each has a row in the Punchy menu you open with F8. They switch whole features on or off for the player. A pack cannot set them. They are here because several flags below act only while one of them is on.

Rows over a disable key read the other way round in the menu. Enable Item Physics is on when disableNativeItemPhysics is false, Resource Pack Movement is on when disableNewKeyframeMoves is false, and Resource Pack Model Parts is on when disableResourcePackModelParts is false.

Mix Packs choices

Your choices on the Mix Packs tab of the Punchy menu are stored in punchy_config.json, and each setup you save is a file at config/punchy/mix_profiles/<name>.json with the same three keys. A pack cannot set them. Mix the packs shows the tab and how Punchy! decides.

Punchy! applies the loaded setup again at each resource reload and when the game starts, so a pick you make after loading or saving a setup goes back to that setup’s choices on the next reload. To keep a pick, save the setup again under the same name with Save as…, or pick Current choices in the setup list before you change a row.

Compat files and tuning profiles

A compat file is a JSON file at assets/minecraft/punchy/compat/<name>.json (or assets/punchy/compat/<name>.json) in a resource pack. A tuning profile is the file the Hand Editor saves in config/punchy/profiles/. Both use the same keys, so everything in this section works in either. Compat rules teaches the files, and Tuning editor and debug teaches the editor.

Root keys

A side set is an object with a right and a left pose.

Poses

A pose places something. It sits inside a side set, in transforms, armTransforms, globalItem, globalArm, armMesh and the proxy maps.

Entries for kinds, groups and items

These keys go in an entry of item (a kind, a custom group or a pattern), in an entry of itemSpecific, or in emptyHand. The Goes in column says which.

Flags that tune or switch off a moment

The Goes in column says where each flag can sit. pose means inside a pose, for one hand. All of them default to false or not set.

A pose reads its keep flags differently from an entry. In a pose, keep_arm_tuning is used when it is written. Only when it is missing does the pose take keep_arm_tuning_l, and then keep_arm_tuning_r, and it takes them for either hand. A right-hand pose that writes only keep_arm_tuning_l therefore gets the left value. Write keep_arm_tuning in a pose, or the same value on both sides.

Physics settings

A physics value in an entry is a mode name alone, an object, or a list. A name alone, such as "physics": "FORWARD_PENDULUM", sets the mode. A list uses the first element that has a name. Write the mode in any letter case, such as FORWARD_PENDULUM or forward_pendulum. The setting keys below are camelCase, such as limitDeg and handSpace, and a snake case spelling such as limit_deg is not read here. Item physics explains each one with examples.

Proxies

A proxy map moves a helper part that Punchy! draws with some held items. Each value is a pose, and only scale, the offsets and the rotations are read. Write the keys in lower case.

Custom animation entries

A customAnimation list says which clip plays at which moment. It sits in an item entry, an itemSpecific entry or emptyHand. The default_animations list at the root takes the same rules for every item. Each element is a rule: a type that names the moment, and keys that name the clip and narrow the moment. Types and triggers teaches them, and Create an animation walks through the first one.

Types

The type of a rule is read after Punchy! lowercases it and drops _, - and spaces, so use_bow, useBow and usebow are one type. mining and mining_v2 are one type too.

The names these types play when no rule gives one are listed on Types and triggers. The keyframe movement types fall back to these clip names:

Keys of a rule

Conditions

These keys go in a rule, and in a variation. Each one that is written must pass. A rule with no conditions always passes them. They are explained on Types and triggers and Compat rules. The same keys are read in the animation entries of a model part, where Conditions has the details.

Custom flags

customFlags is an object inside a rule. It tunes how Punchy!‘s own motion mixes with the clip. It is explained on Types and triggers.

Variations

variations is a list inside a rule. Each variation can swap the clip when the player is in a certain state. Punchy! checks them in list order. A variation counts only when it has a name and every condition it writes passes. The variation with the highest priority wins, a tie keeps the one listed first, and its name replaces the clip names the rule would use.

Hyphens in a state name read as underscores, and letter case does not matter. Any other name is never true.

Clip files

A clip file is a .json file in assets/minecraft/punchy/animations/ of a resource pack. It holds the motion, the timeline tokens and the sounds. Animation reference teaches the format, and Create an animation shows how to make one in Punchy! Studio or Blockbench.

Keys of a clip file

Timeline tokens

A token is an exact word in a timeline string. Several tokens in one string are separated by ;. A token with extra text after it, such as a value after a colon, is a different word and never matches. Tokens that carry an item write its full id after the prefix, for example minecraft:arrow. The Goes in column says where the token is read. In Punchy! Studio, the Events lane of the Dope Sheet holds these tokens. Double-click the lane, or use Key > Insert Event…, to open the token picker. Animation reference explains each token with examples.

Timeline: speed and layout

Timeline: hands and the off hand

Timeline: blending, arm tuning and physics

Timeline: items shown and hidden

Timeline: the item’s own use animation and equip

Model part definitions

A definition is a .json file under assets/<namespace>/punchy/model_parts_items/definitions/, at any depth. It gives an item its own 3D model in first person. Every key below goes at the top of the definition unless the Goes in column says otherwise. Model parts shows how the pieces fit, and Model part definitions teaches the file. The geometry file a definition points to has its own keys (bones, cubes, UV faces, inflate and mirror), and The geometry file lists them.

Items and files

Display

display places the model in your hand. Without it, Punchy! uses the vanilla first person transform of the held item. It is an object with up to four hand entries.

These keys are explained on Model part definitions.

Animation entries

Each element of modelPartsAnimation is an entry. It says: at this moment, in these conditions, play this clip. Item clips teaches them, and Conditions goes through the world checks.

Case, underscores, hyphens and spaces are ignored in a type. When several of these start together, the higher one wins: attack, triggerable, inspect, hand_out, hand_in, mining, the cast and reel of fishingrod, useItem, then useDrink and useEat, then any other type, then idle.

Item clip files

An item clip file is a Bedrock animation file at the id you list in animations. It uses the same shape as a clip file, with these differences: the keys that matter are below, every key is blended linearly, and the bones are the bones of the model’s geometry.

Glow, textures and mirroring

Dynamic textures

dynamic_bone_textures (or dynamicBoneTextures, read only when the first is missing) is one spec or a list of specs. It swaps one bone’s texture, or the whole geometry, by what the held item holds.

Fishing rod keys

Two keys of a definition for minecraft:fishing_rod place the cast line and hide a line that is drawn into the model. Punchy! reads them on every Minecraft version, from the definition that draws the fishing rod in your hand.

This definition, saved as assets/mypack/punchy/model_parts_items/definitions/fishing_rod.json, starts the line at a bone named rod_tip and hides a bone named hanging_line while the hook is out. It needs a geometry file and a texture, which are below.

{
  "format_version": "1.12.0",
  "minecraft:geometry": [
    {
      "description": { "identifier": "geometry.fishing_rod", "texture_width": 16, "texture_height": 16 },
      "bones": [
        {
          "name": "rod",
          "pivot": [0, 0, 0],
          "cubes": [
            {
              "origin": [-0.5, 0, 0.35],
              "size": [1, 9, 1],
              "uv": {
                "north": { "uv": [0, 0], "uv_size": [16, 16] },
                "south": { "uv": [0, 0], "uv_size": [16, 16] },
                "east": { "uv": [0, 0], "uv_size": [16, 16] },
                "west": { "uv": [0, 0], "uv_size": [16, 16] },
                "up": { "uv": [0, 0], "uv_size": [16, 16] },
                "down": { "uv": [0, 0], "uv_size": [16, 16] }
              }
            }
          ]
        },
        {
          "name": "rod_tip",
          "parent": "rod",
          "pivot": [0, 9.5, 0.85],
          "cubes": [
            {
              "origin": [-0.5, 9, 0.35],
              "size": [1, 1, 1],
              "uv": {
                "north": { "uv": [0, 0], "uv_size": [16, 16] },
                "south": { "uv": [0, 0], "uv_size": [16, 16] },
                "east": { "uv": [0, 0], "uv_size": [16, 16] },
                "west": { "uv": [0, 0], "uv_size": [16, 16] },
                "up": { "uv": [0, 0], "uv_size": [16, 16] },
                "down": { "uv": [0, 0], "uv_size": [16, 16] }
              }
            }
          ]
        },
        {
          "name": "hanging_line",
          "parent": "rod",
          "pivot": [0, 9.5, 1.85],
          "cubes": [
            {
              "origin": [-0.25, 3, 1.6],
              "size": [0.5, 6.5, 0.5],
              "uv": {
                "north": { "uv": [0, 0], "uv_size": [16, 16] },
                "south": { "uv": [0, 0], "uv_size": [16, 16] },
                "east": { "uv": [0, 0], "uv_size": [16, 16] },
                "west": { "uv": [0, 0], "uv_size": [16, 16] },
                "up": { "uv": [0, 0], "uv_size": [16, 16] },
                "down": { "uv": [0, 0], "uv_size": [16, 16] }
              }
            }
          ]
        }
      ]
    }
  ]
}

The texture is a 16 by 16 PNG saved as assets/mypack/punchy/model_parts_items/textures/fishing_rod.png. Fill every pixel with one brown such as #8B5A2B; any 16 by 16 picture works.

{
  "items": ["minecraft:fishing_rod"],
  "geo": "mypack:punchy/model_parts_items/geo/fishing_rod.geo.json",
  "texture": "mypack:punchy/model_parts_items/textures/fishing_rod",
  "fishing_line_anchor": { "bone": "rod_tip", "position": [0, 9.5, 0.85] },
  "hide_bones_while_cast": ["hanging_line"]
}

Punchy! Studio has no fields for these two keys and keeps them as written.

Shading rules

assets/<namespace>/punchy/model_parts_items/shading.json sets, by item or texture, how a model part item is lit and whether the particles drawn while it is held blend additively. Punchy! reads this file from every active pack, in any namespace, lowest pack first. For each field the last matching rule wins, so a higher pack can undo a lower one. Geometry and textures teaches glow, and Particles the particles.

The file is an object with a rules list. Each rule names an item, a texture or both, and sets any of the fields below. With both, both must match. A field you leave out is not changed by that rule.

A value is true or false. The text true and false, yes and no, on and off, and 1 and 0 are read too. This file lights a lava bucket in the dark, lights a water bucket evenly, and gives a diamond sword an additive halo:

{
  "rules": [
    { "item": "minecraft:lava_bucket", "fullbright": true },
    { "item": "minecraft:water_bucket", "shading": false },
    { "item": "minecraft:diamond_sword", "additive": true }
  ]
}

Bone physics keys

bone_physics (or bonePhysics, read only when the first is missing) goes in a definition, or in an itemSpecific entry of a compat file. It is an object from bone names to specs, or a list of such objects. Specs for one bone merge. A spec written as just true turns on creature feedback and slime squash for that bone, with no pendulum. A spec is kept only when it has creature feedback, slime feedback or a pendulum mode other than none. A bone with no spec of its own takes the spec of its nearest parent. The key disable_physics_bones (also disable_pendulum_bones, read only when the first is missing) goes at the top of a definition, not inside a spec. It is a list of bone names that lose the item’s physics motion, together with the bones under them. Item physics explains each key with examples.

Particle emitters

An emitter spawns particles from a bone of a model part, or from an item. It is written as a JSON object, as a script string such as type=minecraft:flame,bone=tip,rate=4 (with or without particle(...) around it), or as a bare particle id. Every key below works in all three forms, with the exceptions noted. Particles explains each key with examples and recipes.

Where an emitter starts

A vector is [x, y, z] in an object and x:y:z in a script.

How many and how often

An emitter with no triggers, no rate and no emit_interval releases once per game tick.

Triggers

A pulse trigger is an event, and the emitter releases once for each. A steady trigger is a condition, and the emitter releases on its clock while it is true. By default an emitter needs all of its triggers at once.

Look

Light and glow

In an object, write the short glow names strength, blur and clamp. The long names emissive_strength, emissive_blur, emissive_clamp and their emission_ spellings are read in script strings only.

An additive halo that stays in the model looks like this in a compat file:

{
  "itemSpecific": {
    "minecraft:golden_sword": {
      "particle_emitters": [
        {
          "type": "minecraft:end_rod",
          "texture": "mypack:particle/halo",
          "target": "item_center",
          "size": 0.9,
          "alpha": 0.9,
          "lock_in_model": true,
          "fullbright": true,
          "additive": true
        }
      ]
    }
  }
}

The halo texture is yours to draw: a PNG with a soft bright dot in the middle that fades to black at the edges, saved as assets/mypack/textures/particle/halo.png. A 32 by 32 pixel picture is a good start. Particles says where Punchy! looks for a particle picture.

Punchy! Studio has no field for additive and keeps the key as written.

Space and motion

The mined block

Enchantment variants

enchantment_variants (or enchantmentVariants) goes in an itemSpecific entry of a compat file. Each variant adds particle emitters while the held item has certain enchantments. Nothing else about the item changes. Variants explains them.

A model part definition can carry an enchantment_variants list of its own, with the same enchantments, match and priority keys. There the other keys of each matching variant change the definition itself, in ascending priority: particle lists are added, bone_emission, bone_textures, bone_texture_anim, bone_physics and display merge key by key, and any other key, such as texture, replaces the definition’s. Punchy! 3.0 applies this list only on Minecraft 1.21.11. On other versions it is read and does nothing.

Commands and keys

These are the commands and keys Punchy! adds. A key can be rebound in Options, then Controls, then Key Binds. A pack can also add triggerable keys, which show up in Controls.

Things that drop a whole file

Punchy! checks each file in one go. These mistakes drop a file, or part of it, usually without a message. Punchy! Studio’s lint and Clip > Check for Problems find most of them before you export.

Why a flag has no effect

1. The name is misspelled. Punchy! ignores a key it does not know and says nothing. Compare the spelling and the letter case with the tables above.
2. The flag is in the wrong place. Check the Goes in column. A key in the wrong container is not read.
3. Something that wins sets the same field. See Which setting wins. An active tuning profile and a pack higher in the list are the usual ones.
4. A setting is off. Check Settings that switch features.
5. You did not reload. Press F3+T after every change to a pack.
6. The file was dropped. Check the JSON against Things that drop a whole file.
7. The key needs another mod. Better Combat and Spatial GUI keys act only when those mods are installed.

Related pages

• Compat rules: the files that tune items and attach clips.
• Animation types and triggers: which type plays when.
• Animation reference: the clip file format and every timeline token.
• Create an animation: make a clip and put it in a pack.
• Tuning editor and debug: the Hand Editor and its profiles.
• Settings and controls: the menu behind the settings file.
• Mix the packs: choose between packs that set the same thing.
• Model parts: the whole system, then its definitions, item clips, particles, conditions, dynamic textures and variants.
• Item physics: pendulum modes and settings.
• Punchy! Studio: the editor that writes these files.
• Troubleshooting and FAQ when a pack does not load.