Model parts overview

A model part is a 3D model that Punchy! draws in your hand in first person instead of the normal item. You can give a stick the shape of a baton, a lantern a flame that glows and flickers, or a bucket a creature that swims inside it, all from a resource pack.

This page is for pack makers. It shows what a model part is made of, builds a working one from three small files, and explains how Punchy! picks and draws it. The pages after it cover each piece in depth.

What a model part is made of

One model part is a handful of files that point at each other.

• A definition. A small JSON file that names the items it covers and the other files it uses. It is the only file Punchy! reads to find this model part. Everything else is found through it.
• A geometry. A .geo.json file with the bones and cubes of the model, in the Bedrock geometry format that Blockbench writes.
• A texture. A PNG that paints the cubes. It can be your own, or a texture that already ships with Minecraft.
• Item clips (optional). An .animation.json file that moves the bones of the model itself, such as a lid that opens or a flame that flickers.
• Extras (optional). Glow, a different texture for one bone, an animated texture, particles, physics and swaps that depend on what the item holds.

Model parts draw in first person only. In the third person view the item looks the way Minecraft draws it.

Before you start

• Install Punchy! 3.0 or newer from Modrinth or CurseForge. Behavior on this page is checked against Punchy! 3.0 for Fabric on Minecraft 26.3, and the menu names are those of the Punchy menu (F8).
• Know where your resourcepacks folder is. In the game, Options, Resource Packs, then Open Pack Folder opens it.
• You need a plain text editor for the first example. Punchy! Studio, from Modrinth or CurseForge, can write all of the files for you, and the second set of steps below shows how.

Make your first model part

This pack turns a stick into a small wooden bar. It uses a texture that ships with Minecraft, so you need no image yet.

Video coming soon

Edit a file and press F3+T in the world to reload without leaving the game. Wait a second for Punchy! to finish loading before you look.

How big the bar looks and where it sits in your hand depends on the item’s normal first person transform. The definitions page shows how to set your own with display.

Make a model part in Punchy! Studio

Punchy! Studio’s Model workspace builds a model part of the same kind, with a definition, a geometry and a texture of its own, and shows the model in your hand while you work. The new part is a small grey checkered bar, not the oak planks one from the hand-made pack. To give it a texture of your own, drop a PNG on the Studio window.

Video coming soon

Studio writes the files under assets/minecraft/punchy/model_parts_items/ unless you change the Namespace field, and it moves any file it replaces into .editor-backups. Its lint flags many of the mistakes listed at the end of this page, and the export window shows how many errors it found.

Make it move with an item clip

An item clip moves the bones of the model. This one sways the bar gently while you hold it.

Video coming soon

An item clip plays at 1x speed, so a two second clip lasts two seconds. The item clips page shows how to play other clips for attacks, using an item, equipping and more.

Where the files go

Everything lives in a resource pack under assets/<namespace>/. The namespace is any name you pick with lower case letters, digits, _, - and .. Here it is mypack.

Model part test/
  pack.mcmeta
  assets/
    mypack/
      punchy/
        model_parts_items/
          definitions/
            baton.json
          geo/
            baton.geo.json
          textures/
            baton.png
          animations/
            baton.animation.json

The first example uses the oak planks texture that ships with Minecraft, so its pack has no textures folder. The tree shows a pack that also has a texture of its own. To paint one, save a 16 by 16 PNG as textures/baton.png. The four sides of the example cube show the top left 4 by 12 pixels of the texture and the top and bottom show its top left 4 by 4, so paint the top left 4 by 12 pixels. Then set texture in baton.json to mypack:punchy/model_parts_items/textures/baton.

A resource id such as mypack:punchy/model_parts_items/geo/baton.geo.json means the file assets/mypack/punchy/model_parts_items/geo/baton.geo.json. Resource packs has the full map of where Punchy! looks.

The minimum definition

A definition needs at least one item, a geometry and a texture. Without any one of them Punchy! drops the file.

Build a model part in this order

Add one thing at a time and look at the result before you add the next. When something breaks, the last change is the cause.

1. Get the plain model drawing. A definition with items, geo and texture, as in the first example. Hold the item and check that it shows.
2. Fit it to the hand. Set display so the size and position suit the hand. See Model part definitions.
3. Shape the model. Split it into bones for every piece you will move, and give every cube per-face UVs. See Geometry and textures.
4. Add item clips. Write the animations file, then add modelPartsAnimation entries to say when each clip plays. See Item clips.
5. Add the look. Glow with bone_emission, another texture for one bone with bone_textures, an animated texture with texture_anim. See Geometry and textures.
6. Add particles. Flames, smoke or sparks from a bone. See Particles.
7. React to the world. Pick an idle clip by water, weather, a nearby block, the time or the biome with Conditions, or swap a texture or geometry by what the item holds with Dynamic textures.
8. Add physics. Let a bone swing like a pendulum. See Item physics.
9. Ship variants. Several complete definitions for the same item, such as a lantern with sparks and a calm one, chosen by folder order or by the item’s name. See Variants and presets.

The tutorials follow this order on real items: Recreate a 3D bucket pack and Recreate a 3D torch pack.

Where each key is explained

A fishing rod’s line

Two optional keys fit a fishing rod whose model draws its own line. They matter only for minecraft:fishing_rod, and Punchy! reads them from the definition that draws the rod in your hand, named or not.

This definition starts the line at the bone rod_tip and hides the bone hanging_line while the line is out. Both bones are in the geometry. The geometry and the texture here are your own rod model, so use the names of your own bones and the numbers that put the start at your rod’s tip.

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

