> ## 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 API

> Recognise Lode Items items, read what they are, and create and update stacks from your plugin.

Item methods are static methods on `org.lodemc.api.LodeItemsApi`. Every entry that gives an item has one: plain items, and the items that place blocks, props, crops and fluids, which share their entry's id.

A Lode Items stack is a normal vanilla item with extra components, so Bukkit sees its base `Material` (often `PAPER`). Use these methods to tell which custom item it is.

```java theme={null}
import org.lodemc.api.CustomItem;
import org.lodemc.api.LodeItemsApi;

// Which custom item is in the player's hand?
CustomItem item = LodeItemsApi.item(player.getInventory().getItemInMainHand());
if (item != null && item.getId().asString().equals("lodeitems:ruby")) {
    player.sendMessage("That's a ruby!");
}

// Give a player 3 rubies
ItemStack rubies = LodeItemsApi.createItem("ruby", 3);
if (rubies != null) player.getInventory().addItem(rubies);
```

## LodeItemsApi

**itemId(ItemStack stack)** `Key`

The Lode Items id of `stack`, or `null` for a vanilla stack, an empty stack or `null`. This is the fastest check: it only reads the stack.

**isCustomItem(ItemStack stack)** `boolean`

Whether `stack` is any Lode Items item.

**item(ItemStack stack)** `CustomItem`

The item `stack` is, or `null` for a vanilla stack, or for a stack whose item was removed from the configs.

**item(Key id)** `CustomItem`

Item `id`, or `null` if there's no such item. Also takes the id as a `String`.

**items()** `Collection\<CustomItem\>`

Every Lode Items item.

**itemIds()** `Set\<Key\>`

The ids of every Lode Items item.

**isItem(Key id)** `boolean`

Whether `id` is a Lode Items item right now.

**createItem(Key id, int amount)** `ItemStack`

A new stack of item `id`, exactly as `/lodeitems give` makes it, or `null` if there's no such item. `amount` is optional and defaults to 1. Also takes the id as a `String`.

**update(ItemStack stack)** `ItemStack`

`stack` rebuilt from its item's current config, keeping what the player owns: damage, custom name, enchantments, dye, trims and other plugins' data. This is what the [item updater](https://items.lodemc.net/item-mechanics.md) does when a player joins. Returns `stack` itself when it's already current, vanilla, or its item has `update: false`. Use it on stacks you store yourself, such as in a database or a custom inventory.

## CustomItem

An item as it's configured. It's read-only, and a reload makes new objects, so look items up again after [`LodeItemsLoadEvent`](https://items.lodemc.net/api/events#lodeitemsloadevent).

| Method | Returns | What it is |
| - | - | - |
| `getId()` | `Key` | Its id |
| `getBaseItem()` | `Key` | The vanilla item it's built on (`material:`), such as `minecraft:paper` |
| `getBaseMaterial()` | `Material` | The same as a Bukkit `Material`, or `null` for a modded base item |
| `getName()` | `Component` | Its `name:`, or `null` when it uses the base item's name |
| `getLore()` | `List<Component>` | Its `lore:` |
| `getCategory()` | `String` | Its category in the [item browser](https://items.lodemc.net/commands.md): `category:`, or the top folder its file is in |
| `getModelKey()` | `Key` | The `item_model` its stacks carry, or `null` when it looks like its base item. Set this key on any stack to make it look like this item. |
| `getBlockId()` | `Key` | The [block](https://items.lodemc.net/api/blocks.md) it places, or `null` |
| `getPropId()` | `Key` | The [prop](https://items.lodemc.net/api/props.md) it places, or `null` |
| `getHasEvents()` | `boolean` | Whether it has [`events:`](https://items.lodemc.net/events) |
| `isArmor()` | `boolean` | Whether it's [armour](https://items.lodemc.net/armor.md) with a look of its own |
| `getEntry()` | `ContentEntry` | Its [entry as written](https://items.lodemc.net/api/config.md), with every key, the file and the line |
| `create(int amount)` | `ItemStack` | A new stack. `amount` defaults to 1. |
| `matches(ItemStack stack)` | `boolean` | Whether `stack` is this item |

## Example: an item that reads its own settings

Owners can give any item settings for your plugin. Register the key in `onLoad`, then read it from the item's entry:

```yaml items/tools/lucky_pickaxe.yml theme={null}
lucky_pickaxe:
  material: diamond_pickaxe
  texture: lucky_pickaxe.png
  luck:
    chance: 0.1
    reward: ruby
```

```java theme={null}
@Override
public void onLoad() {
    LodeItemsApi.registerConfigKey(this, "luck");
}

@EventHandler
public void onBreak(BlockBreakEvent event) {
    CustomItem tool = LodeItemsApi.item(event.getPlayer().getInventory().getItemInMainHand());
    if (tool == null || tool.getEntry() == null || !tool.getEntry().has("luck")) return;
    double chance = tool.getEntry().getDouble("luck.chance", 0);
    if (Math.random() < chance) {
        ItemStack reward = LodeItemsApi.createItem(tool.getEntry().getString("luck.reward", "ruby"));
        if (reward != null) event.getBlock().getWorld().dropItemNaturally(event.getBlock().getLocation(), reward);
    }
}
```

See [Config and assets](https://items.lodemc.net/api/config.md) for everything you can read from an entry.


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