Custom Model Data & Item Models¶

CuriosPaper supports two methods for applying custom textures to items, depending on your Minecraft version.

Version Compatibility¶

Method	Minecraft Version	Config Key	Type
CustomModelData	1.14 – 1.21.2	`custom-model-data`	Integer
Item Model	1.21.3+	`item-model`	NamespacedKey

Auto-Detection

CuriosPaper automatically detects your server version and uses the appropriate method. You can define both in your configs for cross-version compatibility.

CustomModelData (1.14 – 1.21.2)¶

How It Works¶

Each slot type and custom item has a custom-model-data integer
The resource pack contains model override JSON files
When the item is displayed, Minecraft uses the matching custom model

Setting CustomModelData¶

In config.yml for slot icons:

slots:
  ring:
    custom-model-data: 10008

In item YAML files:

custom-model-data: 20001

Resource Pack Structure¶

For a PAPER base material with CustomModelData:

assets/minecraft/models/item/paper.json

{
  "parent": "item/generated",
  "textures": {
    "layer0": "item/paper"
  },
  "overrides": [
    { "predicate": { "custom_model_data": 10008 }, "model": "curiospaper/item/ring_slot" }
  ]
}

And the custom model at:

assets/curiospaper/models/item/ring_slot.json
assets/curiospaper/textures/item/ring_slot.png

Item Model (1.21.3+)¶

How It Works¶

Each item has an item-model NamespacedKey (e.g., curiospaper:ring_slot)
Minecraft resolves the model directly from the namespace
No override JSON needed — cleaner and more efficient

Setting Item Model¶

In config.yml for slot icons:

slots:
  ring:
    item-model: "curiospaper:ring_slot"

In item YAML files:

item-model: "myplugin:my_ring"

Resource Pack Structure¶

assets/curiospaper/models/item/ring_slot.json
assets/curiospaper/textures/item/ring_slot.png

Model JSON (ring_slot.json):

{
  "parent": "item/generated",
  "textures": {
    "layer0": "curiospaper:item/ring_slot"
  }
}

Base Material¶

The base-material setting in config.yml determines which vanilla item the custom models are based on:

resource-pack:
  base-material: "PAPER"

Common choices:

Material	Pros	Cons
`PAPER`	Simple, stackable	May conflict with other plugins
`LEATHER_HORSE_ARMOR`	Unique, rarely used	Not stackable

Creating Custom Textures¶

Create a 16×16 or 32×32 PNG texture
Place it in the appropriate textures/ directory
Create a model JSON that references the texture
Set the custom-model-data or item-model in your config
Run /curios rp rebuild to regenerate the pack