Resource packs

Punchy! gets its animations, the rules that play them and its custom item models from resource packs. This page shows how to turn packs on and put them in order, where each kind of file goes inside a pack, what wins when two packs say different things, and how to reload after a change. It is for players who stack several packs and for pack makers who want their files found.

Packs and mods that support Punchy! are gathered in the Punchy! compatibility collection on Modrinth.

Before you start

• Punchy! is installed and starts with your game (see Getting started).
• To build a pack by hand you need a plain text editor. To let the editor write the folders for you, use Punchy! Studio.

Turn packs on and put them in order

Video coming soon

Reload after a change

Press F3+T in a world. This is Minecraft’s own resource reload, and Punchy! listens to it: it reads your clips, rules and model parts again, so you do not restart the game after editing a pack. Pressing Done on the Resource Packs screen does the same.

Punchy! loads straight away and once more about a second later. Wait a moment before you test.

Video coming soon

Build a pack by hand

This pack replaces the sword attack with one clip of your own. It has three files.

The finished folder looks like this:

resourcepacks/
  My Punchy pack/
    pack.mcmeta
    assets/
      minecraft/
        punchy/
          animations/
            my_pack.animation.json
          compat/
            my_pack.json

The anim_speed_1; token in the timeline plays the clip at the speed you keyed. Without it, Punchy! plays an attack clip at the Animation Speed setting, which is 5.5 by default, so a 0.6 second clip would be over in a blink. SWORD is the name of an item kind and must be written in capitals. name is the clip for a single attack; for a combo that cycles clips, use var_1, var_2 and var_3 instead. The rule file format is on Compat rules, and clips are covered in Create an animation.

Let Punchy! Studio write the pack

Punchy! Studio writes this folder for you, including a pack.mcmeta that fits your game. It never changes a pack you only read from.

Studio writes the clip to assets/minecraft/punchy/animations/, the rules to assets/minecraft/punchy/compat/punchy_studio.json, and its own editable copies to .editor-projects/. A file an export replaces goes to .editor-backups/ first, so nothing is lost.

To keep working on a pack you already have, use Build from Pack. It copies the pack into a new one that Studio owns, and the original stays as it is.

In the Library, the list on the left shows every pack that contributes clips, with Punchy (built in) among them. The details say whether Punchy! plays a clip from this pack or from another one.

Where Punchy! looks

Everything below sits inside a pack, under assets/. Punchy! reads these files from every pack that is in Selected.

A resource id such as mypack:punchy/model_parts_items/geo/torch.geo.json means the file assets/mypack/punchy/model_parts_items/geo/torch.geo.json. Write a geometry id and an animation file id in full, with .geo.json or .animation.json. A texture id may leave out .png.

Here is a larger pack with the main kinds of file. Only the files you need have to exist.

My big pack/
  pack.mcmeta
  pack.png
  assets/
    minecraft/punchy/
      animations/my_pack.animation.json
      compat/my_pack.json
    mypack/punchy/model_parts_items/
      shading.json
      definitions/torch.json
      geo/torch.geo.json
      textures/torch.png
      animations/torch.animation.json
    punchy/
      sounds.json
      sounds/animationssounds/my_swing.ogg

This tree is a map of where each kind of file goes, not a pack to copy. pack.png is the square icon the pack list shows, and it is optional. my_swing.ogg is a short sound of your own saved as Ogg Vorbis. The geometry, texture, definition and clip for a model part are made step by step in Recreate a 3D torch pack.

A sound entry in sounds.json has the same shape as the ones Punchy! ships with, and Studio writes it for you when it exports a sound. This one defines the sound my_swing. A clip plays it with "sound_effects": { "0.1": { "effect": "my_swing" } }, which is 0.1 seconds in.

{
  "animationssounds/my_swing": {
    "sounds": [
      "punchy:animationssounds/my_swing"
    ]
  }
}

A shading.json file lights model part items by item. This one keeps a lava bucket bright in the dark, lights a water bucket evenly on every face, 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 }
  ]
}

fullbright and shading change only items a pack draws as model parts, and additive makes the particles drawn while that item is held blend additively. A file that is not valid JSON gives no rules, without a message. Light a whole model part has every key.

Punchy! also reads files that you may not think of as its own: the particle textures and particle definitions an emitter draws with, and the item model files a model part brings. They stay at their normal Minecraft paths. See Particles.

The pack.mcmeta file

