๐ฐ Item Models
Introductionโ
Since version 1.21.4, Minecraft has started supporting more complex item models. This allows you to create more dynamic variants for items. This document 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).
If you discover that CraftEngine lacks some features in latest Minecraft version, you might submit an issue on GitHub to bring this to the attention of the developers.
Simplified Modelsโ
The purpose of a simplified model is to reduce the configuration overhead for common use cases. Although CraftEngine provides templates, using parameters still requires 3-4 lines of configuration. Simplified models lower this barrier at the cost of some flexibility.
Simplified Models are intelligent. They automatically analyze your chosen base material and select the most appropriate method to generate the model. In most cases, simply specifying a texture parameter is all you need to get everything working.
In the following examples, a series of configuration comparisons between simplified models and normal models will be provided. This will help you understand the corresponding normal model configuration while using the simplified approach.
2D iconsโ
Simplified
items:
default:ender_pearl_flower_seeds:
material: paper
texture: minecraft:item/custom/ender_pearl_flower_seeds
Normal
items:
default:ender_pearl_flower_seeds:
material: paper
model:
type: minecraft:model
path: minecraft:item/custom/ender_pearl_flower_seeds
generation:
parent: minecraft:item/generated
textures:
layer0: minecraft:item/custom/ender_pearl_flower_seeds
Handheld itemsโ
Simplified
items:
default:topaz_axe:
material: golden_axe
texture: minecraft:item/custom/topaz_axe
Normal
items:
default:topaz_axe:
material: golden_axe
model:
type: minecraft:model
path: minecraft:item/custom/topaz_axe
generation:
parent: minecraft:item/handheld
textures:
layer0: minecraft:item/custom/topaz_axe
[1.21.4+] For simple 2D icons and handheld item models, configuring multiple textures will overlay the images, like this.
items:
default:topaz_axe:
material: golden_axe
textures:
- minecraft:item/custom/topaz_axe
- minecraft:item/custom/topaz
Fishing Rodโ
Simplified
items:
default:topaz_rod:
material: fishing_rod
textures:
- minecraft:item/custom/topaz_rod
- minecraft:item/custom/topaz_rod_cast
Normal
items:
default:topaz_rod:
material: fishing_rod
model:
type: minecraft:condition
property: minecraft:fishing_rod/cast
on-false:
type: minecraft:model
path: minecraft:item/custom/topaz_rod
generation:
parent: minecraft:item/fishing_rod
textures:
layer0: minecraft:item/custom/topaz_rod
on-true:
type: minecraft:model
path: minecraft:fishing_rod/cast
generation:
parent: minecraft:item/fishing_rod
textures:
layer0: minecraft:fishing_rod/cast
The following configuration only displays a simplified version. If you are curious about how the normal model is configured, you can refer to the default configuration template.
Elytraโ
items:
default:flame_elytra:
material: elytra
textures:
- minecraft:item/custom/flame_elytra
- minecraft:item/custom/flame_elytra_broken
Bowโ
items:
default:topaz_bow:
material: bow
textures:
- minecraft:item/custom/topaz_bow
- minecraft:item/custom/topaz_bow_pulling_0
- minecraft:item/custom/topaz_bow_pulling_1
- minecraft:item/custom/topaz_bow_pulling_2
Crossbowโ
items:
default:topaz_crossbow:
material: crossbow
textures:
- minecraft:item/custom/topaz_crossbow
- minecraft:item/custom/topaz_crossbow_pulling_0
- minecraft:item/custom/topaz_crossbow_pulling_1
- minecraft:item/custom/topaz_crossbow_pulling_2
- minecraft:item/custom/topaz_crossbow_arrow
- minecraft:item/custom/topaz_crossbow_firework
Shieldโ
items:
default:shield_3d:
material: shield
models:
- minecraft:item/custom/shield_3d
- minecraft:item/custom/shield_3d_blocking
If you already have model json files, you can directly specify the model path to apply the simplified model.
items:
default:rod_3d:
material: fishing_rod
models:
- minecraft:item/custom/rod_3d
- minecraft:item/custom/rod_3d_cast
items:
default:exit_icon:
material: paper
model: minecraft:item/custom/exit_icon
Normally, when you have only specified the textures, the item's model JSON path is automatically assigned. You can manually specify the path using the 'model' option, as shown in the example below.
items:
default:ender_pearl_flower_seeds:
material: paper
model: minecraft:item/custom/ender_pearl_flower_seeds
texture: minecraft:item/custom/ender_pearl_flower_seeds
items:
default:topaz_rod:
material: fishing_rod
models:
- minecraft:item/custom/topaz_rod
- minecraft:item/custom/topaz_rod_cast
textures:
- minecraft:item/custom/topaz_rod
- minecraft:item/custom/topaz_rod_cast
Legacy Modelโ
Legacy Model specifically refers to the item model format used in versions 1.21.3 and earlier. You can specify the legacy item model format using the legacy-model section. However, in most cases, you donโt need to do this because the plugin will automatically convert 1.21.4 item models into the legacy format whenever possible. You should only use this configuration section if there are issues with the legacy model format.
items#topaz_gears:
default:topaz_rod:
material: fishing_rod
item-model: default:topaz_rod
settings:
tags:
- "default:topaz_tools"
data:
item-name: "<!i><#FF8C00><i18n:item.topaz_rod>"
tooltip-style: minecraft:topaz
model:
template: default:model/simplified_fishing_rod_2d
arguments:
path: minecraft:item/custom/topaz_rod
cast_path: minecraft:item/custom/topaz_rod_cast
# If you specify a model in the legacy-model section,
# the plugin will use your manually defined model instead of
# relying on the auto-converted legacy format.
legacy-model:
path: minecraft:item/custom/topaz_rod
overrides:
- path: minecraft:item/custom/topaz_rod_cast
predicate:
cast: 1
If you don't require support for versions above 1.21.4, you may configure only the legacy-model section and omit the model section entirely.