Skip to main content

๐ŸŽจ Item Model Definitions

In the beginner tutorial you gave an item a custom texture with one line. Now let's understand the system behind that line โ€” and what you can really do with it.

Model vs. item model definitionโ€‹

These two terms sound similar but mean different things:

ModelItem Model Definition
What it isA single JSON file โ€” geometry, textures, display transformsA JSON file that decides WHICH model(s) to render
Where it livesassets/<ns>/models/assets/<ns>/items/
AnalogyA single outfitA wardrobe that picks outfits based on context

A model is the static thing: block/cube_all, item/handheld, your BlockBench export. An item model definition is the logic that picks which model renders in each situation โ€” in hand vs. in GUI vs. on the ground, when damaged, when charging, and so on.

CraftEngine's model: field on items writes the item model definition. When you write:

items:
  tutorial:sword:
    material: golden_sword
    texture: tutorial:item/toxic_sword

CraftEngine generates an item model definition that says "always use this one model." That's the simplest case โ€” but the system goes far deeper.

The model typesโ€‹

An item model definition is a tree. Each node has a type. Six types exist:

TypeWhat it does
minecraft:modelRenders one static model file
minecraft:compositeLayers multiple models on top of each other
minecraft:conditionSwitches between two models based on a boolean property
minecraft:selectPicks a model from a set of cases based on an enum property
minecraft:range_dispatchPicks a model based on a number crossing thresholds
minecraft:specialRenders a hardcoded vanilla special model (head, banner, shieldโ€ฆ)

Example 1: static modelโ€‹

The one you already know โ€” always renders the same thing:

model:
  type: minecraft:model
  path: tutorial:item/sword

Or the shorthand:

model: tutorial:item/sword

Example 2: durability changes appearanceโ€‹

A sword that cracks as it wears down, using range_dispatch:

model:
  type: minecraft:range_dispatch
  property: minecraft:damage
  scale: 0.25
  entries:
    - threshold: 0.0
      model:
        type: minecraft:model
        path: tutorial:item/sword_pristine
    - threshold: 0.5
      model:
        type: minecraft:model
        path: tutorial:item/sword_damaged
    - threshold: 0.75
      model:
        type: minecraft:model
        path: tutorial:item/sword_broken

scale divides the durability fraction. When durability is above 75%, it's pristine; between 50โ€“75% shows cracks; below 50% looks nearly broken.

Example 3: layered glow effectโ€‹

A gem that has a static base with a pulsing glow layer on top, using composite:

model:
  type: minecraft:composite
  models:
    - type: minecraft:model
      path: tutorial:item/gem_glow
    - type: minecraft:model
      path: tutorial:item/gem_base

The glow layer can be a separate model with transparency โ€” it renders on top of the base. Combine with an animated texture for a pulsing effect.

Example 4: hotbar glowโ€‹

Shows a different model when the item is on the selected hotbar slot, using condition + minecraft:selected:

model:
  type: minecraft:condition
  property: minecraft:selected
  on_true:
    type: minecraft:model
    path: tutorial:item/sword_selected    # On the hotbar slot
  on_false:
    type: minecraft:model
    path: tutorial:item/sword_normal      # In inventory or other slots

Example 5: charging weapon (nested)โ€‹

A weapon that shows 3 charge levels AND cracks when damaged โ€” range_dispatch nested inside composite:

model:
  type: minecraft:composite
  models:
    - type: minecraft:condition
      property: minecraft:damaged
      on_true:
        type: minecraft:model
        path: tutorial:item/damage_overlay
      on_false:
        type: minecraft:empty
    - type: minecraft:range_dispatch
      property: minecraft:use_duration
      scale: 0.33
      entries:
        - threshold: 0.0
          model:
            type: minecraft:model
            path: tutorial:item/mace_idle
        - threshold: 0.33
          model:
            type: minecraft:model
            path: tutorial:item/mace_charging_1
        - threshold: 0.66
          model:
            type: minecraft:model
            path: tutorial:item/mace_charging_2

The damage cracks render ON TOP of the charging model. Both change independently. This can't be done with simple texture swaps โ€” it needs the composable tree structure.

Example 6: biome-aware toolโ€‹

A pickaxe that looks different in the Nether, using select + minecraft:context_dimension:

model:
  type: minecraft:select
  property: minecraft:context_dimension
  cases:
    - when: minecraft:the_nether
      model:
        type: minecraft:model
        path: tutorial:item/pickaxe_nether
    - when: minecraft:the_end
      model:
        type: minecraft:model
        path: tutorial:item/pickaxe_end
  fallback:
    type: minecraft:model
    path: tutorial:item/pickaxe_overworld

The item visually adapts to where the player stands. Combine with range_dispatch on durability and you have a pickaxe that looks different in each dimension AND shows damage.

Start simple

You don't need to build these trees by hand. CraftEngine's simplified syntax โ€” texture:, textures:, model: as a plain path โ€” covers 90% of use cases. The tree syntax is for the 10% that need it.