Tuning editor and debug position

Punchy! has a tuning window inside the game. It lets you slide an item or an arm into the right place in first person and watch the result live, then save it as a profile or export it as a file for your resource pack. This page is for pack authors who want exact numbers without guessing them in a text editor, and for players who only want to nudge one item for themselves.

It also covers the three debug position commands, which move the first-person arms for a quick look.

Before you start

• Punchy! installed and switched on (the Enable Punchy switch under DONE in the left column of the Punchy menu). Getting started covers the install.
• A world to stand in, in first person, with the item you want to edit in a hand.
• For shipping your result: a resource pack folder you can edit. Compat files live in assets/minecraft/punchy/compat/, see Compat rules.

Open the Hand Editor and move an item

Video coming soon

Drag with the left mouse button to move a slider. A plain click does not jump the value. A slider moves relative to where you pressed, so the value never jumps. The sliders show three decimals. Only some of them fit in the window at once: scroll the wheel over the list, or drag its scroll bar with the left mouse button.

The editor does not pause the game. A dark, partly see-through veil covers the screen behind the window. At a high GUI scale, such as Auto on a 1920 by 1080 screen, the window fills most of the screen, and your hand shows while you hold a slider.

Move the arm

The Editor button cycles what the sliders change. Click it once to switch from Editor: Item to Editor: Arm.

Hand: Main and Hand: Off pick the hand. They follow your Main Hand setting in Minecraft, so for a left-handed player Main edits the left arm. If the selected hand is empty and the other holds an item, the editor switches hands for you.

Fishing rods

If you hold a fishing rod, one more click on the editor button gives Line. It appears only while a fishing rod is in the selected hand, and it adjusts where the cast line leaves a rod that has no tip for Punchy! to start the line from.

In first person the cast line starts at the tip of the rod in your hand on every Minecraft version, for a flat rod and for a 3D rod model alike, so the Line sliders do not move it there. They place the line for a rod drawn as model parts whose definition has no fishing_line_anchor. A rod drawn as model parts starts the line at the fishing_line_anchor of its definition, a bone name and a position inside that bone. The same definition can list bones to hide while the line is out in hide_bones_while_cast, for a line you drew into the model. Both keys are read on every version, from the definition that draws the rod in your hand.

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

Save that as assets/mypack/punchy/model_parts_items/definitions/fishing_rod.json. The geometry and the texture are your own rod model, built as in Geometry and textures: save them as assets/mypack/punchy/model_parts_items/geo/fishing_rod.geo.json and assets/mypack/punchy/model_parts_items/textures/fishing_rod.png. Give the geometry a bone named rod_tip at the rod’s tip, with position in pixels inside that bone, and a bone named hanging_line for any line you drew into the model. See Definitions for every key.

Save a profile and export a file

Edits are live, but they last only while the editor is open unless you save them.

Video coming soon

Here is the core of an export after moving a diamond sword in the right hand. A real export can hold a few more keys, such as armKind, described below:

{
  "itemSpecific": {
    "minecraft:diamond_sword": {
      "kind": "SWORD",
      "transforms": {
        "right": {
          "scale": 1.0,
          "offX": 0.06,
          "offY": -0.12,
          "offZ": 0.0,
          "rotX": 0.0,
          "rotY": 0.0,
          "rotZ": 18.0,
          "pivotX": 0.0,
          "pivotY": 0.0,
          "pivotZ": 0.0
        }
      }
    }
  }
}

This is an ordinary compat file, so it works as it is. The key under itemSpecific is the item id. kind sets the kind Punchy uses for that item at runtime, in capital letters such as SWORD, and it overrides the kind the item would have by itself. transforms places the item and armTransforms places the arm, each with a right and a left pose. A side you did not touch is usually left out. Moving the arm of a held item adds armTransforms next to transforms. There you can also set armKind, the kind used for the arm pose: Punchy reads it only when armTransforms is present, and without it the arm pose uses kind. Scope: Global in the Arm editor adds a globalArm entry instead. The other keys are in Compat rules.

What is on the window

The sliders

Each slider writes one number of a pose. The keys are the same ones you write by hand in a compat file.

In the Line editor the ranges are wider: offsets -32 to 32, rotations -720 to 720 and scale 0.01 to 10. There are no pivot sliders there.

The buttons

The status line along the bottom shows the result of the last action.

Profiles and files

Profile names keep the letters A to Z (no accents), digits, dots, hyphens and underscores. Any other character, including accented letters, becomes an underscore, dots at the start are dropped, and a name can be 64 characters long. A saved profile holds only the differences from what your resource packs set, in the same keys a compat file uses.

On every start and every resource reload, Punchy applies things in this order: the compat files from your packs, then punchy_tuning.json if there is one and no profile is active, then your Mix Packs choices, then the active profile last. The active profile therefore wins over every compat file. On Minecraft 26.2 the active profile comes before the Mix Packs choices, and the positions it sets stay. Export compares against the state Punchy had when it last loaded its tuning (game start, F3+T, loading a profile or Reset To Default, and a pick on the Mix Packs tab once it is applied), so it lists everything you changed since then.

Debug position commands

Three commands move the first-person arms by typed numbers. They are client commands, so they work in single player and on servers, and nothing is sent to the server.

Video coming soon

You can also switch debug position mode on and off with Enable Tuning in the Punchy menu: it takes effect the moment you flip it, turning it on also turns Punchy on, and turning Punchy off also turns Enable Tuning off. The numbers act only while debug position says ON. They are not saved and they are not part of an export. Use the commands to look at an arm offset, and use the Hand Editor to make the numbers you keep.

Things that go wrong

• My changes vanished when I closed the editor. If you moved sliders and did not save, Done asks Unsaved profile. Ignore and exit puts everything back as it was when you opened the editor (or when you last saved or loaded a profile), and Cancel keeps you in the editor. Click Save Profile first. Export Tuning Helper keeps your numbers in the file, but the editor still asks Unsaved profile on Done until you save a profile.
• The sliders are grey. The Item editor needs an item in the selected hand. Pick up the item, or use Editor: Arm to edit the empty hand.
• I copied the export into my pack and nothing changed. Check these in order. Reload with F3+T. Make sure no profile is active that sets the same item, because the active profile wins over packs: click Reset To Default or delete the profile. Make sure the pack is higher in the Resource Packs list than any other pack that sets the same item, because the first pack wins each field. Check the JSON: a comma after the last member of an object, or a quote that is never closed, makes Punchy skip the whole file without a message.
• I deleted the wrong profile. Delete Profile removes the file and cannot be undone, and on Minecraft 26.1 and newer it does not ask first. If it was the active profile, Punchy goes back to the pack numbers and also deletes config/punchy/punchy_tuning.json, if you have one.
• The status line says Failed to export tuning helper. The file is written before Punchy tries to open the folder. If your system cannot open folders from the game, look in config/punchy/dev_tuning_helper yourself.
• I hand-edited a pose and the item disappeared. A pose without a scale key counts as scale 0. Keep scale in every pose you write, as the export does.
• I edited a renamed item or one with a custom model. The export names the entry with a # or | suffix and also writes a customModelData or renamed field, and that field does the matching, so the entry applies to that stack only. If you delete the field, the entry applies to every stack of that item.
• /punchy pos does nothing. Run /punchy debugposition first and wait for Debug position: ON.

Related pages

• Compat rules for every key you can put in the exported file.
• Mix the packs to choose which pack wins when several set the same item.
• Item physics for the pendulum settings that go next to a pose.
• Settings and controls for the rest of the Punchy menu.
• Resource packs for where a pack folder goes.
• Punchy! Studio to test animations on a held item with a timeline.