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

# Developer API

> Use Lode Items from your own plugin: recognise custom items, blocks and props, read owners' configs and assets, add to the resource pack, and listen to events.

Other plugins can use Lode Items through its Java API in the `org.lodemc.api` package. Build your own mechanics on top of Lode Items content, let server owners configure them in the same YAML files, and ship your models and textures in the same resource pack.

| Part | Class | What you can do |
| - | - | - |
| [Items](https://items.lodemc.net/api/items.md) | `LodeItemsApi` | Recognise custom items, create and update stacks |
| [Config and assets](https://items.lodemc.net/api/config.md) | `LodeItemsApi`, `ContentEntry` | Read any entry as written, add your own config keys and `type:`s, find files next to the YAML |
| [Blocks](https://items.lodemc.net/api/blocks.md) | `LodeBlocks` | Recognise custom blocks, read their state, place them |
| [Props](https://items.lodemc.net/api/props.md) | `LodeProps` | Find placed props, change their state, place, rotate and break them |
| [Crops](https://items.lodemc.net/api/crops.md) | `LodeCrops` | Grow, plant and harvest crops, and change the rules they grow by |
| [Resource pack](https://items.lodemc.net/api/pack.md) | `LodePack` | Add your own files to the pack Lode Items builds and sends |
| [Events](https://items.lodemc.net/api/events.md) | `org.lodemc.api.event` | React to blocks, props, crops, reloads and pack builds |

The API is written in Kotlin and is called from Java like any Java library. Every example on these pages is Java.

## Setting up

**1. Compile against the Lode Items jar**

Put the Lode Items jar in your project, for example in `libs/`, and add it as a compile-only dependency. Don't shade it into your plugin.

```kotlin build.gradle.kts theme={null}
dependencies {
    compileOnly("io.papermc.paper:paper-api:26.2.build.+")
    compileOnly(files("libs/LodeItems.jar"))
}
```

```xml pom.xml theme={null}
<dependency>
  <groupId>org.lodemc</groupId>
  <artifactId>lodeitems</artifactId>
  <version>local</version>
  <scope>system</scope>
  <systemPath>${project.basedir}/libs/LodeItems.jar</systemPath>
</dependency>
```

**2. Depend on Lode Items**

Lode Items must load before your plugin, and your plugin must be able to see its classes.

```yaml plugin.yml theme={null}
# A Bukkit plugin
depend: [LodeItems]       # or softdepend, if Lode Items is optional
```

```yaml paper-plugin.yml theme={null}
# A Paper plugin
dependencies:
  server:
    LodeItems:
      load: BEFORE
      required: true
      join-classpath: true
```

With `softdepend` or `required: false`, check that Lode Items is enabled before you touch any `org.lodemc.api` class.

## When to call what

Lode Items loads its content in its own `onEnable`, which runs after every plugin's `onLoad` and before your `onEnable`. So:

| In your | Do |
| - | - |
| `onLoad` | Register [config keys and types](https://items.lodemc.net/api/config.md#your-own-config) and [pack contributors](https://items.lodemc.net/api/pack.md), so the first load already knows them |
| `onEnable` | Look up items, blocks, props and crops, add [crop rules](https://items.lodemc.net/api/crops.md#crop-rules), register listeners |
| A [`LodeItemsLoadEvent`](https://items.lodemc.net/api/events#lodeitemsloadevent) listener | Look things up again after `/lodeitems reload` |

Everything you register is removed when your plugin disables.

## Things to know

* **Call the API from the main thread.** The one exception is [crop rules](https://items.lodemc.net/api/crops.md#crop-rules), which Lode Items calls itself.
* **Ids are Adventure keys**, such as `Key.key("lodeitems", "ruby")`. Methods that also take a `String` read `ruby` as `lodeitems:ruby`. A namespaced id like `myserver:ruby` is kept as written. `LodeItemsApi.key("ruby")` does the same conversion for you.
* **Content changes on `/lodeitems reload`.** Items, blocks, props and crops can be added, changed or removed. Objects you got from the API before a reload are out of date afterwards, so look them up again on [`LodeItemsLoadEvent`](https://items.lodemc.net/api/events#lodeitemsloadevent). Placed blocks and props in the world stay where they are.
* **Bukkit can't tell custom blocks apart.** It reports a generic `Material` for all of them: `STONE` for solid blocks, `GLASS` for see-through blocks, and `TRIPWIRE` for walk-through blocks and crops. Use [`LodeBlocks.at`](https://items.lodemc.net/api/blocks#finding-blocks) to find out what a block really is.
* **Normal Bukkit events still fire** for custom content, such as `BlockPlaceEvent`, `BlockBreakEvent` and `PlayerInteractEvent`. See [Vanilla events](https://items.lodemc.net/api/events.md#vanilla-events).
* **Free and licensed editions** don't change the API. The free edition loads fewer items, blocks and plants, so the API only sees what loaded.

## Example: a mana cost on any item

This short plugin lets owners write `mana-cost:` on any Lode Items item, and reads it when a player right-clicks:

```yaml items/weapons/fire_staff.yml theme={null}
fire_staff:
  material: stick
  texture: fire_staff.png
  mana-cost: 15          # read by the mana plugin below
```

```java theme={null}
public final class ManaPlugin extends JavaPlugin implements Listener {
    @Override
    public void onLoad() {
        LodeItemsApi.registerConfigKey(this, "mana-cost");   // no "Unknown option" warning
    }

    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void onUse(PlayerInteractEvent event) {
        CustomItem item = LodeItemsApi.item(event.getItem());
        if (item == null || item.getEntry() == null) return;
        int cost = item.getEntry().getInt("mana-cost", 0);
        if (cost > 0) spendMana(event.getPlayer(), cost);
    }
}
```


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