Developer API

​

Setting up

dependencies {
    compileOnly("io.papermc.paper:paper-api:26.2.build.+")
    compileOnly(files("libs/LodeItems.jar"))
}

<dependency>
  <groupId>org.lodemc</groupId>
  <artifactId>lodeitems</artifactId>
  <version>local</version>
  <scope>system</scope>
  <systemPath>${project.basedir}/libs/LodeItems.jar</systemPath>
</dependency>

# A Bukkit plugin
depend: [LodeItems]       # or softdepend, if Lode Items is optional

# A Paper plugin
dependencies:
  server:
    LodeItems:
      load: BEFORE
      required: true
      join-classpath: true

​

When to call what

​

Things to know

• Call the API from the main thread. The one exception is 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. 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 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.
• 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

fire_staff:
  material: stick
  texture: fire_staff.png
  mana-cost: 15          # read by the mana plugin below

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);
    }
}