Geometry and textures

A model part is a shape, a picture and a definition that ties them to an item. This page covers the first two and the settings that act on them: the Bedrock geometry file, UV and texture size, bone textures, animated textures and glow. It is for anyone who wants to make a held item of their own in Blockbench or Punchy! Studio, or to find out why a model does not show up.

You will build a small glowing stick whose tip flickers, then read through every key Punchy! reads in the geometry file and the texture settings.

Before you start

• Punchy! 3.0 or newer. This page was checked against Punchy! 3.0 for Fabric on Minecraft 26.3.
• A resource pack to put the files in. Resource packs shows how to make and turn on a pack.
• Blockbench 5 (checked in 5.2.2), or Punchy! Studio.
• A basic idea of what a definition file is. Model part definitions covers every field. This page only uses the few that point at geometry and textures.

Model parts show in your own first person hands. The inventory, dropped items and other players still show the normal item.

Where the files go

A model part is three files. The folders below are the usual layout. Punchy! loads exactly the ids the definition names, so only the definitions folder is fixed.

Another namespace works in place of minecraft, as long as the definition names it.

Build the stick

Both paths end with the same three files. Pick the tool you work in.

The complete files

These three files make the stick glow and flicker. Copy them into the paths from the table above.

The definition names the item, the geometry and the textures. It gives the tip bone its own animated texture and makes it glow:

{
  "item": "minecraft:stick",
  "geo": "minecraft:punchy/model_parts_items/geo/glow_stick.geo.json",
  "texture": "minecraft:punchy/model_parts_items/textures/glow_stick",
  "bone_textures": {
    "tip": "minecraft:punchy/model_parts_items/textures/glow_stick_tip"
  },
  "bone_texture_anim": {
    "tip": { "frames": 4, "frametime": 3 }
  },
  "bone_emission": {
    "tip": 100,
    "blur": true
  }
}

The geometry holds two bones. stick is the root. tip hangs from it and sits on top:

{
  "format_version": "1.12.0",
  "minecraft:geometry": [
    {
      "description": {
        "identifier": "geometry.glow_stick",
        "texture_width": 16,
        "texture_height": 16
      },
      "bones": [
        {
          "name": "stick",
          "pivot": [0, 0, 0],
          "cubes": [
            {
              "origin": [-1, 0, -1],
              "size": [2, 12, 2],
              "uv": {
                "north": { "uv": [0, 0], "uv_size": [2, 12] },
                "east": { "uv": [2, 0], "uv_size": [2, 12] },
                "south": { "uv": [4, 0], "uv_size": [2, 12] },
                "west": { "uv": [6, 0], "uv_size": [2, 12] },
                "up": { "uv": [0, 12], "uv_size": [2, 2] },
                "down": { "uv": [2, 12], "uv_size": [2, 2] }
              }
            }
          ]
        },
        {
          "name": "tip",
          "parent": "stick",
          "pivot": [0, 12, 0],
          "cubes": [
            {
              "origin": [-1.5, 12, -1.5],
              "size": [3, 3, 3],
              "uv": {
                "north": { "uv": [8, 0], "uv_size": [3, 3] },
                "east": { "uv": [11, 0], "uv_size": [3, 3] },
                "south": { "uv": [8, 3], "uv_size": [3, 3] },
                "west": { "uv": [11, 3], "uv_size": [3, 3] },
                "up": { "uv": [8, 6], "uv_size": [3, 3] },
                "down": { "uv": [11, 6], "uv_size": [3, 3] }
              }
            }
          ]
        }
      ]
    }
  ]
}

Every face is a rectangle on the 16 by 16 texture grid. Use these rectangles in the UV step above. Each one is written as u, v, width, height:

You need two PNG files:

• glow_stick.png is 16 by 16 pixels. Paint the stick in the rectangle from x 0 to 7 and y 0 to 13, for example in a few shades of brown. Nothing else on it is used.
• glow_stick_tip.png is 16 pixels wide and 64 pixels tall: four frames of 16 by 16, one under the other. In each frame, paint the tip in the rectangle from x 8 to 13 and y 0 to 8. Make the four frames differ a little, for example four shades of orange.

Hold a stick in first person. The tip cycles through its four frames, and at night the tip glows while the rest of the stick is shaded as usual. If the stick sits oddly in your hand, the display field of the definition moves it. Model part definitions covers it.

