🔢 Item Data

Introduction

data sets the data components on an item stack — its name, lore, attributes, enchantments, food properties, and everything else that isn't the model or behavior. Most keys under data map directly to vanilla data components, with CraftEngine handling cross-version conversion automatically.

tip

Append #<id> to a data key to apply the same processor multiple times. The #id part is stripped during parsing and only serves to make the key unique:

data:
  insert_lore#1:
    position: TAIL
    lore:
      - "First insertion"
  insert_lore#2:
    position: HEAD
    lore:
      - "Second insertion"

Works with any data key: attribute_modifiers#main, attribute_modifiers#bonus, lore#static, lore#conditional, etc.

🎨 Appearance

item_name

The item's default name, present on all items by default. Unlike custom_name, this cannot be erased by an anvil, is not italicized, and does not display in certain labels such as banner markers or item frames. Alias: display_name.

items:
  demo:sword:
    data:
      item_name: "<!i><#FF8C00>Topaz Sword"

custom_name

A player-assigned name for the item, typically set via an anvil. Has highest priority for display and appears italicized by default.

items:
  demo:sword:
    data:
      custom_name: "<!i><#FF8C00>Topaz Sword"

lore

The item's description lines.

items:
  demo:sword:
    data:
      lore:
        - "What a shiny sword!"

For conditional lines, split text, or priority-based ordering:

lore:
  - content: "Priority 2"
    priority: 2
    operation: APPEND        # APPEND (default) | PREPEND
  - content: "Priority 1"
    priority: 1
  - content: "Split\nThis Line"
    split_lines: true
    conditions:
      - type: permission
        permission: craftengine.admin

Lower priority appears closer to the top. operation defaults to APPEND.

insert_lore

Inserts lines into existing lore at a specific position.

items:
  demo:sword:
    data:
      insert_lore:
        position: AFTER          # HEAD | TAIL | BEFORE | AFTER
        pattern: "Match this"    # Regex for BEFORE/AFTER
        lore:
          - content: "<green>Inserted line"
        fallback:                # Optional — if pattern doesn't match
          position: TAIL
          lore:
            - content: "<red>Fallback"

remove_lore

Removes lines matching a regex.

items:
  demo:sword:
    data:
      remove_lore: "Remove this line"

tooltip_style (1.21.2+)

The tooltip background texture.

items:
  demo:sword:
    data:
      tooltip_style: minecraft:topaz

hide_tooltip

Hides tooltips from specific components. Wraps vanilla minecraft:tooltip_display with cross-version support (formerly HideFlags).

items:
  demo:sword:
    data:
      hide_tooltip:
        - dyed_color
        - enchantments
        - attribute_modifiers

dyed_color

Color for dyeable items (leather armor, etc.).

items:
  demo:armor:
    data:
      dyed_color: 255,128,64

trim

Armor trim pattern and material.

items:
  demo:chestplate:
    data:
      trim:
        pattern: eye
        material: iron

custom_model_data

caution

custom_model_data inside data only sets a plain integer and does not bind models. To link a value to a model definition, configure it at the item root level instead.

# Inside data — sets the component, no model binding
items:
  demo:sword:
    data:
      custom_model_data: 10001

# At item root — sets the component AND binds to model definitions
items:
  demo:sword:
    custom_model_data: 10001

item_model (1.21.2+)

caution

item_model inside data only sets the component value and does not generate models. To link to a model definition and trigger model generation, configure it at the item root level instead.

# Inside data — sets the component, no model generation
items:
  demo:sword:
    data:
      item_model: default:sword

# At item root — sets the component AND triggers model generation
items:
  demo:sword:
    item_model: default:sword

profile

Sets a player head skin. Accepts strings (auto-detected as name, URL, or base64) or a map.

# By player name
profile: XiaoMoMi

# By texture URL
profile: http://textures.minecraft.net/texture/ed83db5c...

# By Base64
profile: eyJ0ZXh0dXJlcyI6...

# Map form (1.20.5+)
profile:
  name: XiaoMoMi       # Player name
  # texture: minecraft:entity/player/slim/alex  # Resource-pack texture path
  # url: https://...    # Texture URL
  # base64: eyJ0ZXh...  # Base64-encoded texture

⚡ Behavior

food (1.20.5+)

Sets the food stats applied when this item is consumed. The item must also have a consumable component to be edible.

items:
  demo:apple:
    material: apple
    data:
      food:
        nutrition: 5
        saturation: 3.5
        can_always_eat: false

