Settings and controls

Press F8 in the game and the Punchy menu opens. This page walks through the tabs of the menu, with the exact label and default of each option, then the keys Punchy adds to the Controls screen, including the keys your own animations can add. It is for players who want to tune first person and for pack makers who want a key for a clip.

Before you start

• The labels and defaults here were checked against Punchy! 3.0 for Fabric on Minecraft 26.3. Another version or loader can word things a little differently.
• Your choices are saved in config/punchy/punchy_config.json in the game folder, so they stay between sessions. Every change is written the moment you make it.
• A few options do something only when another mod is installed. Without that mod the row shows a Not installed tag. The page says which.
• The title, the group headers and the gold buttons of the menu are drawn in capital letters. This page writes them the way they are worded, such as Done.

Open the menu and change an option

Video coming soon

What is in the menu

The left column holds a preview box with the Punchy! logo, the Done button, the Enable Punchy switch and the tabs, sorted into groups. Each page has its title, a one-line subtitle, a Search field and, on pages of settings, a Changed pill. A … page menu appears at the top right of a page once something on it differs from its default. A tab that holds changed settings shows a small gold dot.

Enable Punchy sits under Done on every tab. Turn it off and the game draws your hands the vanilla way, with no Punchy animation, and every Punchy page shows Punchy is off. Settings are kept but have no effect. with a Turn on button.

Help and bug reports

Please donate, Discord, Wiki and Report a bug (Discord) open a link through the game’s link prompt. Discord and Report a bug open the same Discord invite. Copy debug info puts a short report on your clipboard: your Punchy and Minecraft versions, your loader and its version, the version of Punchy! Studio when it is installed, and one line for every setting you changed from its default, plus the number of blacklist entries. Paste it into your bug report.

Search, undo and the keyboard

• Search. Click the Search field of a page, or press Ctrl+F or /. Typing replaces the page with the matching rows from every tab, grouped by tab and section, with the matching letters underlined and a count beside each tab. Go to page on a group opens that tab. Esc clears the search, and a second Esc closes the menu. On Mix Packs and Item Blacklist the field filters that page only. On Item Blacklist, what you type in the Search field also fills the Search item name or id box. Pressing Esc inside that box only leaves the box and keeps the text.
• Changed. The Changed pill shows only the settings that differ from their defaults, with a count.
• Row details. Hovering a row shows what it does, its Default, Changed from default when it differs, and Takes effect after resources reload (F3+T) where that applies. Right-click a row for Reset to default followed by the default in brackets, and Copy value.
• Undo. Each change is one undo step. Ctrl+Z undoes the last one, and Ctrl+Y or Ctrl+Shift+Z does it again. A message with Undo follows Reset this page, Reset all settings and every profile load. Resetting a single row has no message: use Ctrl+Z. While you type in a text field, Ctrl+Z undoes your typing in that field instead.

On a slider, Enter or a double click on the number lets you type a value, and Ctrl with the mouse wheel steps it. Hold Shift while you drag to move at a tenth of the speed, and press Esc during a drag to put the value back.

Reset a setting, a page or everything

• One setting. Point at a changed row and click its reset arrow, or right-click the row and choose Reset to default (…). It puts back the real default of that row.
• One page. Once a setting on the page has changed, open the … menu at the top right and choose Reset this page. A message tells you how many settings were reset and offers Undo.
• Everything. Open General and press Reset on Reset all settings, then confirm. Every Punchy setting and the item blacklist go back to their defaults, Enable Punchy and Resource Pack Movement included. Your Mix Packs choices, your saved profiles and the menu’s own preferences stay. It is one undo step, and the message offers Undo.

Every setting by tab

The File key column is the name used in punchy_config.json, covered in Edit the settings file. Every key that starts with disable is inverted: a menu row that is on is false in the file. Enable Punchy (file key enableMod, on by default) is the switch under Done.

General tab

The Tools section also holds the Hand Editor row. Press Open to adjust where items and arms sit in your hand. On Minecraft 1.20.1 to 1.21.11, closing the Hand Editor brings you back to the Punchy menu. On 26.1 and newer it closes straight to the game, so press F8 to open the menu again. See Tuning editor and debug.

The Menu section holds four preferences for the menu itself. They are not Punchy settings, so profiles and Reset all settings do not touch them.

