🟰 Item Models

This page mainly explains how to configure models for an item.

Since version 1.21.4, Minecraft has started supporting more complex item models. This allows you to create more dynamic variants for items. This tutorial is specifically for version 1.21.4 and above. For older versions, the plugin will downgrade the corresponding model files (note: this is not 100% compatible with older versions, as many conditions and model types do not exist in older versions).

Introduction

Let's take the simplest minecraft:model 📐 Model type as an example.

items:
  default:topaz_pickaxe:
    model:
      type: minecraft:model
      path: minecraft:item/custom/topaz_pickaxe
      generation:
        parent: "minecraft:item/handheld"
        textures:
          "layer0": "minecraft:item/custom/topaz_pickaxe"

If you do not specify a type, it will default to using minecraft:model. Therefore, the configuration above is the same as the configuration below.

items:
  default:topaz_pickaxe:
    model:
      path: minecraft:item/custom/topaz_pickaxe
      generation:
        parent: "minecraft:item/handheld"
        textures:
          "layer0": "minecraft:item/custom/topaz_pickaxe"

If you are unsure how to handle model generation and model path specification, please read 🏭️ Model Generation.

From the above configuration, we can see that under the model section, you are required to fill in the type of the model and its corresponding parameters. Below is a list of all available model types. Some models (such as range dispatch, select, composite, and condition) support nested model usage. You can click on the link below to jump to the corresponding model type. Once you have read through all of them, we will proceed to discuss more complex examples.

📐 Model

🧩 Composite

⚖️ Condition

📡 Range Dispatch

✅ Select

Examples

In the following example, a template for automatically generating a 2D crossbow is created by combining condition, model, and range_dispatch.

templates:
  models:crossbow_2d:
    type: "minecraft:condition"
    property: "minecraft:using_item"
    on-false:
      type: "minecraft:select"
      property: "minecraft:charge_type"
      cases:
        - when: arrow
          model:
            type: minecraft:model
            path: "{crossbow_arrow_model}"
            generation:
              parent: "minecraft:item/crossbow_arrow"
              textures:
                "layer0": "{crossbow_arrow_texture}"
        - when: rocket
          model:
            type: minecraft:model
            path: "{crossbow_firework_model}"
            generation:
              parent: "minecraft:item/crossbow_firework"
              textures:
                "layer0": "{crossbow_firework_texture}"
      fallback:
        type: minecraft:model
        path: "{crossbow_model}"
        generation:
          parent: "minecraft:item/crossbow"
          textures:
            "layer0": "{crossbow_texture}"
    on-true:
      type: "minecraft:range_dispatch"
      property: "minecraft:crossbow/pull"
      entries:
        - model:
            type: minecraft:model
            path: "{crossbow_pulling_1_model}"
            generation:
              parent: "minecraft:item/crossbow_pulling_1"
              textures:
                "layer0": "{crossbow_pulling_1_texture}"
          threshold: 0.58
        - model:
            type: minecraft:model
            path: "{crossbow_pulling_2_model}"
            generation:
              parent: "minecraft:item/crossbow_pulling_2"
              textures:
                "layer0": "{crossbow_pulling_2_texture}"
          threshold: 1.0
      fallback:
        type: minecraft:model
        path: "{crossbow_pulling_0_model}"
        generation:
          parent: "minecraft:item/crossbow_pulling_0"
          textures:
            "layer0": "{crossbow_pulling_0_texture}"