Both keys work on every Minecraft version and loader. Punchy! Studio has no fields for these keys and keeps them as you wrote them. The definitions page lists them with the other definition keys.

How Punchy! draws a model part

A model part takes the place of the item model in your hand. The hand itself, your clips and Punchy!‘s other first person work are unchanged. The model is drawn where the normal item would be, so the clips that move your hand carry it along.

Punchy! decides what to draw for each hand on its own, so a definition can show in your main hand and not in your off hand. The checks run in this order:

1. Built-in models first. Punchy! has its own in-hand models for boats, minecarts and rafts, chests, enchanting tables and pistons. While their switch is on in the Items & World tab of the Punchy menu (Enable Boat/Minecart/Raft Models, Enable Chest Effects, Enable Enchanting Effects, Enable Piston Effects), these items draw that way and never reach a model part.
2. Using an item skips model parts. While you draw a bow, eat or block with a shield, Punchy! skips model parts and the normal use pose draws. A model part stays on when its definition has a modelPartsAnimation entry of a use type (such as useItem, useDrink or useEat), or a using entry in state_models.
3. Punchy! looks for a definition. A definition with a customName that matches the item’s name wins. If a named definition exists for the item and the name does not match, no unnamed definition is used. Otherwise the first matching definition in id order wins. Resource packs explains the order.
4. It draws the model. Punchy! poses the bones from the item clip that is playing, paints the cubes with the texture, applies glow and per-bone textures, puts the model in the hand with your display transform (or the item’s normal first person transform when there is none), and releases the particles. In the left hand the model is mirrored.
5. No definition, no change. An item without a matching definition draws the normal way.

Two switches change this, both on the Effects tab of the Punchy menu. Enable Particle System turns the particles of every model part off. Enable Model Parts Glow turns off the glow of particles only: the bone_emission glow on the model’s own bones does not depend on it. See Settings and controls.

Work from a pack you already have

Studio can open a model part that a pack already contains, so you can see how it is built and change a copy.

To copy a whole pack, with its clips, rules and model parts, into a new pack that Studio owns, use Build from Pack in the Library.

Things that stop a model part from showing

Punchy! says nothing in the game about the worst of these, and a definition that has a mistake often just disappears. Studio’s lint finds many of them for you: a dropped definition, a definition in the wrong folder, a missing geometry, texture or clip file, a clip name that does not exist, a named definition that blocks others, and cubes without per-face UVs. In a pack you write by hand, check this list first.

• A definition that is dropped without a message. The file is not valid JSON, the top level is not an object, items (or item), geo or texture is missing, or a key holds the wrong kind of value, such as a display entry that is not an object or a rotation that is not a list of numbers. One mistake drops the whole file, and the item draws the normal way.
• The wrong folder. Definitions are read only under assets/<namespace>/punchy/model_parts_items/ in a definitions folder. A definition anywhere else is never loaded.
• A geo id that is not complete. Punchy! uses it exactly as written. baton or geo/baton.geo.json points nowhere, and mypack:punchy/model_parts_items/geo/baton.geo.json is right. A definition whose geometry file is missing still claims its items. It draws nothing and hides the later definitions for the same item, so the normal item shows.
• Cubes without per-face UVs. Give every cube a uv object with the faces it draws, as in the example. Once any cube has one, cubes that use the short [u, v] form are not drawn. A model made only of short-form cubes draws, but without glow, bone textures, particles or physics. Only the faces you list on a cube are drawn.
• A model the wrong size or in the wrong place. Geometry is in pixels, 16 to a block. The examples on this page, and a model that Studio starts, sit around the middle (x and z near 0) with their base at y 0. Use display to fit the model to the hand.
• Two definitions for one item. Pack order does not decide. Punchy! sorts the ids as text, namespace first, and the first match wins. Studio’s Export First in Order puts the definition in a folder called 0_punchy_studio, which sorts ahead of definitions whose folders and files start with a letter in its own namespace. A folder or file name that starts with a symbol such as -, or with 0_ and an earlier letter, can still sort ahead of it. A definition in a namespace that sorts before yours still wins, so change the Namespace field if you need to move ahead of it.
• A broken clip file. A clip file stops loading at its first bad clip or bad time key. The clips before it are kept, the ones after it are lost, and nothing is said. A modelPartsAnimation entry that names a clip that does not exist falls back to the idle clip.
• An animations id that is not complete. Like geo, it is used as written, so a file must exist at that exact path. Ending the name in .animation.json is the convention, not a rule the game checks.
• A texture grid that does not match your UVs. The UV numbers are read on the grid set by texture_width and texture_height in the geometry file, not on the size of the PNG. When they are missing the grid is 64 by 64, so a 16 by 16 texture painted with UVs for 16 shows the wrong part of the texture. Write the grid you drew your UVs on. Geometry and textures has the details.
• A named definition for the same item. When one definition has a customName and the stack’s name does not match it, Punchy! uses no unnamed definition for that item, so the normal item shows.
• A model part you wanted in third person. Model parts draw in first person only.
• A pack that is not on. Check that it is in Selected, that pack.mcmeta covers your game version, and that you waited a second after the reload.

Related pages

• Model part definitions lists every key that picks items and fits the model to the hand.
• Geometry and textures makes the model and its texture.
• Item clips animates the bones of the model.
• Particles adds particle emitters.
• Dynamic textures and Conditions make a part react to the item and the world.
• Variants and presets ships several versions of one part.
• Item physics adds pendulum swing to bones.
• Resource packs shows where Punchy! looks and how it orders packs.
• Punchy! Studio for Punchy! packs covers the Model workspace and the Model Parts Library.