Overview

uxmEssentials is built to be a good neighbour. If you write your own plugin, you can read its economy, react to its events, and extend its menus — all at runtime, through interfaces every Paper plugin already knows how to reach.

There is one thing to get straight before anything else, because it shapes the whole integration story.

uxmEssentials is not published to a Maven repository

There is no JitPack coordinate, no maven-publish, and no public Maven artifact for the plugin. Do not add a compileOnly 'com.github…:uxmEssentials' dependency block — there is nothing to resolve.

Integrate at runtime instead: soft-depend on the plugin so it loads first, then obtain what you need from Bukkit's ServicesManager and listen to its Bukkit events. Everything below follows from that.

---

Soft-depend on the plugin

Declare uxmEssentials as a soft dependency in your own paper-plugin.yml, so the server loads it before you and its services are registered by the time your onEnable runs:

name: MyAddon
main: com.example.MyAddon
version: 1.0.0
api-version: '1.21'
dependencies:
  server:
    uxmEssentials:
      load: BEFORE
      required: false
      join-classpath: true

required: false keeps your plugin working if uxmEssentials is absent — always guard your lookups so you degrade gracefully.

---

What you can integrate with

Three surfaces are available to external plugins, all reached at runtime:

Surface	How you reach it	Use it for
Menu API (MenuApi)	ServicesManager lookup	Register custom menu actions, requirements, placeholders, list sources, and icon providers; build menu items — see Menu API
Economy provider	Vault / Treasury via ServicesManager	Read and move balances. uxmEssentials registers as a standard economy provider, so you consume it through the Vault or Treasury APIs you would use for any economy plugin — see Vault & Treasury
Bukkit events	@EventHandler	React to kit claims and menu open/click — see Events

Read the economy through Vault or Treasury

uxmEssentials does not ask you to import its own economy port. Instead it registers a provider into the ecosystem's standard slots — Treasury first, then Vault — so if you already talk to net.milkbowl.vault.economy.Economy (or a Treasury EconomyProvider), you are already talking to uxmEssentials when it is the active provider. See Vault & Treasury for the exact lookup.

---

Getting a service from the ServicesManager

The ServicesManager is Bukkit's built-in service registry. uxmEssentials registers MenuApi there on enable (at ServicePriority.Normal), so you fetch it like any other service. Do the lookup inside your onEnable, after uxmEssentials has loaded:

import org.bukkit.plugin.RegisteredServiceProvider;
import org.bukkit.plugin.ServicesManager;
// The MenuApi type lives in the plugin's api package, resolved at runtime via join-classpath.
import com.uxplima.uxmessentials.shared.gui.menu.api.MenuApi;

public final class MyAddon extends JavaPlugin {

    private MenuApi menuApi;

    @Override
    public void onEnable() {
        ServicesManager services = getServer().getServicesManager();
        RegisteredServiceProvider<MenuApi> registration =
                services.getRegistration(MenuApi.class);

        if (registration == null) {
            getLogger().info("uxmEssentials MenuApi not present — skipping menu integration.");
            return;
        }

        this.menuApi = registration.getProvider();
        // ... register your custom actions, requirements, placeholders here.
    }
}

The pattern is always the same: getRegistration(SomeService.class), null-check, then getProvider(). A null registration means the service (or the whole plugin) is not installed — handle it and move on, never assume it is there.

Register once, on enable

Anything you register through MenuApi (actions, requirements, placeholders, …) must be registered once, during your onEnable, before any menu that uses it is loaded. See the register-once contract for why order matters.

---

Next Steps

• Events — the Bukkit events you can listen to
• Menu API — extend the menu engine with your own actions and placeholders
• Vault & Treasury — read and move economy balances