How to make 3D items and custom models in a Minecraft texture pack

What a Minecraft model is

Java Edition 1.8 and newer draws most blocks and items from model files in the resource pack:

• assets/minecraft/models/block/ holds block models, such as oak_slab.json. A blockstate file in blockstates/ says which model a block uses in each state: a slab at the bottom or the top, a log on its side.
• assets/minecraft/models/item/ holds item models. Most items use a flat model (item/generated): the game turns the 16×16 sprite into a thin shape by itself. Since 1.21.4, an item model definition in assets/minecraft/items/ says which model an item shows.

A model file has four main parts:

• textures: names for the textures the model uses, such as "oak_planks": "minecraft:block/oak_planks". particle is the texture of the breaking particles.
• elements: the cubes. Each one runs from one corner to the opposite one, measured in pixels of a 16 × 16 × 16 block, and may reach from -16 to 32 on each axis. A cube can be turned with rotation.
• faces: for each side of a cube (down, up, north, south, west, east), the texture it shows, the part of the texture (uv), and cullface, which skips the face when a full block covers that side.
• display: how the model is turned, moved and scaled in the inventory (gui), in the hands, on the ground, in an item frame (fixed) and on the head.

This is a one-cube model shaped like a slab, laid out the way the model editor writes it. A file made in the editor lists the display of every slot, not only the inventory:

{
  "textures": {
    "oak_planks": "minecraft:block/oak_planks",
    "particle": "#oak_planks"
  },
  "elements": [
    {
      "from": [0, 0, 0],
      "to": [16, 8, 16],
      "faces": {
        "down": {
          "texture": "#oak_planks",
          "cullface": "down"
        },
        "up": {
          "texture": "#oak_planks"
        },
        "north": {
          "texture": "#oak_planks",
          "cullface": "north"
        },
        "south": {
          "texture": "#oak_planks",
          "cullface": "south"
        },
        "west": {
          "texture": "#oak_planks",
          "cullface": "west"
        },
        "east": {
          "texture": "#oak_planks",
          "cullface": "east"
        }
      }
    }
  ],
  "display": {
    "gui": {
      "rotation": [30, 225, 0],
      "translation": [0, 0, 0],
      "scale": [0.625, 0.625, 0.625]
    }
  }
}

Hand-made models often use "parent" to borrow the textures, cubes or display of another model. The model editor writes self-contained files instead: everything it read from the parent models is copied in, so your file does not depend on another one.

Make a 3D item step by step

1. Open the Texture Pack Maker and create a Java pack for the version you play: 1.8 or newer, or 1.21.4 or newer to keep the item flat in the inventory.
2. Switch the list to Items and open the item, for example the diamond sword. In the Preview tab, press Edit shape.
3. Pick 3D item from sprite. Every pixel of the flat picture becomes part of a cube one pixel deep.
4. Change the shape: click a cube in the 3D view or the list, then move it, resize it, copy it or add new ones. Under Faces, give a face another texture or another part of one.
5. Open Display and check the model in the inventory, in first and third person, on the ground, in an item frame and on the head. Change the rotation, position or size where it looks wrong.
6. Optional, on 1.21.4 and newer: in the Model tab, turn on Flat in the inventory to keep the flat icon there and show the 3D model in hand.
7. Press Done, export the pack as a .zip, put it in your resourcepacks folder and test it in game.

How “3D item from sprite” works

A flat item is a single picture, its sprite, usually 16×16 pixels. The start point takes every pixel that is not transparent and builds cubes one pixel deep from them, centred the way the game centres its own flat items (from 7.5 to 8.5 on the z axis). Pixels in a row are joined into one long cube, and equal rows below each other into a rectangle, so the diamond sword becomes 19 cubes instead of one cube per pixel. Faces that a neighbouring pixel hides completely are left out.

Each face shows the matching pixels of the sprite. Three pixels in a row, in columns 5 to 7 of row 3, become this cube:

{
  "from": [5, 12, 7.5],
  "to": [8, 13, 8.5],
  "faces": {
    "down": {
      "uv": [5, 3, 8, 4],
      "texture": "#layer0",
      "tintindex": 0
    },
    "up": {
      "uv": [5, 3, 8, 4],
      "texture": "#layer0",
      "tintindex": 0
    },
    "north": {
      "uv": [8, 3, 5, 4],
      "texture": "#layer0",
      "tintindex": 0
    },
    "south": {
      "uv": [5, 3, 8, 4],
      "texture": "#layer0",
      "tintindex": 0
    },
    "west": {
      "uv": [5, 3, 6, 4],
      "texture": "#layer0",
      "tintindex": 0
    },
    "east": {
      "uv": [7, 3, 8, 4],
      "texture": "#layer0",
      "tintindex": 0
    }
  }
}

