Items

Make a custom item, then give it stats, food, cooldowns and any vanilla data component.

A first item

items/gems/ruby.yml

ruby:
  material: paper             # the vanilla item it is built on (default: paper)
  name: "<red>Ruby"
  lore:
    - "<gray>A polished gemstone."
  texture: ruby.png           # next to this file

Run /lodeitems reload, then /lodeitems give ruby.

A custom item is a normal vanilla item with your look and data on top. It is not added to the game’s item list, so you can add and remove items with a reload, without a restart, and it works alongside mods. LodeItems recognises its own items by a hidden tag, so renaming one or changing its lore never breaks it.

Basic options

material · item id · default: "paper"

The vanilla (or modded) item it is built on. It decides what the item does by default: a diamond_sword swings and has durability, bow shoots, iron_chestplate can be worn. Modded items use their full id, such as create:wrench.

name · text

The item’s name, in MiniMessage.

lore · list of text

Lines under the name.

texture · file

A .png for a flat item. Tools and weapons (swords, axes, pickaxes, shovels, hoes, spears, rods, sticks, bones, the mace and the trident) are held at an angle, like vanilla tools.

model · file

A .json model, such as one exported from Blockbench. Use either texture or model, not both.

category · text

The tab it goes in in the item browser. Defaults to the first folder under items/ it lives in, or misc for files directly in items/.

Stats

ruby_sword:
  material: diamond_sword
  name: "<red>Ruby Sword"
  texture: ruby_sword.png
  damage: 9               # what the tooltip shows
  attack-speed: 1.8
  durability: 2000
  enchantments:
    sharpness: 2
  rarity: rare

Option	Value	Does
damage	number	Attack damage, as the tooltip shows it.
attack-speed	number	Attacks per second, as the tooltip shows it.
durability	whole number	Maximum durability. Also makes it stack to 1, unless you set stack-size.
stack-size	1 to 99	How many fit in one slot.
unbreakable	true	Never loses durability.
enchantments	map	Enchantments and levels: sharpness: 2.
glint	true / false	Forces the enchantment shine on or off.
rarity	common, uncommon, rare, epic	The name’s default colour.
fire-resistant	true	Survives fire and lava, like netherite.
glider	true	Lets the wearer glide like with an elytra.
color	#rrggbb	Dye colour, for leather armour and other dyeable items.
tooltip-style	id	A custom tooltip background, such as myserver:ruby.
hide-tooltip	true	Shows no tooltip at all.
hide	list	Hides parts of the tooltip: [enchantments, attribute_modifiers].
cooldown	seconds	Cooldown after use, like ender pearls.
cooldown-group	id	Items in the same group share one cooldown.

Attributes

For anything beyond damage and speed, list attribute modifiers:

swift_boots:
  material: leather_boots
  attributes:
    - attribute: movement_speed
      amount: 0.1
      operation: multiply_base   # add (default), multiply_base or multiply
      slot: feet                 # any (default), mainhand, offhand, hand, head, chest, legs, feet, armor, body
    - attribute: max_health
      amount: 4
      slot: feet

Food

ruby_apple:
  material: apple
  name: "<red>Ruby Apple"
  texture: ruby_apple.png
  food:
    nutrition: 6
    saturation: 9.6
    can-always-eat: true
    eat-time: 2.4     # seconds; vanilla is 1.6

Any item can be made edible this way, even one whose material can’t be eaten.

Any vanilla data component

Everything Minecraft can store on an item can go under components:, written exactly as /give writes it. Minecraft itself checks it, so every component works, including ones added in future updates. A wrong value is reported with its line.

ruby_helmet:
  material: leather_helmet
  components:
    dyed_color: 16711680
    trim:
      pattern: silence
      material: diamond
    max_stack_size: 1
  remove-components:
    - attribute_modifiers   # drop something the base item has

The options are applied in this order, and later ones win:

1. The material’s own data.
2. The shortcut options above (durability, food…).
3. damage, attack-speed and attributes.
4. components:.
5. remove-components:.
6. name, lore and the model. These always win.

/lodeitems inspect <item> prints every component the item ends up with. Use it to check what your config produced.

Vanilla behaviour

By default a custom item stops acting as its base item in ways that would be surprising. A ruby built on paper isn’t used as paper in vanilla recipes, and one built on stone doesn’t place stone. It also isn’t smelted, burned as fuel or repaired in an anvil as its base item.

ruby:
  material: coal
  vanilla-behaviour: true   # still burns as fuel and works in coal recipes

Recipes you write yourself always work.

More

Item mechanics

Backpacks, hammers, auto-smelting, harvesting, keeping items on death and more.

Armour

Custom worn textures, elytra, horse armour and set bonuses.

Events and actions

Run commands, effects and sounds when an item is used.

Recipes

Crafting, smelting, smithing and brewing.