Paper plugins: paper-plugin.yml, bootstrapper and loader

Besides the classic plugin.yml, Paper understands a newer descriptor called paper-plugin.yml. It adds two special startup classes, a bootstrapper and a loader, and a stricter way to declare dependencies. On this page you will use all three, and learn when the extra power is worth it.

Two formats, one server

A descriptor is the small file inside your jar that tells the server what the plugin is. You already know plugin.yml from the plugin.yml chapter. Paper adds a second descriptor, paper-plugin.yml. A plugin has one or the other, never both. Both kinds run side by side on the same server, and you can see them listed separately:

> plugins[12:12:21 INFO]: Server Plugins (8):[12:12:21 INFO]: Paper Plugins (3):[12:12:21 INFO]:  - PaperBootstrapDemo, PaperHelloBootstrap, PaperMinimal[12:12:21 INFO]: Bukkit Plugins (5):[12:12:21 INFO]:  - CoinsApi, PresenceCheck, ScoreboardsDemo, ScoreboardsExercise, ScoreboardsFirstSidebar

"Paper Plugins" are the ones with paper-plugin.yml. "Bukkit Plugins" use plugin.yml. Your Java code can look exactly the same in both, because both still extend JavaPlugin. The differences are in the descriptor and in what you can set up around your main class.

The smallest paper-plugin.yml

The smallest working Paper plugin is a main class and a descriptor with the four fields you know:

1name: PaperMinimal2version: '1.0.0'13main: com.example.paperpluginsbootstrapminimal.MinimalPlugin24api-version: '26.3'5description: The smallest plugin that uses paper-plugin.yml instead of plugin.yml.

7@Override8public void onEnable() {19    registerCommand("papermini", "Says hello from a Paper plugin", (source, args) ->10        source.getSender().sendRichMessage("<green>Hello from a paper-plugin.yml plugin!"));311    getComponentLogger().info("PaperMinimal is ready.");12}

The fields you can use in paper-plugin.yml are:

Declaring dependencies

In plugin.yml you wrote depend, softdepend and loadbefore as three lists of names. A Paper plugin replaces all three with one dependencies section. Each other plugin gets its own small block with three settings:

1dependencies:12  server:23    Vault:34      load: BEFORE45      required: true56      join-classpath: true7    PlaceholderAPI:8      load: BEFORE9      required: false10      join-classpath: true

Paper's own settings are required: true and join-classpath: true when you leave them out. Writing all three lines makes the file easier to read, so the examples always do.

Isolated classloaders

Here is the biggest behavior difference. A classloader is the part of Java that finds and loads the classes inside a jar. Plugins made with plugin.yml can all see each other's classes. Paper plugins are isolated: each one has its own classloader, and it cannot see another plugin's classes unless you declare that plugin as a dependency with join-classpath: true.

That is better for safety (two plugins that bundle different versions of the same library cannot clash), but it also explains a common error. If your Paper plugin calls into Vault and forgets to declare it, the class is not found, exactly like the NoClassDefFoundError in Working with other plugins. The fix is the dependency block above.

The startup order

The two special classes run at the very beginning of the startup, long before onEnable:

The bootstrapper

A bootstrapper is a class you write that implements PluginBootstrap. Paper runs it early, before the worlds and most of the game are ready. Its main job is registering things that must exist before the game finishes loading:

• Commands, with the LifecycleEvents.COMMANDS event.
• Changes to registries, the game's lists of things like enchantments, damage types, paintings and cat variants, through RegistryEvents. Custom enchantments are the most common reason people write a bootstrapper.
• Datapacks your plugin brings along, with LifecycleEvents.DATAPACK_DISCOVERY.

The example plugin paper-plugins-bootstrap-demo has a bootstrapper that does three things: logs a line, registers a command, and passes some information to the plugin. Here is the class:

1package com.example.paperpluginsbootstrapdemo;2 3import io.papermc.paper.plugin.bootstrap.BootstrapContext;4import io.papermc.paper.plugin.bootstrap.PluginBootstrap;5import io.papermc.paper.plugin.bootstrap.PluginProviderContext;6import io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents;7import java.time.Instant;8import org.bukkit.plugin.java.JavaPlugin;9 110@SuppressWarnings("UnstableApiUsage")211public final class DemoBootstrap implements PluginBootstrap {12 13    private BootInfo bootInfo;14 15    @Override316    public void bootstrap(BootstrapContext context) {17        bootInfo = new BootInfo(Instant.now());418        context.getLogger().info("Bootstrapping {} v{}",19            context.getConfiguration().getName(), context.getConfiguration().getVersion());20 521        context.getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event ->622            event.registrar().register(BootCheckCommand.create(bootInfo), "Shows when the bootstrapper ran"));23    }24 25    @Override726    public JavaPlugin createPlugin(PluginProviderContext context) {827        return new DemoPlugin(bootInfo);28    }29}

14static LiteralCommandNode<CommandSourceStack> create(BootInfo bootInfo) {115    return Commands.literal("bootcheck")16        .executes(context -> {17            long seconds = bootInfo.timeSinceBootstrap().toSeconds();18            context.getSource().getSender().sendRichMessage(19                "<gray>The bootstrapper ran <yellow><seconds></yellow> seconds ago.",220                Placeholder.unparsed("seconds", Long.toString(seconds)));321            return Command.SINGLE_SUCCESS;22        })23        .build();24}

1package com.example.paperpluginsbootstrapdemo;2 3import java.time.Duration;4import java.time.Instant;5 16record BootInfo(Instant bootstrappedAt) {7 8    Duration timeSinceBootstrap() {9        return Duration.between(bootstrappedAt, Instant.now());10    }11}

The plugin class receives that object in its constructor and uses it in onEnable:

19DemoPlugin(BootInfo bootInfo) {10    this.bootInfo = bootInfo;11}

13@Override14public void onEnable() {15    getComponentLogger().info("Enabled {} ms after the bootstrapper ran.",116        bootInfo.timeSinceBootstrap().toMillis());17    getComponentLogger().info("Caffeine library available: {}",218        isClassAvailable("com.github.benmanes.caffeine.cache.Caffeine"));19}

The loader and runtime libraries

Sometimes your plugin needs a library that the server does not have, such as a caching library or a database driver. You could pack it into your jar, which makes the jar big. A loader offers a cleaner way: it tells Paper which libraries to download when the server starts, and Paper adds them to your plugin's classpath. The classpath is the list of places where Java looks for classes.

13@Override114public void classloader(PluginClasspathBuilder classpathBuilder) {215    MavenLibraryResolver resolver = new MavenLibraryResolver();16    resolver.addRepository(new RemoteRepository.Builder(317        "central", "default", MavenLibraryResolver.MAVEN_CENTRAL_DEFAULT_MIRROR).build());18    resolver.addDependency(new Dependency(419        new DefaultArtifact("com.github.ben-manes.caffeine:caffeine:3.2.0"), null));520    classpathBuilder.addLibrary(resolver);21}

The loader runs even before the bootstrapper. On the first start you can watch the download in the console:

[12:12:05 INFO]: [PluginInitializerManager] Initializing plugins...[12:12:06 INFO]: [MavenLibraryResolver] Downloading https://maven-central.storage-download.googleapis.com/maven2/com/github/ben-manes/caffeine/caffeine/3.2.0/caffeine-3.2.0.jar[12:12:07 INFO]: [PluginInitializerManager] Initialized 8 plugins[12:12:08 INFO]: [PaperBootstrapDemo] Bootstrapping PaperBootstrapDemo v1.0.0[12:12:20 INFO]: [PaperBootstrapDemo] Enabling PaperBootstrapDemo v1.0.0[12:12:20 INFO]: [PaperBootstrapDemo] Enabled 12902 ms after the bootstrapper ran.[12:12:20 INFO]: [PaperBootstrapDemo] Caffeine library available: true

To use the library in your own code, also add it to build.gradle.kts as compileOnly, so your code compiles but Gradle does not pack it into the jar:

1dependencies {2    compileOnly("com.github.ben-manes.caffeine:caffeine:3.2.0")3}