The front (south) shows the pixels as they are and the back (north) shows them mirrored, as you see a picture from behind. The cubes keep using the item’s own texture (#layer0), so repainting the sprite recolours the 3D item. Pixels you add or erase only change the shape when you pick 3D item from sprite again. Items with several layers, such as potions or leather armour, get cubes for every layer, and the game still colours them.

Then make it your own:

• Make the blade thicker: select its cubes and change their Z position and size, for example from 7.5 and 1 to 7 and 2.
• Add a cube for a guard or a gem with the + button (or N), and give its faces another texture under Faces > Change.
• Turn a cube under Rotation. Before Minecraft 1.21.6 a cube turns on one axis only, by -45°, -22.5°, 0°, 22.5° or 45°; the editor offers what your version accepts.
• Undo any change with Ctrl+Z.

Set how it is held: Display

The Display tab previews the model in six places. Each has a rotation in degrees, a position in pixels (up to ±80) and a size (1 is normal, 4 at most).

3D item from sprite keeps the item’s own display settings, so a 3D sword is held like the flat one. Game’s default puts a slot back to the game’s values, and No change removes the setting. Java 1.21.9 added an on_shelf slot for shelves; the editor keeps the value from the game’s model.

Keep the flat icon in the inventory (1.21.4+)

Many 3D packs keep the familiar flat icon in the inventory and show the 3D model only in hand. Since Java 1.21.4, an item model definition can choose a model by where the item is shown. Turn on Flat in the inventory in the Model tab and the editor:

• saves your shape as a second model, models/item/diamond_sword_3d.json, and leaves the flat diamond_sword.json as it is;
• writes items/diamond_sword.json, which shows the flat model in the inventory (gui), on the ground and in item frames (fixed), and the 3D one everywhere else:

{
  "model": {
    "type": "minecraft:select",
    "property": "minecraft:display_context",
    "cases": [
      {
        "when": ["gui", "ground", "fixed"],
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:item/diamond_sword"
        }
      }
    ],
    "fallback": {
      "type": "minecraft:model",
      "model": "minecraft:item/diamond_sword_3d"
    }
  }
}

Versions before 1.21.4 have no item definitions, so an item shows the same model everywhere and the switch is not offered.

Change the shape of a block

Blocks work the same way. Show a block in the Preview tab and press Edit shape. The editor opens the model the block uses in the state you are looking at, and the menu at the top lists its other models, such as the top and double versions of a slab. Keep the game’s model or start from Full cube, Slab, Cross (plant) or Empty, then add, move and resize cubes. Turning stone into a step takes the Slab start point and one more cube:

• Shared models: some blocks use the same model file. When another block uses the model you edit, the editor tells you which; it changes too.
• Items stay separate: an item that shows a block model, such as a slab in your hand, gets its own item model when you edit the item, so the block keeps its shape.
• Only the look changes: the hitbox, collision and light come from the game’s code. A stone block shaped like a step still stops you like a full block, and the blocks next to it still hide the faces that touch it, which can leave see-through gaps.
• Blocks drawn by code: chests, beds, signs, banners and other blocks the game draws itself have no block model, so Edit shape is not offered for them. Items drawn by code, such as the shield, can be given a model, which replaces that look.

Stone and some other blocks pick between two models at random: stone and a mirrored copy, each also turned around. Use for every random variant in the Model tab puts your shape on all of them by writing the block’s blockstate file. The "y": 180 entry keeps the random turn, and weight sets how often each entry is picked:

{
  "variants": {
    "": [
      {
        "model": "minecraft:block/stone",
        "weight": 2
      },
      {
        "model": "minecraft:block/stone",
        "y": 180,
        "weight": 2
      }
    ]
  }
}

Which files go in the pack

Every path is inside assets/minecraft/. Every Java version from 1.8 gets the same files; only flat in the inventory needs 1.21.4 or newer. The editor adds an item definition or a blockstate only when the game needs one, and model files already in a pack you open are kept and can be edited. When you export, every model is checked against your game version, and you get a warning for anything that would not load.

What changed between versions

The model editor follows these rules for the version your pack is made for.

Install and test it

1. Press Done to leave the model editor, then Export the pack as a .zip.
2. In Minecraft open Options… > Resource Packs… > Open Pack Folder, drop the zip in (keep it zipped) and move the pack to Selected, above other packs.
3. Hold the item, press F5 for third person, drop it, and put it in an item frame to check every display.
4. After changing the model, export again, replace the zip and press F3 + T in game to reload the packs.

More help: How to install resource packs and Texture pack not working.

Bedrock Edition

Bedrock packs work differently, and the model editor makes Java models only:

• Blocks: a Bedrock resource pack cannot change the shape of the game’s blocks. A custom-shaped block is a new block, added by an add-on with a behaviour pack and a geometry file.
• Held items: Bedrock gives items a 3D model in hand with attachables, resource pack files that use Bedrock geometry and animation. The Texture Pack Maker does not make them; Blockbench can.
• A starting point: in the model editor’s menu, Download as Bedrock geometry saves your model as a .geo.json file (format 1.12.0, one bone, all cubes) to import into Blockbench or an add-on. Bedrock geometry uses a single texture, so each face keeps its place on its own texture.

In a Bedrock pack, Edit shape explains this instead of opening the editor. Painting textures works as usual.

Common problems

• Purple and black faces: a face uses a texture the game cannot find: a name (#…) that is not set under textures, a file that is not in the game or the pack, or, since 1.19.3, a texture outside the atlas folders. The Model tab lists these problems with the cube they are on.
• A purple and black cube instead of the model: the file did not load. Usual causes are broken JSON, a cube outside -16 to 32, or a rotation the version does not allow. The game’s log names the file.
• The model does not show at all: check that the pack is selected and above other packs, that the file has exactly the name and folder of the model it replaces, and, on 1.21.4 and newer, that a new model (such as a _3d copy) has an item definition pointing at it.
• Fine in hand, odd in the inventory: adjust the Inventory display, try the other inventory light (side or front), or turn on Flat in the inventory.
• Too many cubes: every cube adds faces to draw. That hardly matters for an item in your hand, but a block placed thousands of times should stay simple. Keep the joined cubes that 3D item from sprite makes instead of splitting them up.
• An angle is not allowed: before 1.21.6 a cube turns by 22.5° steps up to 45°, on one axis. For a quarter turn, swap the cube’s size on two axes instead; for other shapes, build them from more cubes.

More fixes for packs in general: Texture pack not working? Fixes.

Questions