Write pack_format for every version, and add min_format and max_format from 1.21.11 on, as in the example above. A pack whose numbers do not cover your game version is flagged in the pack list as made for another version. From 1.21.11 on, a pack must also have both min_format and max_format: the game refuses a pack that leaves them out, so it does not load. Studio writes the right numbers for you and leaves a pack.mcmeta you wrote untouched when it already covers your game.

Load order and what wins

Punchy! ranks the packs by the Selected list, top first. A pack that is not in Selected is not read. When two things in different packs compete, the rule depends on the kind of file.

Clips

Clips are found by name, from every pack. The first clip with a name, from the top of the list down, is the one Punchy! uses. A rule in any pack can name a clip that a different pack supplies, as long as that pack is on. Clip names are case sensitive.

If two files of one pack hold a clip with the same name, do not count on either one winning. Give each clip a name of its own.

Rules in compat files

All compat files from all packs are merged into one set of rules. The higher pack wins for each field, and a lower pack only adds what is still empty. In practice:

• Each entry of item and itemSpecific is merged on its own, by its key.
• A right or left pose in transforms or armTransforms is taken whole from the first pack that has it. Fields the winner left out do not come from a lower pose.
• In a customAnimation list, the higher pack’s entries stay. A lower pack adds only entries whose type the higher pack does not have. An interaction entry is told apart by its key and its filters as well.
• A group in customGroups keeps the first definition of a name, ignoring case.

Here is what that gives for two packs. Pack A is higher in the list.

{
  "item": {
    "SWORD": {
      "transforms": {
        "right": { "scale": 1.0, "rotX": 20.0 }
      }
    }
  }
}

Pack B is below it.

{
  "item": {
    "SWORD": {
      "transforms": {
        "right": { "scale": 0.8 },
        "left": { "scale": 0.8 }
      },
      "customAnimation": [
        { "type": "attack", "name": "b_swing" }
      ]
    }
  }
}

A sword is held with the right pose of pack A, the left pose of pack B, and plays b_swing on an attack, because pack A has no attack entry. If pack A also had one, pack A’s would play.

Model parts

Definitions are not ranked by pack. Punchy! sorts all of them by their full id, as text, ignoring case and starting with the namespace. It uses the first one that matches the held item.

a_pack:punchy/model_parts_items/definitions/torch.json
minecraft:punchy/model_parts_items/definitions/0_first/torch.json
minecraft:punchy/model_parts_items/definitions/torch.json

Read top to bottom, that is the order Punchy! tries them. So a definition wins over another one for the same item when its id sorts earlier. Two things change this:

• A definition with a customName beats every unnamed definition when the held item carries that name. When a named definition exists for an item and the held item does not match it, no unnamed definition is used, and the vanilla model is drawn.
• A definition whose geometry file is missing still matches its items. It draws no model of its own, so the vanilla model shows, and it hides the later definitions for the same item.

Studio’s Model Parts Library lists every definition in your loaded packs in this order, and says for each item whether it is rendered, shadowed by another definition, blocked by a named one, or never matching. When you export a model part, Studio can put the definition first in the order so that it wins over other packs.

What is applied after the packs

Punchy! applies things in this order, and a later step overrides an earlier one wherever both set the same thing:

1. The compat files of all packs, merged as above.
2. config/punchy/punchy_tuning.json, the tuning you saved, only when no tuning profile is active.
3. Your picks on the Mix Packs tab.
4. The active tuning profile, from config/punchy/profiles/.

On Minecraft 26.2, steps 3 and 4 swap places. The active tuning profile is applied first and your picks on the Mix Packs tab after it, so a pick wins over the animations the profile sets for those item kinds. The positions the profile sets stay. See Mix the packs.

These files live in your game folder, not in a pack, so a pack you install cannot change them. They are covered in Tuning editor and debug.

Mixing several packs

You can stack packs freely. These patterns come up most:

• A pack for swords above a pack for everything else. Put the sword pack higher. It wins for the sword rules and clips it defines, and the lower pack supplies the rest.
• Clips from one pack, rules from another. Rules and clips find each other by clip name, so both packs only need to be on.
• Picking one animation from a lower pack. Press F8 to open Punchy!‘s menu and open the Mix Packs tab. Find the row of an item kind, such as Sword, and pick a pack in its chooser. The pick is saved at once, needs no restart, and beats pack order for that kind. Use resource pack order puts every row back to the order of your resource packs. To keep a set of picks, press Save as…, type a name and press Save. See Mix the packs.
• Two model part packs for the same item. Pack order does not help here, because definitions are ranked by id. Use the Model Parts Library to see which one is drawn.
• One pack that holds everything. Build from Pack in Studio copies a pack into a new one you own, and you can add your own clips to it.

