Cyn's CustomModelData

A Spigot/Paper plugin for Minecraft 1.21.11 (Java 21+) that makes working with custom_model_data - the component resource packs use to swap item models - quick and painless. Set model data on the item in your hand, edit it (plus attributes, enchants, damage, potion effects and more) in a live GUI item editor, mass-apply model data from config rules, and bind model data to item display names so named items always get the right model.

Install

1. Drop the jar into plugins/.
2. Start the server (Paper 1.21.11 recommended). plugins/CustomModelData/config.yml is generated.
3. Edit the config and run /cmddata reload.

GUI item editor

Hold an item and run /cmddata gui. Every change is applied to the item immediately, so the preview is exactly what you hold. The layout is consistent on every screen: back (top left), the item you are editing (top middle), close (top right), and the rest of the menu filled with the same buttons.

Main menu categories:

Button	What it edits
Model Data	custom_model_data ints and the float values
Name & Lore	display name, lore lines, colour codes
Enchantments	every enchantment that can apply to the item
Attributes & Stats	attack damage, speed, health, armour, ...
Damage & Durability	damage, max damage, unbreakable
Potion Effects	custom potion effects (potion items)
Misc Settings	stack size, rarity, glint, fire resistance, item model, tooltip flags

Plus revert all changes and undo (up to gui.undo-depth steps).

A centred number pad pops up whenever you need an exact numeric value; text values (name, lore, item model id) are typed in chat (cancel or clear supported).

Controls: left click add / +1 step, right click subtract, shift click big step, middle click open the number pad, Q drop to remove / clear.

Commands

Hand item:

• /cmddata gui - open the item editor
• /cmddata set <number> / /cmddata add <number> - set / add model data
• /cmddata get - show the current model data
• /cmddata reset - remove the model data component
• /cmddata hand - change your default hand (main / off)
• /cmddata give <player> <number> - set it on someone else (admin)

Name based (permanent bindings, saved to names.yml):

• /cmddata name set <name> <number> - rename the held item, set its model data and remember the binding
• /cmddata name apply - read the held item's name and apply the model data bound to it
• /cmddata name applyall [player] - apply every remembered name across an inventory
• /cmddata name bind/unbind/lookup/list - manage the bindings
• /cmdname <name> <number> / /cmdname <name> - shortcut for the same workflow

Mass change from config:

• /cmddata mass apply [self|all|<player>] - run the config rules
• /cmddata mass scan [self|all|<player>] - preview without changing anything
• /cmddata mass add/remove/list/test - edit rules inside config.yml
• /cmddata reload - reload the configs

Mass rule config

Simple form - mass.items:

mass:
  items:
    DIAMOND_SWORD: 1001          # by material
    minecraft:stone: 2000        # namespaced works too
    "Ruby Staff": 3000           # by the item's custom display name
    "@Light": 4001               # '@' forces name matching

Advanced form - mass.rules:

mass:
  rules:
    - item: LEATHER_HELMET       # required
      model-data: 5000           # required
      name: 'Ruby Cap'           # only match items with this custom name
      set-name: '&6Ruby Cap'     # give matched items this name
      data: 100                  # only match (and set) this damage value
      slots: [armor, storage]    # mainhand | offhand | armor | storage
      overwrite: false           # false = skip items that already have model data

Rules are applied in file order and the first matching rule wins for each stack. With settings.apply-on-join: true they run automatically for every player on join.

Permissions

Node	Default	Grants
cmddata.use	everyone	hand, name and GUI commands on yourself
cmddata.gui	everyone	open the item editor
cmddata.admin	op	mass rules, /cmddata give, /cmddata reload

Compatibility

Server side only. Tested on Paper 1.21.11, built against spigot-api 1.21.11-R0.1, requires Java 21+.