BuiltByBit Anti-Piracy Placeholders and License Keys, Explained

If you sell on BuiltByBit, you get one of the most useful anti-piracy tools in the Minecraft world for free: placeholders. When a buyer downloads your resource, BuiltByBit finds special strings in your files and replaces them with details about that specific download.

Used well, they tell you exactly who leaked a copy, and they can put a working license key in the jar without the buyer doing anything. Here's how they work and how to use them properly.

How placeholders work

You put a placeholder string, like %%__USER__%%, somewhere in your plugin. When someone downloads your resource, BuiltByBit replaces that string in the file with the real value (for example, the buyer's user ID). Every buyer gets a slightly different jar.

Your code reads the value like any other string. If a jar turns up on a leak site, the values inside it point back to the account that downloaded it.

The built-in placeholders

According to BuiltByBit's anti-piracy placeholder docs, these are available on every download:

On top of these, you can create custom placeholders of several types: nonce, plain text, SHA256 hash and external license key.

Reading placeholders in Java

Store the placeholder in a field and read it at runtime:

public final class Downloader {
    private static String user = "%%__USER__%%";
    private static String nonce = "%%__NONCE__%%";

    public static boolean fromBuiltByBit() {
        return !user.startsWith("%%__");
    }

    public static String user() {
        return user;
    }
}

There's one trap here that catches a lot of people. Don't compare against the full placeholder string, like user.equals("%%__USER__%%"). BuiltByBit replaces every occurrence it finds, including the one in your comparison, so the check ends up comparing the user ID to itself. Check for the %%__ prefix instead, which isn't a placeholder on its own and is left alone.

A few more tips:

• Use them in more than one place. A leaker who finds one placeholder will strip it. Copy the values into config defaults, log lines or metadata your plugin actually uses, and they're much harder to remove cleanly.
• Keep them out of string encryption. If you run an obfuscator that encrypts string constants, BuiltByBit can't find the placeholder to replace it. Exclude the classes that hold placeholders. (We cover this in obfuscating a plugin with ProGuard.)
• Test with a real download. The values only exist in jars downloaded through BuiltByBit. Your local build will always show the raw placeholder text.

External license key placeholders

The most powerful type is the external license key. You give BuiltByBit a placeholder name, a URL and a secret. When a buyer downloads the resource, BuiltByBit calls that URL, gets a license key back and writes it into the jar in place of the placeholder.

The result: every buyer's download already contains their own valid license key. No email, no "DM me your order ID", and nothing for the buyer to paste in.

Setting it up with MC License

1. In the MC License dashboard, go to Keys and generate a BuiltByBit webhook secret.
2. On BuiltByBit's placeholders page, create a placeholder:
   • Placeholder: %%__BBB_LICENSE__%%
   • Type: External license key
   • URL: https://api.mclicense.org/builtbybit
   • Secret: the secret from step 1
3. In MC License, create your plugin using your BuiltByBit resource URL.
4. Add the license check to your plugin:

if (!MCLicense.validateKey(this, "yourPluginId")) {
    Bukkit.getPluginManager().disablePlugin(this);
    return;
}

You don't need to reference %%__BBB_LICENSE__%% yourself. The MC License library already contains the placeholder, so BuiltByBit fills it in on download, and the library uses that key on first start and saves it to mclicense.txt.

Each key is a fully managed license from the start. It appears in your dashboard with the buyer's BuiltByBit username, uses your plugin's default server limits, and you can edit, disable or revoke it at any time. (If you're on BuiltByBit's Ultimate tier, add your own API token for username resolution.)

New to adding a license check? Follow our step-by-step guide to adding a license key to a Paper plugin.

Placeholders vs license keys: use both

They solve different problems:

• Placeholders tell you who leaked a copy, after the fact.
• A license key with server limits stops a leaked copy from working, and lets you shut it off remotely.

Together they cover both sides: the shared jar stops working, and you know which account it came from. Here's what to do next when you find a leaked copy of your plugin.