Video coming soon

The geometry file

Punchy! reads the standard Bedrock geometry layout that Blockbench writes in its Bedrock Entity format. It reads only the keys below. Everything else in the file, such as format_version, identifier or locators, is ignored.

Units and axes

All numbers are pixels, and 16 pixels make one block. Punchy! draws the model at one sixteenth of the file’s size, so a model 16 pixels high is one block high.

Pivots are absolute positions in the model, as in every Bedrock file. They are not relative to the parent bone. Punchy! works out each bone’s offset from its parent for you. Cube origins and cube pivots are absolute too, and cubes are placed relative to the pivot of the bone they sit in.

Punchy! flips the X axis when it reads bones and cubes, the same left to right flip Bedrock models need. Model the way Blockbench shows the model and do not mirror anything by hand to compensate.

The file and its texture size

The texture grid is the size UV values are written in. Punchy! divides every UV number by it, so the PNG itself does not have to match. A 64 by 64 PNG on a 16 by 16 grid works: each UV pixel then covers a 4 by 4 block of the PNG, and you can paint finer detail without touching a single UV. Keep the same proportions: a PNG twice as wide as it is tall needs a grid twice as wide as it is tall.

For an animated texture, compare one frame with the grid. Four stacked 16 by 16 frames make a 16 by 64 PNG on a 16 by 16 grid, as in the stick.

A UV that runs past the edge of the grid is clamped to the edge. It does not repeat.

Bones

Cubes

A cube with a size of 0 on one axis is a flat card. Punchy! draws only its two broad faces, the ones that face along the zero axis. A card of size [8, 8, 0] shows its north and south faces, and a card of size [0, 8, 8] shows east and west. A cube that is flat on two axes keeps only its largest face.

Faces and UV

The uv object has one entry per face. The names are north, south, east, west, up and down, in any case. Only the faces you list are drawn, so leave out a face nobody can see.

Textures

The definition’s texture key names the main texture, the one every bone uses unless it has a bone texture. It is a PNG file.

Punchy! adds what is missing to a texture id:

A path that starts with punchy/model_parts_items/textures/ only gets .png added if it is missing. Any other path gets textures/ in front unless it already starts with textures/, and .png at the end unless it already ends with .png. The same rule applies to the texture ids in bone_textures.

The geo key is different. Punchy! uses it exactly as written, so write the whole id, including the folders and the .geo.json ending, as in the example.

Transparent and half transparent pixels in a texture are see-through, which is how you make glass.

Bone textures

bone_textures gives a bone its own texture. It is the way to keep a glowing part, a liquid or a gem in a separate PNG. A bone texture is also used by the bone’s children, unless a child has one of its own. In Studio, pick it in the Texture list of the Bone tab.

{
  "bone_textures": {
    "gem": "minecraft:punchy/model_parts_items/textures/gem_blue",
    "metal": "minecraft:punchy/model_parts_items/textures/metal_dark"
  }
}

The same thing as a list, which is shorter when several bones share a texture:

{
  "bone_textures": [
    {
      "texture": "minecraft:punchy/model_parts_items/textures/gem_blue",
      "bones": ["gem", "gem_inner"]
    },
    {
      "texture": "minecraft:punchy/model_parts_items/textures/metal_dark",
      "bones": ["frame", "handle"]
    }
  ]
}

Punchy! looks up a bone’s texture in this order: the exact bone name, then the same name ignoring case and spaces at the ends, then the bone’s parent, then its parent’s parent and so on, and last the main texture.

A bone texture uses the same UV grid as the main texture. Lay out the faces on the grid once and give every texture the same layout and proportions. For textures that change while the game runs, see dynamic textures.

Texture animation

Put the frames of an animated texture one under the other in one tall PNG. Punchy! then shows one frame at a time. Two keys switch it on: texture_anim for the whole model, and bone_texture_anim for single bones.

{
  "texture_anim": {
    "frames": 8,
    "frametime": 2
  },
  "bone_texture_anim": {
    "water": { "frames": 6, "frametime": 4 }
  }
}

The rules:

• The PNG must be exactly frame_height times frames pixels tall. In the stick, the grid is 16 high, so four frames make a PNG 64 pixels tall. If the height is off by even one pixel, the animation stops. The grid is then stretched over the whole PNG, so all the frames show at once, squeezed together. Punchy! says nothing in game, but Studio warns you.
• A PNG that is bigger than the grid works too: with a 16 by 16 grid and a PNG that has 64 by 64 pixel frames, set frame_height to 64.
• The faces on the UV grid describe one frame. Punchy! moves them down the PNG for you, so draw the first frame’s layout once.
• texture_anim applies to the main texture and to every bone texture that has no bone_texture_anim entry of its own. Each texture is checked against its own height, and a texture that does not fit stops animating and shows all its frames squeezed together.
• A bone_texture_anim entry replaces the whole model’s values for that bone. A key you leave out in it is not copied from texture_anim: it goes back to its default. Write all the keys you need.
• A bone’s animation is looked up by the exact bone name. Children of that bone do not take it.
• The frames play from the age of the player in ticks, so the animation keeps running and is not tied to the moment you pick the item up.
• A glowing bone animates with its texture: the glow is drawn from the same frame.

Animated particle textures

Particles use a different, simpler rule. Name the frames of a particle’s texture with a number at the end: flame_0.png, flame_1.png, flame_2.png. Punchy! counts upward from _0 until the first number with no file, up to 64 frames, and plays them at 12 frames a second. Particles covers the rest of the particle keys.

Hiding back faces on glass and flames

camera_transparent_bones is a key of the definition, not of the geometry. It lists the bones that should not draw the faces turned away from you, which is what you want for glass and flame cards that you look at from inside.

{
  "camera_transparent_bones": ["glass"]
}

The faces turned away from the camera are left out for the named bones and for every bone under them. It does not apply to a bone that has physics. inside_visible_bones means the same, but it is read only when camera_transparent_bones is missing. In Studio, tick Camera Transparent under Flags in the Bone tab. Model part definitions covers the key with the other definition fields.

Glow

bone_emission makes bones glow. A glowing bone is drawn a second time on top of itself at full brightness, so it stays bright in the dark while the rest of the model is shaded as usual. It shows best at night, in caves and in shade.

{
  "bone_emission": {
    "flame": 100,
    "ember": 40,
    "strength": 100,
    "blur": true,
    "clamp": false
  }
}

What a level does:

Three things to remember:

• The whole bone glows, every opaque pixel of its texture. To make only part of a texture glow, put that part in its own bone.
• blur, clamp, strength, intensity and brightness are the special keys of this object. A bone with one of those names, in any case, cannot glow. Rename the bone.
• With a shader pack on, Punchy! hands the glow to the shader pack, so it can look different. Check a glowing model with your shader pack on.

In Studio, a bone’s glow is the Glow Level field in the Bone tab, and the three model-wide settings are Glow Strength, Blur Glow and Clamp Glow under Glow Settings in the Material tab. View > Show Glow previews it on the stage. The texture animation fields are Frames, Frame Time and Frame Height: in the Material tab for the whole model (Texture Animation) and in the Bone tab for one bone (Bone Texture Animation). A Frame Height of 0 leaves the key out, so the grid height is used. Studio warns you when the texture’s height does not fit.

Video coming soon

Light a whole model part

bone_emission lights single bones. To change how a whole held item is lit, add a rules file to the pack: assets/<namespace>/punchy/model_parts_items/shading.json. It sits next to the definitions folder and belongs to no single definition. Each rule names an item, a texture or both, and sets any of these:

• fullbright: true draws the model part without the light map, so the whole item stays bright in the dark, and your hand does not show through it. The default is false.
• shading: false lights every face evenly, without the game’s directional shading. The default is true.
• additive: true makes every particle drawn while that item is held blend additively, and false stops it. A rule decides over a particle’s own additive key. Particles covers it.

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

The item is a lower case id, and minecraft: may be left out. With both an item and a texture, both must match. A texture is written as in a definition, and textures/ and .png may be left out. A value is true or false. The text true and false, yes and no, on and off, and 1 and 0 are read too. fullbright and shading change only items a pack draws as model parts.

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. A file that is not valid JSON gives no rules, and Punchy! says nothing. Press F3+T after you change the file. Shading rules lists the keys in one place.

The Export Model Part window of Studio does not write this file. Write it in a text editor and put it in your pack by hand.

Model parts under a shader pack

