🔗 API (Developers)

Overview

Oraxen exposes a small public API surface for other plugins. Most integrations revolve around these classes.

• io.th0rgal.oraxen.api.OraxenItems
• io.th0rgal.oraxen.api.OraxenBlocks
• io.th0rgal.oraxen.api.OraxenFurniture
• io.th0rgal.oraxen.api.OraxenPack

info

Oraxen is open source, allowing you to create a pull request with the needed changes for your integration. If you are unsure about how to contribute, refer to our Contributing Guide.

Setup

Add the Maven Repository + Dependency

Oraxen is a server plugin, so in most cases you want compileOnly / provided.

repositories {
  maven("https://repo.oraxen.com/releases")
}

dependencies {
  compileOnly("io.th0rgal:oraxen:VERSION")
}

repositories {
  maven { url "https://repo.oraxen.com/releases" }
}

dependencies {
  compileOnly "io.th0rgal:oraxen:VERSION"
}

<repository>
  <id>oraxen</id>
  <url>https://repo.oraxen.com/releases</url>
</repository>

<dependency>
  <groupId>io.th0rgal</groupId>
  <artifactId>oraxen</artifactId>
  <version>VERSION</version>
  <scope>provided</scope>
</dependency>

Snapshot builds are also available at https://repo.oraxen.com/snapshots.

Add Oraxen to plugin.yml

Use depend if your plugin cannot run without Oraxen, otherwise use softdepend.

name: MyPlugin
main: com.example.myplugin.MyPlugin
version: 1.0.0

softdepend: [Oraxen]

Use Events Instead of Guessing Load Order

Items and mechanics are reloaded on /oraxen reload all. Prefer listening to Oraxen events (see below) rather than caching results forever.

Items (OraxenItems)

Oraxen assigns an item id into the PersistentDataContainer using OraxenItems.ITEM_ID.

import io.th0rgal.oraxen.api.OraxenItems;
import io.th0rgal.oraxen.items.ItemBuilder;
import org.bukkit.inventory.ItemStack;

public class MyIntegration {
    public ItemStack build(String itemId) {
        ItemBuilder builder = OraxenItems.getItemById(itemId);
        return builder != null ? builder.build() : null;
    }

    public boolean isOraxenItem(ItemStack stack) {
        return OraxenItems.exists(stack);
    }

    public String getOraxenId(ItemStack stack) {
        return OraxenItems.getIdByItem(stack); // null if not an Oraxen item
    }
}

info

Useful helpers

• OraxenItems.exists(String) / OraxenItems.exists(ItemStack)
• OraxenItems.getItemById(String) and OraxenItems.getOptionalItemById(String)
• OraxenItems.getBuilderByItem(ItemStack)
• OraxenItems.getNames() (all loaded ids) and OraxenItems.getItemNames() (filtered for commands)

Custom Blocks (OraxenBlocks)

Oraxen custom blocks can be backed by different mechanics (note block / tripwire / chorus plant / shaped block). The API provides common queries and safe placement/removal methods.

import io.th0rgal.oraxen.api.OraxenBlocks;
import org.bukkit.Location;
import org.bukkit.block.Block;

public class MyBlocks {
    public boolean isOraxen(Block block) {
        return OraxenBlocks.isOraxenBlock(block);
    }

    public void place(String itemId, Location at) {
        OraxenBlocks.place(itemId, at);
    }

    public boolean remove(Location at) {
        return OraxenBlocks.remove(at, null); // player optional
    }
}

info

Also available:

• ID lists - getBlockIDs(), getNoteBlockIDs(), getStringBlockIDs(), getChorusBlockIDs()
• Type checks - isOraxenNoteBlock(...), isOraxenStringBlock(...), isOraxenChorusBlock(...)
• Mechanic accessors - getNoteBlockMechanic(...), getStringMechanic(...), getChorusMechanic(...), getShapedMechanic(...)
• Block data creation - getOraxenBlockData(itemId)

Furniture (OraxenFurniture)

Furniture is entity-backed (and may optionally use barrier hitboxes). The API lets you detect furniture, place it with a rotation or yaw, and remove it while respecting drops.

import io.th0rgal.oraxen.api.OraxenFurniture;
import org.bukkit.Location;
import org.bukkit.block.BlockFace;
import org.bukkit.entity.Entity;
import org.bukkit.Rotation;

public class MyFurniture {
    public Entity place(String itemId, Location at) {
        return OraxenFurniture.place(itemId, at, Rotation.NONE, BlockFace.UP);
    }

    public boolean remove(Location at) {
        return OraxenFurniture.remove(at, null); // player optional
    }
}

warning

The old boolean-returning OraxenFurniture.place(Location, String, Rotation, BlockFace) is deprecated. Use OraxenFurniture.place(String, Location, Rotation, BlockFace) instead.

Resource Pack (OraxenPack)

Use OraxenPack when you need to trigger pack actions or inject additional files into the generated output.

import io.th0rgal.oraxen.api.OraxenPack;
import java.io.File;

public class MyPack {
    public File getPackFile() {
        return OraxenPack.getPack();
    }

    public void reload() {
        OraxenPack.reloadPack();
    }

    public void upload() {
        OraxenPack.uploadPack();
    }
}

Add extra files to the generated pack

import io.th0rgal.oraxen.api.OraxenPack;
import java.io.File;

OraxenPack.addFilesToPack(new File[] {
    new File("plugins/MyPlugin/pack_overrides/pack.mcmeta")
});

Events

All events live under io.th0rgal.oraxen.api.events.* and can be listened to like any other Bukkit event.

import io.th0rgal.oraxen.api.events.OraxenItemsLoadedEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MyListener implements Listener {
    @EventHandler
    public void onItemsLoaded(OraxenItemsLoadedEvent event) {
        // Items were (re)parsed, rebuild your caches here
    }
}

info

Common integration events

• OraxenItemsLoadedEvent - items were parsed/reloaded
• OraxenNativeMechanicsRegisteredEvent - native mechanics registered; hook custom mechanics here (see Mechanics)
• OraxenPackGeneratedEvent - pack output list is available
• OraxenPackPreUploadEvent - cancellable, fired async (avoid unsafe Bukkit calls)
• OraxenPackUploadEvent - pack got uploaded; provides the HostingProvider (URL, SHA1, UUID)
• Block / furniture events: events.noteblock.*, events.stringblock.*, events.chorusblock.*, events.shapedblock.*, events.furniture.*
• Shaped blocks currently only fire a break event (OraxenShapedBlockBreakEvent). There are no damage, interact or place variants yet.