📦Ship Your Own Loader

Every protected plugin ships its own loader, named after itself. Here is why, and the ten lines it takes.

If you sell a protected plugin, build a loader named after your plugin and ship that. Do not ship the generic one.

Why

A loader hosts exactly one protected module. It has one config file, one product id, one license key, and one module in memory.

Bukkit refuses to enable two plugins with the same name, and Velocity refuses two plugins with the same id. So if every seller shipped the stock ObsidianLoader, a customer who bought protected plugins from two different sellers could install exactly one of them. The second would fail to load, and the two would fight over the same plugins/ObsidianLoader/config.yml anyway.

Name the loader after your plugin and the problem disappears. Your customers install MyPlugin, someone else's install TheirPlugin, and both run happily side by side.

The generic loader from the dashboard is still useful: for testing, and for a customer who only ever runs one protected plugin. It is just not what you distribute.

Get the code

Everything the loader is made of is public:

GitHub - ohAleee/obsidianlicense-api: Public API contract and licence-check client for ObsidianLicense. Paper, Velocity and plain Java.GitHub

repositories {
    mavenCentral()
    maven("https://jitpack.io")
    maven("https://repo.papermc.io/repository/maven-public/")
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.8-R0.1-SNAPSHOT")
    implementation("com.github.ohAleee.obsidianlicense-api:paper:v1.2.1")
}

Use velocity instead of paper for a proxy plugin. You can also just copy the sources into your project if you would rather not add a dependency.

Selling for 1.8? Use v1.2.1 or newer. Earlier releases reached the command map through Server#getCommandMap(), which Paper only added in 1.19.4, so registering a module's commands threw NoSuchMethodError on older servers. The loader now resolves it reflectively off the concrete server class, which works on every generation.

Whatever version you use, remember that the paper module compiles against a current Paper API. If your loader itself calls a Bukkit method that does not exist on your oldest target, that is a runtime failure on the customer's server, not a compile error on yours. Compiling your loader against your oldest supported API as a build step is the cheapest way to catch it.

The loader, in full

package com.example.myplugin;

import com.obsidian.license.core.ObsidianLoader;
import com.obsidian.license.loader.PaperLoader;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPluginLoader extends JavaPlugin {

    // You know these three, so hardcode them.
    private static final String SERVER_URL = "https://license.ohalee.com";
    private static final String PRODUCT_ID = "my-plugin";
    private static final String PUBLIC_KEY = "MCowBQYDK2VwAyEA...";   // Dashboard, Server key

    private ObsidianLoader loader;

    @Override
    public void onEnable() {
        saveDefaultConfig();
        try {
            loader = PaperLoader.builder(this)
                    .serverUrl(SERVER_URL)
                    .productId(PRODUCT_ID)
                    .serverPublicKey(PUBLIC_KEY)
                    .licenseKey(getConfig().getString("licenseKey", ""))
                    // .variant("game")   only if your product ships several jars
                    .build();
            loader.start();
        } catch (Exception e) {
            // Fail closed. The message is written for the customer, so print it as-is.
            getLogger().severe("License check failed: " + e.getMessage());
            getServer().getPluginManager().disablePlugin(this);
        }
    }

    @Override
    public void onDisable() {
        if (loader != null) loader.stop();
    }
}

plugin.yml:

name: MyPlugin          # your name, not ObsidianLoader
version: '1.0.0'
main: com.example.myplugin.MyPluginLoader
api-version: '1.21'
load: STARTUP

config.yml, which is all your customer ever edits:

licenseKey: "OBS-XXXX-XXXX-XXXX-XXXX"

Hardcode the server URL, product id and public key rather than putting them in config.yml. The only thing a customer should have to paste is their license key, and a pinned public key they cannot edit is a public key nobody can talk them into changing.

Shade the dependency so the loader carries its own classes:

tasks.shadowJar {
    relocate("com.google.gson", "com.example.myplugin.libs.gson")
}

Velocity

The same shape, with VelocityLoaderSupport and your own plugin id:

@Plugin(id = "myplugin", name = "MyPlugin", version = "1.0.0")
public final class MyProxyLoader {

    @Subscribe
    public void onInit(ProxyInitializeEvent event) {
        try {
            String key = VelocityLoaderSupport.readConfig(dataFolder).getOrDefault("licenseKey", "");
            loader = VelocityLoaderSupport.builder(this, proxy, dataFolder)
                    .serverUrl(SERVER_URL).productId(PRODUCT_ID).serverPublicKey(PUBLIC_KEY)
                    .licenseKey(key)
                    .build();
            loader.start();
        } catch (Exception e) {
            // Velocity cannot disable a plugin at runtime, so register nothing and say why.
            logger.error("License check failed, this plugin will NOT run: {}", e.getMessage());
        }
    }
}

Full template: MyProxyLoader.java.

Plain Java

There is no plugin to name, so there is no collision to avoid: use ObsidianLoader directly from your own main. See StandaloneHost.java.

What you ship

Two jars, from two builds:

Jar	Built from	Goes to
MyPlugin.jar (the loader)	Your loader project	Your customers
my-plugin-1.0.0.jar (the module)	Your real plugin	Uploaded to the dashboard, never shipped

The module jar is the one that stays secret. The loader is public by nature: it runs on customer machines and can be decompiled by anyone, which is why none of its security depends on being hidden. It pins a public key, and every real check happens on the server.

Keeping it up to date

Bump the dependency when the platform's signed envelope changes, then rebuild and redistribute your loader. Older loaders fail closed with "response signature invalid" rather than doing anything unsafe, but your customers will notice. Release notes call out any change that needs this.