While a shader pack, or a mod that replaces the game’s entity shaders, is drawing the world, Punchy! draws every face of a model part whose texture pixels are all opaque as solid, so your hand never shows through the item. Only a face that covers a half see-through pixel (an alpha from 1 to 254) stays see-through, such as the surface of the water in a bucket. The solid faces of a fullbright part get full light. Without a shader pack or such a mod, the faces are drawn the usual way, except that a fullbright part is still solid, so your hand does not show through it.

Keep each face either fully opaque or see-through on purpose. A face that covers even one half see-through pixel is drawn see-through. The glow of a bone is still handed to the shader pack, as described above.

Mirroring and the left hand

You build one model, and Punchy! uses it for both hands. In the left hand it flips the whole model on the X axis for you. Item clips can have a _left and a _right version for each hand. Item clips explains how Punchy! picks one.

Inside the geometry, mirroring works on single cubes and faces:

• A cube with "mirror": true is drawn mirrored. Its east and west faces trade sides, its up and down faces trade sides, and the pictures on its north and south faces are flipped left to right. It only works on cubes with per-face UV.
• A face with a negative uv_size is flipped without touching the rest of the cube. In Studio, Flip U and Flip V in the UV editor do it.

Things that make Punchy! skip your model

Punchy! prints no message for any of these. Where it says the vanilla item draws, you see the normal item in your hand and nothing in the log.

• The geometry is in the old layout. The root of the file must hold a minecraft:geometry list. A file that starts with geometry.something and has no list is not used, and the vanilla item draws. Use Blockbench’s Bedrock Entity format.
• A bone has no name. The whole geometry fails to load, and the vanilla item draws.
• The geo id is wrong. It must be the full id with .geo.json. A wrong id leaves the vanilla item in your hand.
• A list of numbers is something else. A single number or an object where a list belongs, or words inside the list, in pivot, origin, size, rotation, or in a face’s uv or uv_size, stops the geometry from loading, and the vanilla item draws. A cube whose uv is neither an object nor a list is not drawn, and nothing else fails.
• A cube has no uv object, or its faces lack uv or uv_size. That cube, or that face, is not drawn. Box UV needs more care: see the warning above.
• A value of the wrong kind in the definition. An empty list, a list of several values or an object where a number belongs in texture_anim makes Punchy! drop the whole definition. So does a bones value that is not a list in an entry of the list form of bone_textures that has a valid texture. In the object form of bone_textures, a value that is a list or an object is skipped, and that bone is treated as if it were not listed.

Why my model looks wrong

• The model looks stretched or shifted on the texture. The texture_width and texture_height of the geometry do not match the proportions of your PNG, or the UV rectangles are off. Check the Project window in Blockbench, or the UV editor in Studio.
• A face shows one stretched color. Its UV runs past the edge of the grid. UV is clamped to the edge, not repeated.
• A flat card shows only one side. A card shows the two faces that lie flat, so give both of them a UV. Cards that are flat on two axes show a single face.
• A bone does not follow its parent. The parent key does not match a bone name exactly. Names are case sensitive.
• The texture animation does not move. The PNG height is not frames times the frame height, frames is 1, or the texture is missing. Studio’s Lint panel in the Definition tab names the problem.
• A bone does not glow. The name in bone_emission does not match the bone exactly, the bone is named like one of the special keys, or strength is 0. Bright daylight can make the glow hard to see, but it does not turn it off. If you use levels from 16 to 100 and see no difference, turn blur on.
• The glow is too soft or has a halo. Turn blur off, or lower the bone’s level.
• The whole item is dark at night, not only a part of it. Only bones in bone_emission glow. To keep the whole item bright, add a fullbright rule to shading.json: see Light a whole model part.
• The model does not show when I look at another player or the inventory. Model parts draw in your own first person hands only.

Related pages

• Model parts: the overview of how a definition, its files and its extras fit together.
• Model part definitions: the fields that match items, set display and link clips.
• Item clips: animate the bones you named here.
• Particles: put emitters on a bone, such as the flame of a torch.
• Flags reference: the keys of shading.json.
• Dynamic textures: swap a bone’s texture or the whole geometry while the game runs.
• Punchy! Studio: the Model workspace, with its UV editor, painting and live link.
• Torch pack tutorial: glow, an animated flame and particles together.