🤝 Compatibility (Developers)

Overview

Oraxen provides a robust compatibility system that allows developers to easily integrate with other plugins. The system automatically manages the lifecycle of compatibility providers and supports both built-in integrations and custom implementations.

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.

Usage

info

All compatibility providers must extend the CompatibilityProvider class with these key methods.

public class CompatibilityProvider<T extends Plugin> implements Listener {
    protected String pluginName;
    protected T plugin;
    protected boolean isEnabled;

    public void enable(String pluginName) {
        // Called when target plugin is detected
        // Registers this provider as a Bukkit listener
    }

    public void disable() {
        // Called when compatibility is disabled
        // Unregisters this provider's listeners
    }
}

Create the Compatibility Class

Create a class that extends CompatibilityProvider<T> where T is the main class of the target plugin.

import io.th0rgal.oraxen.compatibilities.CompatibilityProvider;
import io.th0rgal.oraxen.OraxenPlugin;
import org.bukkit.event.EventHandler;

public class MyPluginCompatibility extends CompatibilityProvider<MyTargetPlugin> {
    
    @Override
    public void enable(String pluginName) {
        super.enable(pluginName);
        // Initialize your integration here
        // Event listeners are automatically registered
        OraxenPlugin.get().getLogger().info("MyPlugin compatibility enabled!");
    }
    
    @Override
    public void disable() {
        super.disable();
        // Clean up your integration here
        // Event listeners are automatically unregistered
        OraxenPlugin.get().getLogger().info("MyPlugin compatibility disabled!");
    }
    
    @EventHandler
    public void onMyPluginEvent(MyPluginEvent event) {
        // Handle integration events here
        // This will only be called when compatibility is enabled
    }
}

Register the Compatibility

Add your compatibility to Oraxen's system. This can be done from your plugin or through a pull request to Oraxen.

import io.th0rgal.oraxen.compatibilities.CompatibilitiesManager;
import org.bukkit.plugin.java.JavaPlugin;

public class MyOraxenIntegrationPlugin extends JavaPlugin {
    
    @Override
    public void onEnable() {
        // Register compatibility with auto-enable when target plugin loads
        CompatibilitiesManager.addCompatibility("MyTargetPlugin", MyPluginCompatibility.class, true);
        
        // Or register without auto-enable (manual control)
        CompatibilitiesManager.addCompatibility("MyTargetPlugin", MyPluginCompatibility.class, false);
    }
}

Automatic Lifecycle Management

The compatibility system automatically handles:

• Detection - Monitors when target plugins are enabled/disabled
• Instantiation - Creates compatibility instances when needed
• Event Registration - Registers/unregisters event listeners
• Cleanup - Properly disables compatibilities when plugins unload

Example

import io.lumine.mythic.bukkit.MythicBukkit;
import io.lumine.mythic.bukkit.events.MythicDropLoadEvent;
import io.lumine.mythic.bukkit.utils.numbers.RandomDouble;
import io.lumine.mythic.core.drops.Drop;
import io.th0rgal.oraxen.compatibilities.CompatibilityProvider;
import io.th0rgal.oraxen.api.OraxenItems;
import io.th0rgal.oraxen.utils.MythicUtil;
import org.bukkit.event.EventHandler;
import org.bukkit.inventory.ItemStack;

public class MythicMobsCompatibility extends CompatibilityProvider<MythicBukkit> {
    
    @EventHandler
    public void onMythicDropLoadEvent(MythicDropLoadEvent event) {
        if (!event.getDropName().equalsIgnoreCase("oraxen")) return;

        String line = event.getContainer().getLine();
        String itemId = line.split(" ").length >= 2 ? line.split(" ")[1] : "";
        if (!OraxenItems.exists(itemId)) return;

        ItemStack oraxenItem = OraxenItems.getItemById(itemId).build();

        Drop drop = MythicUtil.getOraxenDrop(line, event.getConfig(), oraxenItem, new RandomDouble("1-1"));
        event.register(drop);
    }
}

// Registration in your plugin's onEnable()
import io.th0rgal.oraxen.compatibilities.CompatibilitiesManager;

@Override
public void onEnable() {
    CompatibilitiesManager.addCompatibility("MythicMobs", MythicMobsCompatibility.class, true);
}

warning

Compatibility providers are automatically instantiated when the target plugin is detected. Make sure your compatibility class has a public no-args constructor and doesn't perform heavy operations in the constructor.