equippable (1.21.2+)

Lets the item be worn in an equipment slot.

items:
  demo:helmet:
    data:
      equippable:
        slot: head
        asset_id: minecraft:topaz
        swappable: true
        damage_on_hurt: true
        dispensable: false

Field	Type	Description
slot	string	head / chest / legs / feet / body / mainhand / offhand / saddle
asset_id	asset path	Equipment model at assets/<ns>/equipment/<id>.json
camera_overlay	asset path	Overlay texture at assets/<ns>/textures/<id>
swappable	bool	Can be equipped by right-clicking
damage_on_hurt	bool	Takes durability damage when the wearer is hurt
dispensable	bool	Can be equipped via dispenser
equip_on_interact	bool	(1.21.5+) Can be equipped onto a mob by using on it

use_remainder (1.21.2+)

Replaces this item with the specified remainder when its stack count decreases after use.

items:
  demo:cooked_chicken:
    data:
      use_remainder:
        id: default:chicken_bone
        count: 1               # Optional, default 1

unbreakable

items:
  demo:sword:
    data:
      unbreakable: true

max_damage (1.20.5+)

The item's maximum durability.

items:
  demo:sword:
    material: wooden_sword
    data:
      max_damage: 100

attribute_modifiers

Applies attribute modifiers to the item. Alias: attributes.

items:
  demo:sword:
    data:
      attribute_modifiers:
        - type: attack_speed
          amount: 1.0
          operation: add_value
          id: namespace:custom_attribute   # Optional
          slot: mainhand

enchantment

items:
  demo:sword:
    data:
      enchantment:
        minecraft:sharpness: 3

enchantment:
  merge: true
  enchantments:
    minecraft:sharpness: 3

painting_variant

items:
  demo:painting:
    data:
      painting_variant: default:painting_custom

jukebox_playable (1.21+)

The jukebox song to play when this item is inserted into a jukebox.

items:
  demo:music_stick:
    material: stick
    data:
      jukebox_playable: default:credits_music

block_state

Block state properties applied when placing this item as a block. Also improves placement responsiveness for high-latency players. Alias: blockstate.

# Use detailed vanilla block properties
items:
  demo:sofa:
    material: note_block
    data:
      block_state:
        note: "1"
        powered: "false"
        instrument: "harp"

# Shorthand — copies block state from a defined custom block
items:
  demo:sapling:
    material: oak_sapling
    data:
      block_state: default:palm_sapling[stage=0]

tip

The material must visually match the block state. Use note_block or mushroom_stem instead of paper for block items.

If you have the premium version, you can use client_bound_material + client_bound_data.block_state to improve the client-side experience while keeping the original server-side material:

YAML

items:  default:palm_planks:    material: nether_brick    data:      item_name: <!i><i18n:item.palm_planks>+   client_bound_material: mushroom_stem+   client_bound_data:+     block_state: default:palm_planks    settings:      fuel_time: 300      tags:        - minecraft:planks        - minecraft:wooden_tool_materials    model: minecraft:block/custom/palm_planks    behavior:      type: block_item      block:        settings:          template: default:settings/planks        loot:          template: default:loot_table/self        state:-         auto_state: solid+         auto_state: mushroom_stem          texture: minecraft:block/custom/palm_planks

💾 Stored Data

pdc (Persistent Data Container)

Stores custom key-value data for other plugins to read.

items:
  demo:sword:
    data:
      pdc:
        key: "value"
        number: 42
        list:
          - 1
          - 2

tags / nbt

Low-level NBT access. Sets arbitrary NBT tags on the item. Use @ prefix on keys to flatten nested structures.

items:
  demo:sword:
    data:
      tags:
        CustomTag: "value"
        "@nested.path": 42

📦 External Data

Inherit data from another plugin's item.

items:
  default:example_item:
    data:
      external:
        plugin: neigeitems       # or "source"
        id: example_item

See External Item Sources for supported plugins.

🧩 Custom Components (1.20.5+)

Your own components — not maintained or version-checked by CraftEngine. Format may break across Minecraft updates. See the data component format on the Minecraft Wiki for the full component reference.

Components

★ max_damage

components:
  minecraft:max_damage: 128

★★ food

components:
  minecraft:food:
    nutrition: 4
    saturation: 2.0
    can_always_eat: false

★★ block_state

components:
  minecraft:block_state:
    distance: '1'
    persistent: 'false'

★★★ instrument

components:
  minecraft:instrument: "seek_goat_horn"

