> ## Documentation Index
> Fetch the complete documentation index at: https://items.lodemc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Items

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

## A first item

```yaml items/gems/ruby.yml theme={null}
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](https://items.lodemc.net/basics.md#text-formatting).

**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](https://items.lodemc.net/commands.md#item-browser). Defaults to the first folder under `items/` it lives in, or `misc` for files directly in `items/`.

## Stats

```yaml theme={null}
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:

```yaml theme={null}
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

```yaml theme={null}
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.

```yaml theme={null}
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.

> [!TIP]
>
> `/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.

```yaml theme={null}
ruby:
  material: coal
  vanilla-behaviour: true   # still burns as fuel and works in coal recipes
```

[Recipes](https://items.lodemc.net/recipes.md) you write yourself always work.

## More

> **[Item mechanics](https://items.lodemc.net/item-mechanics.md)**
>
> Backpacks, hammers, auto-smelting, harvesting, keeping items on death and more.

> **[Armour](https://items.lodemc.net/armor.md)**
>
> Custom worn textures, elytra, horse armour and set bonuses.

> **[Events and actions](https://items.lodemc.net/events.md)**
>
> Run commands, effects and sounds when an item is used.

> **[Recipes](https://items.lodemc.net/recipes.md)**
>
> Crafting, smelting, smithing and brewing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.