Working with other plugins

Real servers run dozens of plugins, and the best ones cooperate. On this page you will learn how to depend on another plugin, use Vault, LuckPerms and PlaceholderAPI without crashing when they are missing, and offer your own plugin's features to other developers.

Why plugins talk to each other

Imagine your plugin sells items in a shop. Who keeps track of each player's money? If your shop invents its own money system, it will not match the one the rest of the server uses. A much better shop asks the economy plugin that is already installed. Three popular plugins show up in almost every tutorial:

Using one of these means two jobs: making sure the other plugin loads before yours, and writing code that calls its API, the set of classes and methods the other plugin offers to other developers. And one more job that beginners skip and regret: making your plugin still work when the other plugin is not installed.

Load order: depend and softdepend

Paper enables plugins one after another. If your plugin tries to talk to Vault before Vault has started, nothing works. You fix the order in plugin.yml (the plugin.yml chapter shows every field):

11depend: [Vault]22softdepend: [LuckPerms, PlaceholderAPI]33loadbefore: [Essentials]

Use the name exactly as the other plugin spells its own name, capital letters included. Which one should you pick?

[14:02:10 ERROR]: [ModernPluginLoadingStrategy] Could not load 'plugins/Shop.jar' in folder 'plugins'org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'Shop'.

That is what a missing depend looks like. It is a good failure: it happens at startup, with a message that names the problem.

Checking for another plugin

With a softdepend your plugin loads whether the other plugin is there or not, so you must ask. Paper's PluginManager has two questions for this:

• getPlugin("Vault") returns the plugin object, or null when it is not installed.
• isPluginEnabled("Vault") returns true only when it is installed and successfully started.

The example plugin other-plugins-presence prints what is installed when it starts. First a small helper class:

21String describe(String name) {122    Plugin plugin = server.getPluginManager().getPlugin(name);23    if (plugin == null) {24        return name + ": not installed";25    }226    if (!plugin.isEnabled()) {27        return name + ": installed but not enabled";28    }329    return name + ": enabled, version " + plugin.getPluginMeta().getVersion();30}

9@Override10public void onEnable() {11    OptionalPlugins optionalPlugins = new OptionalPlugins(getServer());12 113    for (String name : OptionalPlugins.NAMES) {14        getLogger().info(optionalPlugins.describe(name));15    }16 217    getServer().getPluginManager().registerEvents(new HookListener(getLogger()), this);18 319    registerCommand("hooks", "List the optional plugins", new BasicCommand() {20        @Override21        public void execute(CommandSourceStack source, String[] args) {22            for (String name : OptionalPlugins.NAMES) {23                source.getSender().sendRichMessage("<gray>" + optionalPlugins.describe(name));24            }25        }26 27        @Override28        public String permission() {29            return "presencecheck.hooks";30        }31    });32}

[14:02:11 INFO]: [PresenceCheck] Enabling PresenceCheck v1.0.0[14:02:11 INFO]: [PresenceCheck] Vault: enabled, version 1.7.3[14:02:11 INFO]: [PresenceCheck] LuckPerms: not installed[14:02:11 INFO]: [PresenceCheck] PlaceholderAPI: installed but not enabled

Plugins that start later

Sometimes the plugin you want is not ready yet when your onEnable runs, even with a softdepend. The economy that Vault talks to, for example, is provided by a separate plugin that may start after yours. There are two solutions, and good plugins use both:

• Look it up at the moment you need it instead of once at startup. A shop that asks for the economy each time a player buys something is always up to date.
• Listen for PluginEnableEvent (and PluginDisableEvent) to know the moment a plugin starts or stops. The example's HookListener does this:

17@EventHandler18public void onPluginEnable(PluginEnableEvent event) {119    String name = event.getPlugin().getName();220    if (OptionalPlugins.NAMES.contains(name)) {21        logger.info(name + " just started, so its features can be used now.");22    }23}

The crash you must avoid: NoClassDefFoundError

Here is the most common bug in plugins that use other plugins. The author tests with Vault installed, everything works, and the plugin gets released. A user without Vault installs it and sees this:

[14:02:11 ERROR]: Error occurred while enabling Shop v1.0.0 (Is it up to date?)java.lang.NoClassDefFoundError: net/milkbowl/vault/economy/Economy	at com.example.shop.ShopPlugin.onEnable(ShopPlugin.java:21)Caused by: java.lang.ClassNotFoundException: net.milkbowl.vault.economy.Economy