components:
  minecraft:instrument:
    description:
      text: "Custom Instrument"
      color: "red"
    sound_event: minecraft:block.note_block.bell
    use_duration: 1
    range: 16

★★★★ fireworks

components:
  minecraft:fireworks:
    flight_duration: 3
    explosions:
      - shape: small_ball
        colors: [11223344]
        fade_colors: [0]
        has_trail: true
        has_twinkle: true

tip

When a component needs only to be present (no value):

components:
  minecraft:unbreakable: {}

Remove Components

items:
  demo:item:
    data:
      remove_components:
        - minecraft:equippable

🔀 Conditional

Premium Exclusive

Different data based on conditions.

items:
  demo:mythic_sword:
    client_bound_data:
      conditional#1:
        conditions:
          - type: permission
            permission: item.unlock
        data:
          item_name: "Mythic Sword"
          lore:
            - "A blade forged in fallen stars"
      conditional#2:
        conditions:
          - type: "!permission"
            permission: item.unlock
        data:
          item_name: "???? Sword"

📡 Client Bound Data

Premium Exclusive

What it is

Normally, everything you put in data lives on the server-side ItemStack — every player sees the same thing, and every plugin reading the item sees all of its components.

client_bound_data moves display-only information off the server. The data is sent through the network protocol and resolved on the client at render time. The server-side item stays lightweight, and different players can see different things.

How it works

Split your data: keep what the server needs in data, put what the player sees in client_bound_data. Any key from data works here — item_name, lore, custom_model_data, item_model, components, etc.

Here is a sword that shows different names and descriptions depending on whether the player has unlocked it:

items:
  demo:mythic_sword:
    material: diamond_sword
    data:
      item_name: "<!i><#FF8C00>Mythic Sword"
    client_bound_data:
      conditional#unlocked:
        conditions:
          - type: permission
            permission: item.mythic_sword.unlock
        data:
          item_name: "<!i><#FF8C00>Mythic Sword"
          lore:
            - "<green>Unlocked"
            - "<gray>Level <arg:player.level>"
      conditional#locked:
        conditions:
          - type: "!permission"
            permission: item.mythic_sword.unlock
        data:
          item_name: "<!i><gray>???? Sword"
          lore:
            - "<red>Locked"
            - "<gray>Requires Level 30"

A player with the permission sees the golden name and their current level. Everyone else sees "???? Sword" and a lock message. Both are looking at the same ItemStack.

Why use it

Different players, different views. Without client_bound_data, every player holding the same item sees identical text. With it, item unlock states, player-specific stats, or real-time counters are all possible — resolved per-client at render time.

Performance. The server-side ItemStack no longer carries complex display components. This matters in three ways:

• Faster getItemMeta. Other plugins reading item metadata don't need to deserialize display components that only exist on the client.
• Lower memory. Survival servers with thousands of stored items benefit from lightweight server-side stacks — the rich data only lives in the rendering pipeline.
• Faster chunk loading. Display components are serialized on the netty thread only when shown to a player. During chunk loads, items carry minimal data.

client_bound_material

Changes the visual material the client sees while keeping the server-side material unchanged.

items:
  demo:palm_planks:
    material: nether_brick
    client_bound_material: mushroom_stem
    client_bound_data:
      block_state: default:palm_planks

Useful when the server-side material must differ from the visual one — for example, using nether_brick as a base while the client renders a block model tied to mushroom_stem.

Overwritable variants

These only take effect when the item doesn't already have the corresponding data — allowing other plugins to set their own values without being overwritten.

# Lore — only shown if no lore is present
overwritable_lore:
  - "Default description"

# item_name — only shown if no custom name is present
overwritable_item_name: "<!i><#FF8C00>Default name"

# item_model (1.21.2+) — only set if no model is present
overwritable_item_model: default:sword

# custom_model_data — only set if no CMD is present
overwritable_custom_model_data: 10001

danger

This feature changes how item data flows between server and client. It is intended for servers that curate their plugin ecosystem and can troubleshoot independently.

• Plugin compatibility. Plugins that identify items by reading server-side names or model values may not recognize items using client_bound_data. If needed, add a minimal set of real components in data alongside the client-only ones.
• Packet conflicts. Other plugins that modify items via packets may strip or corrupt client-side components. This can cause items to visually stick on the cursor (appearing duplicated) or components to become permanently attached.
• Paper obfuscation. If you use Paper's enable-item-obfuscation, add minecraft:custom_data to dont-obfuscate in paper-global.yml.