1Cache<UUID, Integer> kills = Caffeine.newBuilder()2    .expireAfterWrite(Duration.ofMinutes(10))3    .build();

Putting it together

This is the whole demo plugin. The descriptor ties the three classes together:

1name: PaperBootstrapDemo2version: '1.0.0'3main: com.example.paperpluginsbootstrapdemo.DemoPlugin14bootstrapper: com.example.paperpluginsbootstrapdemo.DemoBootstrap25loader: com.example.paperpluginsbootstrapdemo.DemoLoader6api-version: '26.3'7description: A bootstrapper that registers a command early and a loader that downloads a library.8authors: [Guide]9dependencies:10  server:311    LuckPerms:12      load: BEFORE13      required: false14      join-classpath: true

Start the server and type bootcheck in the console. You see how long ago the bootstrapper ran:

> bootcheck[12:12:22 INFO]: The bootstrapper ran 14 seconds ago.

Which format should you choose?

A short rule: start with plugin.yml. Switch to paper-plugin.yml when you need custom registry entries, a bootstrapper, a loader with your own repository, or you want Paper's stricter isolation. Do not switch just because it is newer. A plugin with plugin.yml keeps working on Paper, and you lose nothing for ordinary plugins.

Mistakes to avoid

• Having both descriptors. A jar needs one. Pick a format and delete the other file.
• Adding a commands: section to paper-plugin.yml. It does nothing. Register commands in code.
• Using the Bukkit API in bootstrap. The server is not ready, so things like Bukkit.getWorld or Bukkit.getOnlinePlayers fail or return nothing. Do the work in onEnable instead.
• Forgetting the dependency block for a plugin whose classes you use, which leads to NoClassDefFoundError because of the isolated classloaders.
• A wrong class name in main, bootstrapper or loader. These are full names with the package, spelled exactly like the class.
• Typing Maven Central's URL into your loader. Use MavenLibraryResolver.MAVEN_CENTRAL_DEFAULT_MIRROR.
• Reaching for these tools too early. Most plugin ideas, including every project in this guide, work with a plain plugin.yml.

1name: PaperHelloBootstrap2version: '1.0.0'3main: com.example.paperpluginsbootstrapexercise.HelloPlugin4bootstrapper: com.example.paperpluginsbootstrapexercise.HelloBootstrap5api-version: '26.3'6description: Registers /hello from the bootstrapper.

11@Override12public void bootstrap(BootstrapContext context) {13    context.getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event ->114        event.registrar().register("hello", "Greets you by name", (source, args) ->15            source.getSender().sendRichMessage(16                "<green>Hello, <white><name></white>!",217                Placeholder.unparsed("name", source.getSender().getName()))));18}

1depend: [Vault]2softdepend: [PlaceholderAPI]3loadbefore: [Essentials]

1dependencies:2  server:3    Vault:4      load: BEFORE5      required: true6      join-classpath: true7    PlaceholderAPI:8      load: BEFORE9      required: false10      join-classpath: true11    Essentials:12      load: AFTER13      required: false14      join-classpath: false

Recap

• paper-plugin.yml is Paper's newer descriptor. A plugin uses it or plugin.yml, never both.
• It has no commands: section, so commands go in code. Dependencies move into one dependencies section with load, required and join-classpath.
• Paper plugins run in isolated classloaders. To use another plugin's classes, declare it as a dependency with join-classpath: true.
• The loader runs first and builds the classpath, for example by downloading libraries with MavenLibraryResolver and the default Maven Central mirror.
• The bootstrapper runs before the worlds load. Use it for commands, registry changes and datapacks, and pass data to your plugin through createPlugin. Most of the Bukkit API does not work there yet.
• Start with plugin.yml. Choose paper-plugin.yml only when you need these extra abilities.

Quick quiz

Next steps

• Registries, keys and data components: what the game's registries are, and what the bootstrapper can add to them.
• Commands, part 2: the command trees you register from a bootstrapper.
• Server internals (NMS) with paperweight: another advanced topic that uses a Paper plugin setup.