Why does this happen? When your plugin compiles, it only needs Vault's classes to check your code. At runtime the real Vault jar is the only place those classes exist. Java loads classes lazily, the first time your code needs them. If Vault is not installed, the moment Java touches a Vault class, it cannot find it and throws NoClassDefFoundError, which usually disables your whole plugin.

The fix is a rule and a pattern:

1private VaultHook vaultHook;2 3if (getServer().getPluginManager().isPluginEnabled("Vault")) {4    vaultHook = VaultHook.create(getServer());5}

If Vault is missing, the line that creates VaultHook never runs, so Java never loads VaultHook, so it never looks for Vault's classes. The field is typed with your own class, which always exists. Everywhere else in your code, check vaultHook != null before you use it.

Adding another plugin's API to your project

To write code against Vault, LuckPerms or PlaceholderAPI, your project needs their API on the compile classpath. In Gradle that takes two parts: the repository (where to download from) and the dependency line with compileOnly (use it to compile, but do not pack it into your jar, because the real plugin on the server provides the classes).

1repositories {2    maven("https://jitpack.io")3}4 5dependencies {6    compileOnly("com.github.MilkBowl:VaultAPI:1.7")7}

1dependencies {2    compileOnly("net.luckperms:api:5.4")3}

1repositories {2    maven("https://repo.extendedclip.com/releases/")3}4 5dependencies {6    compileOnly("me.clip:placeholderapi:2.11.6")7}

Remember the two jobs: Gradle gets your code to compile, and the entry in plugin.yml gets the plugin to load first. Forgetting either one is the usual reason an integration "works on my machine" and nowhere else.

The ServicesManager: how plugins find each other's features

How does your shop find the economy plugin? It does not look for a plugin by name. It asks Paper's ServicesManager for a service: an interface that some plugin has promised to implement.

Using Vault's economy

Vault's interfaces live in net.milkbowl.vault. The economy is net.milkbowl.vault.economy.Economy. Inside the hook class you ask the ServicesManager for it:

1static VaultHook create(Server server) {2    RegisteredServiceProvider<Economy> registration =13        server.getServicesManager().getRegistration(Economy.class);24    return registration == null ? null : new VaultHook(registration.getProvider());5}

Once you have the Economy object, the calls are short. These come from Vault's own API:

1double balance = economy.getBalance(player);12boolean enough = economy.has(player, 50.0);23EconomyResponse result = economy.withdrawPlayer(player, 50.0);4boolean charged = result.transactionSuccess();35String shown = economy.format(50.0);

LuckPerms: ranks and prefixes

LuckPerms has its own API. You get it with LuckPermsProvider.get(), which only works after LuckPerms has finished starting (so make it a softdepend). The next lines read the prefix of an online player:

11LuckPerms api = LuckPermsProvider.get();22User user = api.getPlayerAdapter(Player.class).getUser(player);33String prefix = user.getCachedData().getMetaData().getPrefix();

getPrefix() returns null for a player with no prefix, and when it has one, it is usually old-style text with & color codes, such as &c[Admin]. Turn it into a modern component with the legacy serializer, as the Adventure chapter explains:

1String prefix = user.getCachedData().getMetaData().getPrefix();2Component rank = prefix == null3    ? Component.empty()4    : LegacyComponentSerializer.legacyAmpersand().deserialize(prefix);

PlaceholderAPI: using placeholders

A placeholder is a word between percent signs, such as %player_name%, that PlaceholderAPI swaps for a live value. Who answers the placeholder? A small add-on called an expansion. The built-in player expansion answers %player_name%. Server owners download expansions with /papi ecloud download Player.

To fill placeholders into your own text, hand the text to PlaceholderAPI:

1String raw = "Welcome, %player_name%!";12String filled = PlaceholderAPI.setPlaceholders(player, raw);

Writing your own PlaceholderAPI expansion

The other direction is even more useful: you let every plugin that supports placeholders (scoreboards, chat, holograms) show your plugin's values. An expansion is a class with an identifier and a method that answers requests. In the real class a constructor also stores the CoinService in a field named coins; the snippets leave it out to stay short.

1public final class CoinsExpansion extends PlaceholderExpansion {12    public String getIdentifier() { return "coins"; }3    public String getAuthor() { return "yourname"; }4    public String getVersion() { return "1.0.0"; }25    public boolean persist() { return true; }6}

11public String onRequest(OfflinePlayer player, String params) {2    if (player == null || !params.equals("balance")) {23        return null;4    }5    return String.valueOf(coins.balance(player.getUniqueId()));6}

Finally, register it once, inside the check you already learned, so a server without PlaceholderAPI never loads the class:

1if (getServer().getPluginManager().isPluginEnabled("PlaceholderAPI")) {2    new CoinsExpansion(coins).register();3}

Now %coins_balance% works in every plugin on the server that understands placeholders, including your sidebar.

Providing your own API

Vault works because one plugin defines interfaces and other plugins build on them. You can do the same. The example plugin other-plugins-service-api is a tiny coin system built in three parts:

The interface is tiny. It says what you can do with coins and nothing about how it works. That freedom lets you change the implementation later without breaking anyone:

1package com.example.otherpluginsserviceapi.api;2 3import java.util.UUID;4 5public interface CoinService {6 7    int balance(UUID playerId);8 9    void deposit(UUID playerId, int amount);10 11    boolean withdraw(UUID playerId, int amount);12}

The main class registers the implementation under that interface:

11@Override12public void onEnable() {113    getServer().getServicesManager().register(214        CoinService.class, new InMemoryCoinService(), this, ServicePriority.Normal);15 16    getServer().getPluginManager().registerEvents(new KillRewardListener(getServer()), this);17    registerCommand("coins", "Show your coin balance", new CoinsCommand(getServer()));18}

When your plugin is disabled, Paper removes its services automatically. A different plugin finds the service like this:

12static CoinService find(Server server) {13    RegisteredServiceProvider<CoinService> registration =114        server.getServicesManager().getRegistration(CoinService.class);215    if (registration == null) {16        return null;17    }18    return registration.getProvider();19}

21@EventHandler22public void onDeath(EntityDeathEvent event) {123    if (!(event.getEntity() instanceof Monster)) {24        return;25    }226    Player killer = event.getEntity().getKiller();27    if (killer == null) {28        return;29    }330    CoinService coins = CoinLookup.find(server);31    if (coins == null) {32        return;33    }34    coins.deposit(killer.getUniqueId(), COINS_PER_MONSTER);35    killer.sendRichMessage("<gold>+" + COINS_PER_MONSTER + " coins");36}

In this example both halves sit in one plugin so you can run it with one jar. In real life the consumer package would be a different plugin. To make that work:

1. Build the plugin that offers the service, and give the other developer the api classes, as a jar or a repository.
2. In the second plugin, add it with compileOnly(files("libs/coins-api-1.0.0.jar")), so it is not copied into the second jar.
3. Add softdepend: [CoinsApi] or depend: [CoinsApi] to the second plugin's plugin.yml so Paper loads CoinsApi first and lets the second plugin see its classes.

Mistakes to avoid

• Forgetting the plugin.yml entry. The code compiles but the other plugin may start after yours, and its classes or services are not there yet.
• Packing the other plugin's API into your jar (with implementation instead of compileOnly). You then ship a second copy of the classes, which clashes with the real plugin.
• Mentioning optional types in your main class. A single import is harmless, but a field, parameter or variable of that type can crash startup. Keep them in the hook class.
• Trusting null to never happen. getRegistration, getPlugin and a prefix can all be null. Check every time.
• Only checking at startup. Plugins can start late, so look services up when you need them.
• Misspelling the name. getPlugin and isPluginEnabled ignore capital letters, but "Valt" never matches Vault. In depend a typo means your plugin refuses to load, so copy the name from the other plugin's own plugin.yml.

1int reward = killer.hasPermission("coinsapi.double") ? COINS_PER_MONSTER * 2 : COINS_PER_MONSTER;2coins.deposit(killer.getUniqueId(), reward);3killer.sendRichMessage("<gold>+" + reward + " coins");

1softdepend: [PlaceholderAPI]

1compileOnly("me.clip:placeholderapi:2.11.6")

Recap

• depend means "load me only after this plugin, and fail without it". softdepend means "load after it if it exists".
• Add the other plugin's API as compileOnly with its repository, and list the plugin in plugin.yml.
• Use getPlugin and isPluginEnabled to check for a plugin, and keep its types inside a hook class to avoid NoClassDefFoundError.
• The ServicesManager connects plugins through interfaces. Vault's economy and your own services are found with getRegistration(Interface.class), which can return null.
• LuckPerms gives you ranks through LuckPermsProvider.get(), and PlaceholderAPI lets you both use placeholders and offer your own with an expansion.
• You provide an API by writing an interface and registering an implementation with register.

Quick quiz

Next steps

• Paper plugins: the newer descriptor with a clearer dependency system.
• Permissions: what LuckPerms really manages for you.
• Scoreboards, sidebars and teams: show your coins in a sidebar.