In Studio’s Bindings workspace, the Effective panel on the right shows, for the held item and each trigger, which rule Punchy! would use and why.

Replace the built-in rules

The Punchy! pack carries a rule file called tuning_template.json. It is ranked like any other rule file, by where the Punchy! pack sits in Selected. If a different enabled pack holds a file named default_tuning.json directly in a compat folder, Punchy! no longer merges tuning_template.json into your rules; it merges only the rule files of the packs, ranked as above:

assets/minecraft/punchy/compat/default_tuning.json

Use this only when your pack is a full replacement. The built-in rules then no longer fill in anything your pack leaves out.

Things that stop a pack from loading

• No pack.mcmeta, or a zip with an extra folder. The top level of the zip must show pack.mcmeta and assets directly. A zip that holds one folder with those inside is not read as a pack.
• A misspelled folder. Folder names are exact and lower case. animation instead of animations is not an error: Punchy! never sees the file.
• A rule file that is not valid JSON. A missing comma is enough. Punchy! skips the whole file without a message, and so does a value of the wrong type, such as text where a number belongs, or the same key twice in one map such as item.
• A clip file with a mistake. A file that is not valid JSON, or whose top level is not an object, gives no clips and a warning in the game log (logs/latest.log). A file with no animations object gives no clips and writes no message. A clip with one bad value is dropped alone and the rest of the file loads.
• A model part definition missing a required key. A definition with no items (or item), no geo or no texture is dropped with no message. Check that all three are there.
• Resource Pack Model Parts is turned off. With that switch off, no model part definition loads or draws, whatever the packs hold. It is on by default. Press F8, open the Items & World tab and check Resource Pack Model Parts, then press F3+T.
• A pack that sits below Punchy!. For any clip name or rule both packs define, Punchy! wins, so your change never shows. Move your pack up.
• A pick from earlier on the Mix Packs tab. A pick there beats pack order for its item kind. If a pack you moved to the top seems ignored, press F8, open Mix Packs and look at the row of that item kind. Use resource pack order clears every pick.
• A pick that comes back to an older one after a reload. Punchy! applies the setup you loaded or saved again at every resource reload and every start. A pick you make on the Mix Packs tab after loading or saving a setup is replaced by that setup on the next reload. To keep the pick, press Save as… again, or choose Current choices in the setup list at the top left of the tab, which forgets the loaded setup and keeps your picks.
• A misspelled key. Punchy! ignores a key it does not know, with no message, so a typo such as customAnimations does nothing. Check each key against Compat rules, which also lists the other spellings a key accepts.
• A pose with no scale. A right or left pose without scale is drawn at size 0, so the item vanishes. Write scale in every pose.
• A wrong name or a wrong case. A rule that names My_Sword_Swing does not find the clip my_sword_swing. Item kinds such as SWORD are exact capitals.
• A sound that does not play. A missing .ogg is skipped with no message. Check that the file sits at assets/punchy/sounds/animationssounds/<name>.ogg and that the sound name in sound_effects matches it exactly. Use only lowercase letters, digits and _ - . / in sound names, as Minecraft’s resource paths allow.
• Testing before the reload has finished. Press F3+T and wait a second.

When no active pack holds a Punchy! clip or compat file, which happens when you turn off the built-in Punchy! pack and have no other one on, Punchy! shows a screen titled Punchy: resource pack disabled. It appears the first time you attack, mine, use an item or inspect in first person. It says Punchy! could not find compatibility files or first-person animations in your active resource packs, and asks you to enable the built-in Punchy! pack or another compatible pack in Options, Resource Packs. With Punchy!‘s menu installed, the warning is a card with a Turn on Punchy’s pack button when the built-in pack is in your list but switched off. Press it and Punchy! turns its pack on and reloads, or press Not now to leave it off. If the pack is not in the list, the card only has Got it.

Related pages

• Create an animation takes a clip from nothing to playing in game.
• Compat rules explains the rule files in full.
• Mix the packs chooses a pack for each kind of item.
• Model parts covers definitions, geometry and textures.
• Punchy! Studio writes packs for you.
• Tuning editor and debug covers saved tuning and profiles.
• Troubleshooting helps when a clip does not play.