Custom Item Models (CIM)

Custom Item Models (CIM)

This feature is exclusive to 1.21+ as it uses its new components (also it probably wont survive 1.22 since mojang is adding similar things)

With CIM you'll be able to assing multiple arbitrary models to any items, similar to what bows do.

Some example are:

• Assing a model to named items
• Assing a model to items with a certain enchant

The system uses the vanilla Component system and is thus automatically compatible with ANY mod item and their associated components.

This means that watever item you are holding, if it has variants (being with different names, properties or data associated to it) you can give EACH of their combination a different model!

Preliminary concepts

This system is Components based. The entire syntax of a Component Map object that will be used below here can be read on the Official Minecraft Wiki.

Getting Started

You have two ways to add custom item models:

• via Item Modifiers
• via custom_item_models folder

In Item Modifiers

You can define a custom item model list directly in your items modifiers. More precisely you can add the custom_models field which will contain a LIST of model overrides. Syntax of your Item Modifier .json can be as follows:

{
  "custom_models": [
    {
      "model": "my_namespace:item/awesome_staff",
      "components": {
        "minecraft:custom_name": "\"awesome_staff\""
      }
    },
    {
      "model": "my_namespace:item/staff",
      "components": {
        "minecraft:custom_name": "\"staff\""
      },
      "stack_count": 1
    }
  ]
}

In this example we are assinging 2 models to an item when it is renamed to "staff" or "awesome_staff"

As you can see the file contains a custom_models field which houses a list of Model Overrides. A Model override has the following syntax:

field	explanation
model	the location of the model file to apply (remember to add that to your pack)
components	The components the item needs to have to match. Note that the item can have other components too
stack_count	Required item stack count
name_pattern	A regex pattern that will match the item custom name. Only use this if you really need it as its slower. For exact match use the component name instead
entity_nbt	Contains a partial entity NBT which the holding entity will need to have in order for this model to be applied (can contain partial matches)
item_nbt_components	A map of component types to NBT. The NBT is gotten from one of the few "custom_data" component types in the game which contain NBT. Can contain partial matches
expression	A math expression for further filtering. Notably you can use the DAMAGE variable here to filter items with a range of damage falues. The expression will evaluate to true when its output is not zero.

NOTE:

Try to avoid using the last 3 fields when possible as those will need to be checked every render tick for all your models for a specific item. Using just the components one will be much faster especially when one has many item models for a single item.

Also you can NOT use the auto generated generated model type here. Only references to actual model files

In Custom Item Models Folder

This alternative method to defining CIM exist simply to make it easier and cleaner for pack makers to add models. Also the fact that Item Modifiers can target multuple items at once make them a bit less intutive and suited for this task.

To start you'll need to create a .json file in your resource pack folder in assets/[your namespace]/polytone/custom_item_models/[some name].json.

The name of the file and namespace has little importance here.

Here is how a simple one could look like:

{
  "item": "minecraft:leather_chestplate",
  "model": "generated",
  "components": {
    "minecraft:dyed_color": {
       "rgb": -1
     }
  }
}

The json syntax is the same as the one previously see in item modifiers, with the addition of the item field which specifies the only target.

field	explanation
item	target item that will have this model
components	A Component Map containing all the components and their values. Each of them will need to match what an item has for the model to be applied
model	Path to the model file. When left to generated, the mod will automatically generate a flat item model for you, provided you have a texture file
stack_count	Required item stack count
name_pattern	A regex pattern that will match the item custom name. Only use this if you really need it as its slower. For exact match use the component name instead
name_pattern	A regex pattern that will match the item custom name. Only use this if you really need it as its slower. For exact match use the component name instead
entity_nbt	Contains a partial entity NBT which the holding entity will need to have in order for this model to be applied
item_nbt_components	A map of component types to NBT. The NBT is gotten from one of the few "custom_data" component types in the game which contain NBT. Can contain partial matches
expression	A math expression for further filtering. Notably you can use the DAMAGE variable here to filter items with a range of damage falues. The expression will evaluate to true when its output is not zero.

As explained above the generated model can be used as a shorthand to avoid having to manually add a model json. For it to be valid simply add a .png file with the same name as your .json in the same directory.

Tips

• If you want to have a specific item only appear when on your head or maybe in the inventory, you can use a separate_transform model. Check that out on the Exta Featurs page

• If you want to easily see what the Components of an item are, you can use the /data get command on your player or a dropped item. Component syntax is same as its used anywhere else in the game, such as in recipes, so those are another place where you can find examples.

• When not using the generated model type, remember that you will have to manually add a model file in your resource pack

NBT match example

This field is used to PARTIALLY match one of the CustomData component types (components that hold NBT). This must ONLY be used when partial matching is need. If exact one is needed you should use the components block normally. The components that this applies to in vanilla are custom_data, entity_data, block_entity_data and bucket_entity_data. Mods might add more. Here's an example

{
  "item": "minecraft:salmon_bucket",
  "model": "my_namespace:item/my_custom_model",
  "item_nbt_components": {
     "minecraft:bucket_entity_data": {
       "age": 0
     }
  }
}