• Reduce motion is Auto, On or Off, and Auto by default. Auto follows the game’s Distortion Effects setting. When it applies, the menu’s motion becomes short fades and the Mix Packs preview gets a Pause button.
• Menu size is Smaller, Auto or Larger, and Auto by default, which follows your GUI scale.
• Pause game while open is on by default. It stops single-player time while the menu is open.
• Interface sounds is on by default. It clicks when you press buttons and toggles.

They are saved in config/punchy/menu_prefs.json, together with the tab you used last. A missing or broken file gives the defaults, so deleting it is a safe reset.

{
  "lastTab": "general",
  "reduceMotion": "auto",
  "menuSize": "auto",
  "pauseWhileOpen": true,
  "interfaceSounds": true
}

Movement tab

Effects tab

Items & World tab

The World models section switches the extra effects Punchy gives to some held items.

Compatibility tab

The rows for First Person Model, Better Combat and Sword Blocking Mechanics carry a Not installed tag when that mod is missing.

Keep items vanilla

The item blacklist makes chosen items look and play like normal Minecraft. Punchy plays no animation for them.

Each change is saved at once and can be undone. Blocking moves an item’s id to the top of the list, because the first entry that matches an item decides. Switching Block off clears its Both hands, and switching Both hands on for an item that is not blocked blocks it. A row reads Blocked by followed by the entry that covers it when a pattern or a mod you added already includes that item.

Video coming soon

To block many items at once, type an item id, a mod id or a pattern such as minecraft:*_sword into the field that reads Item id, mod id, or a pattern with * and ? and press Add pattern. These entries appear under Patterns and mods, tagged Pattern, Mod or Not in this game, each with Both hands and Remove. You can also write them in the settings file, as shown below.

The Clear blacklist button empties only the blacklist, and a message offers Undo.

On Minecraft 26.1 and newer, if you open the menu from the title screen, for example through Mod Menu, the Item Blacklist and Mix Packs tabs show names without item icons until you have joined a world. The icons appear after that.

Save a setup as a profile

A profile is a named copy of the options in the menu and of the item blacklist. Use one to switch between, say, a plain look and a full effects look. Loading a profile leaves Resource Pack Movement and your Mix Packs choices as they are.

While a profile is active, its name shows at the left of the title bar as Profile: and the name. Click it to come back to the Profiles tab.

Delete on a profile’s row asks Delete profile NAME? and removes the file when you confirm with Delete. Your current settings stay. Open Profiles Folder opens config/punchy/config_profiles/ on your computer, where each profile is a .json file named after it.

Spaces and the characters \ / : * ? " < > | in a name become _, and a name is cut at 64 characters. An empty name is saved as config_profile. While you type, a line under the name says whether it is Saved as a new name or Replaces the profile with that name.

Keys Punchy adds to Controls

Open Options, then Controls, then Key Binds. Punchy adds two keys under the Punchy! group.

Click a key in the list, press the new key and it is rebound, like any other Minecraft key. Every default key lands on the key its name says, and the key you pick is kept. The Inspect key plays the clip that an inspect entry of the item names, or else any loaded clip named inspect, and nothing when the loaded packs have neither. How packs set this up is covered in Animation types and triggers.

Video coming soon

Add a key for your own clip

A pack can ask Punchy for its own key. The entry type is triggerable. It shows up in Controls under Punchy Triggerable Animations, and the player can rebind it there.

The example is a small pack of three files:

My wave pack/
  pack.mcmeta
  assets/minecraft/punchy/animations/my_wave.animation.json   (any file name)
  assets/minecraft/punchy/compat/my_pack.json

{
  "default_animations": [
    {
      "type": "triggerable",
      "id": "my_pack_wave",
      "title": "Wave hello",
      "name": "my_wave",
      "key": "H"
    }
  ]
}

The player can still rebind it in Controls.

In Punchy! Studio’s Bindings workspace the same entry is a rule of type Custom Key, with a Key field that takes the names below.

The key text is not case sensitive, and spaces, - and _ in it are ignored, so Page Up and PAGE_UP both work. A leading key.keyboard. is dropped, so key.keyboard.g works too. These names are accepted:

• Letters A to Z and digits 0 to 9.
• F1 to F25.
• Keypad keys written NUMPAD0 to NUMPAD9, or KP0 to KP9, and NUMPADPLUS, NUMPADMINUS, NUMPADMULTIPLY, NUMPADDIVIDE, NUMPADDECIMAL (or NUMPADDOT) and NUMPADENTER, each also with the KP start, such as KPPLUS.
• ESC (or ESCAPE), TAB, ENTER (or RETURN), SPACE, BACKSPACE, INSERT (or INS), DELETE (or DEL), HOME, END, PAGEUP (or PGUP), PAGEDOWN (or PGDN), UP, DOWN, LEFT and RIGHT.
• LEFTSHIFT (or LSHIFT, SHIFT), RIGHTSHIFT (or RSHIFT), LEFTCTRL (or LCTRL, CONTROL), RIGHTCTRL (or RCTRL), LEFTALT (or LALT, ALT), RIGHTALT (or RALT), CAPSLOCK, SCROLLLOCK, NUMLOCK, PRINTSCREEN (or PRTSCR, PRTSC) and PAUSE.
• APOSTROPHE (or QUOTE), COMMA, PERIOD (or DOT), SLASH, SEMICOLON, EQUAL (or PLUS), MINUS (or DASH), LEFTBRACKET (or LBRACKET), RIGHTBRACKET (or RBRACKET), BACKSLASH and GRAVE (or TILDE).

Any other text leaves the entry without a default key, and the player picks one in Controls.

The key the player chooses is saved in config/punchy/triggerable-keybindings.json. That file belongs to the player, so never ship it in a pack. A saved key always wins over the key in the pack.

Edit the settings file

Everything in the menu’s Punchy tabs is stored in config/punchy/punchy_config.json. Close the game before you edit it by hand, because the menu writes the file each time you change a setting. For example, you can copy a setup to another instance this way. Keys you leave out keep their defaults, so this small file is complete:

{
  "animationSpeed": 4.0,
  "disableNewKeyframeMoves": false,
  "sprintArmSwingIntensity": 0.5,
  "enableMud": false,
  "firstPersonModelHidePitch": 60.0,
  "itemBlacklist": ["minecraft:*_shovel", "minecraft:shield", "examplemod"],
  "blacklistApplyDualHanded": { "minecraft:shield": true }
}

In that file disableNewKeyframeMoves is false, which turns the Resource Pack Movement row on, so a resource pack’s keyframe clips can drive walk, sprint, jump, fall and landing. Every disable key works the other way round: false means the row is on.

Numbers are clamped when the file loads: animationSpeed to 0.5 to 7, firstPersonModelHidePitch to 0 to 90, and the two sprint values to -1 to 1 (the menu shows them as percents).

Things that trip people up

• The file is replaced when it cannot be read. A missing comma, a stray quote or a value of the wrong type makes Punchy fall back to the defaults and write a fresh file over yours. Keep a copy before you edit it, and check it in a JSON validator.
• Resource Pack Movement is off by default. Punchy’s own walk, sprint, jump, fall and landing movement is used. A pack’s keyframe clips for those do not play until you switch it on.
• A row can look ignored. Turn Enable InteractiveStuff Compat on and the four World models rows on the Items & World tab stay as they are but have no effect.
• A model parts change waits for a reload. Resource Pack Model Parts takes effect after F3+T.
• Some rows need another mod. Spatial GUI Support is greyed out without Spatial GUI. First Person Model Auto Hide and FPM hide angle act only with First Person Model. Better Combat Support acts only with Better Combat. Sword Blocking Mechanics Support is tagged Not installed without that mod and does not change anything when it is installed.
• A key needs a key. A triggerable without one never reaches the Controls screen. Reload with F3+T after you add or change one.
• Two keys on the same key. The Controls screen can miss a clash between two Punchy keys, so check for one yourself. Pick keys that no other mod uses and that Punchy’s built-in pack does not use: it holds G and J.

Related pages

• Getting started for installing Punchy and choosing a first pack.
• Mix the packs for the Mix Packs tab.
• Tuning editor and debug for the Hand Editor row.
• Animation types and triggers for every trigger, including inspect and triggerable.
• Item physics for what Enable Item Physics switches.
• Troubleshooting when an animation or key does not respond.