| Platform | \nBase API | \nNotes | \n
|---|---|---|
| Paper | \nBukkit/Spigot + Paper extensions | \nRecommended; async chunk loading, Adventure native | \n
| Spigot | \nBukkit + Spigot extensions | \nLegacy; fewer APIs, slower | \n
| Bukkit | \nBase API only | \nAvoid for new plugins | \n
| Folia | \nPaper fork | \nRegion-threaded; requires special scheduler APIs | \n
\n\nPaper is the recommended target. Paper includes all Bukkit and Spigot APIs plus\nsignificant performance improvements and additional APIs.
\n
Use when: the target is server-side Paper/Bukkit/Spigot plugin behavior with JavaPlugin APIs.Do not use when: the task requires client-side installable mods or loader APIs (minecraft-modding / minecraft-multiloader).Do not use when: the task is pure vanilla datapack/command content (minecraft-datapack / minecraft-commands-scripting).references/runtime-patterns.md when the task touches scheduling, Folia support, PDC, Adventure/MiniMessage, YAML config, Vault, or Paper-specific APIs.references/paper-plugin-commands.md for a Paper-only paper-plugin.yml project or Brigadier command registration.The examples below target current Paper 26.2 and Java 25. For an existing\n1.21.x plugin, preserve its 1.21.x-R0.1-SNAPSHOT dependency, Java 21\ntoolchain, and matching api-version until the project is intentionally ported.
settings.gradle.ktsrootProject.name = \"my-plugin\"\nbuild.gradle.ktsplugins {\n java\n}\n\ngroup = \"com.example\"\nversion = \"1.0.0-SNAPSHOT\"\n\nrepositories {\n mavenCentral()\n maven(\"https://repo.papermc.io/repository/maven-public/\")\n}\n\ndependencies {\n compileOnly(\"io.papermc.paper:paper-api:26.2.build.+\")\n}\n\njava {\n toolchain.languageVersion.set(JavaLanguageVersion.of(25))\n}\n\ntasks {\n processResources {\n // Substitutes ${version} in plugin.yml with the Gradle project version\n filesMatching(listOf(\"plugin.yml\", \"paper-plugin.yml\")) {\n expand(\"version\" to project.version)\n }\n }\n}\nAdd Shadow only when the plugin has runtime libraries that must be bundled and\nrelocated. Paper and optional plugin APIs such as Vault remain compileOnly and\nmust not be shaded into the plugin JAR.
gradle/wrapper/gradle-wrapper.propertiesdistributionUrl=https\\://services.gradle.org/distributions/gradle-9.1.0-bin.zip\nGradle 8.8 cannot run on Java 25. Use Gradle 9.1 or newer for a current Java 25\nproject. Preserve the existing wrapper and Java 21 toolchain for a legacy 1.21.x\nproject unless its build is intentionally upgraded and verified.
\nmy-plugin/\n├── build.gradle.kts\n├── settings.gradle.kts\n├── gradle/\n│ └── wrapper/\n│ └── gradle-wrapper.properties\n└── src/main/\n ├── java/com/example/myplugin/\n │ ├── MyPlugin.java ← main class (extends JavaPlugin)\n │ ├── listeners/\n │ │ └── PlayerListener.java\n │ ├── commands/\n │ │ └── MyCommand.java\n │ └── managers/\n │ └── DataManager.java\n └── resources/\n ├── plugin.yml ← Bukkit-compatible descriptor\n ├── paper-plugin.yml ← active descriptor for a Paper plugin\n └── config.yml\nplugin.yml (Bukkit-compatible default)name: MyPlugin\nversion: \"${version}\"\nmain: com.example.myplugin.MyPlugin\ndescription: An example Paper plugin\nauthor: YourName\nwebsite: https://github.com/example/my-plugin\napi-version: '26.2'\n\ncommands:\n myplugin:\n description: Main plugin command\n usage: /myplugin <subcommand>\n permission: myplugin.use\n aliases: [mp]\n\npermissions:\n myplugin.use:\n description: Allows use of /myplugin\n default: true\n myplugin.admin:\n description: Admin access\n default: op\n\n\nMatch
\napi-versionto the oldest Paper API the plugin intentionally supports.\nCurrent Paper examples use26.2; legacy1.21and positive1.21.<patch>\nvalues remain valid for older servers. A server older than the declared value\nrefuses to load the plugin.
paper-plugin.yml (experimental Paper-only format)Prefer plugin.yml for Bukkit-compatible plugins. Use paper-plugin.yml only\nwhen the JAR is intentionally Paper-only and needs Paper-plugin behavior such\nas bootstrapping, loaders, or classloading isolation. It can be the only\ndescriptor, but is not a drop-in replacement: Paper plugins do not use a\ncommands field or getCommand(...) registration. Read\nreferences/paper-plugin-commands.md\nfor the paired descriptor, main class, and Brigadier lifecycle registration.
When one JAR ships both descriptors, keep their shared metadata and main class\naligned. Do not combine the Paper-only sample with the Bukkit-compatible\nMyPlugin sample below.
package com.example.myplugin;\n\nimport com.example.myplugin.commands.MyCommand;\nimport com.example.myplugin.listeners.PlayerListener;\nimport org.bukkit.plugin.java.JavaPlugin;\n\npublic final class MyPlugin extends JavaPlugin {\n\n @Override\n public void onEnable() {\n saveDefaultConfig();\n\n // Register listeners\n getServer().getPluginManager().registerEvents(new PlayerListener(), this);\n\n // Register commands\n var cmd = getCommand(\"myplugin\");\n if (cmd == null) {\n throw new IllegalStateException(\"myplugin command is missing from plugin.yml\");\n }\n var handler = new MyCommand(this);\n cmd.setExecutor(handler);\n cmd.setTabCompleter(handler);\n\n getLogger().info(\"MyPlugin enabled!\");\n }\n\n @Override\n public void onDisable() {\n getLogger().info(\"MyPlugin disabled.\");\n }\n\n}\npackage com.example.myplugin.listeners;\n\nimport net.kyori.adventure.text.Component;\nimport net.kyori.adventure.text.format.NamedTextColor;\nimport org.bukkit.event.EventHandler;\nimport org.bukkit.event.EventPriority;\nimport org.bukkit.event.Listener;\nimport org.bukkit.event.entity.PlayerDeathEvent;\nimport org.bukkit.event.player.PlayerJoinEvent;\nimport org.bukkit.event.player.PlayerQuitEvent;\n\npublic class PlayerListener implements Listener {\n\n @EventHandler(priority = EventPriority.NORMAL)\n public void onPlayerJoin(PlayerJoinEvent event) {\n event.joinMessage(\n Component.text(event.getPlayer().getName() + \" joined!\", NamedTextColor.GREEN)\n );\n }\n\n @EventHandler\n public void onPlayerQuit(PlayerQuitEvent event) {\n event.quitMessage(\n Component.text(event.getPlayer().getName() + \" left.\", NamedTextColor.YELLOW)\n );\n }\n\n @EventHandler\n public void onPlayerDeath(PlayerDeathEvent event) {\n // Modify death message using Adventure components\n event.deathMessage(\n Component.text(\"☠ \", NamedTextColor.RED)\n .append(Component.text(event.getPlayer().getName(), NamedTextColor.WHITE))\n .append(Component.text(\" died!\", NamedTextColor.RED))\n );\n }\n}\nLOWEST → LOW → NORMAL → HIGH → HIGHEST → MONITOR
\nUse MONITOR for logging only (never modify outcome). On events that implement\nCancellable, use ignoreCancelled = true unless you need cancelled events.
@EventHandler\npublic void onBlockBreak(BlockBreakEvent event) {\n if (event.getPlayer().hasPermission(\"myplugin.break.deny\")) {\n event.setCancelled(true);\n event.getPlayer().sendMessage(Component.text(\"You cannot break blocks!\", NamedTextColor.RED));\n }\n}\nThis section is for the plugin.yml path above. Its declared command enables\ngetCommand(\"myplugin\"). For a Paper-only descriptor, use the Brigadier\nlifecycle example in references/paper-plugin-commands.md.
package com.example.myplugin.commands;\n\nimport com.example.myplugin.MyPlugin;\nimport net.kyori.adventure.text.Component;\nimport net.kyori.adventure.text.format.NamedTextColor;\nimport org.bukkit.command.Command;\nimport org.bukkit.command.CommandExecutor;\nimport org.bukkit.command.CommandSender;\nimport org.bukkit.command.TabCompleter;\nimport org.bukkit.entity.Player;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.List;\nimport java.util.Locale;\n\npublic class MyCommand implements CommandExecutor, TabCompleter {\n\n private final MyPlugin plugin;\n\n public MyCommand(MyPlugin plugin) {\n this.plugin = plugin;\n }\n\n @Override\n public boolean onCommand(@NotNull CommandSender sender, @NotNull Command command,\n @NotNull String label, @NotNull String[] args) {\n if (!(sender instanceof Player player)) {\n sender.sendMessage(Component.text(\"Only players can use this command.\", NamedTextColor.RED));\n return true;\n }\n\n if (!player.hasPermission(\"myplugin.use\")) {\n player.sendMessage(Component.text(\"No permission.\", NamedTextColor.RED));\n return true;\n }\n\n if (args.length == 0) {\n player.sendMessage(Component.text(\"Usage: /myplugin <reload|info>\", NamedTextColor.YELLOW));\n return true;\n }\n\n return switch (args[0].toLowerCase(Locale.ROOT)) {\n case \"reload\" -> {\n plugin.reloadConfig();\n player.sendMessage(Component.text(\"Config reloaded.\", NamedTextColor.GREEN));\n yield true;\n }\n case \"info\" -> {\n player.sendMessage(Component.text(\"Version: \" + plugin.getDescription().getVersion(), NamedTextColor.AQUA));\n yield true;\n }\n default -> {\n player.sendMessage(Component.text(\"Unknown subcommand.\", NamedTextColor.RED));\n yield true;\n }\n };\n }\n\n @Override\n public @Nullable List<String> onTabComplete(@NotNull CommandSender sender, @NotNull Command command,\n @NotNull String label, @NotNull String[] args) {\n if (args.length == 1) {\n return List.of(\"reload\", \"info\").stream()\n .filter(s -> s.startsWith(args[0].toLowerCase(Locale.ROOT)))\n .toList();\n }\n return List.of();\n }\n}\nFor classic Paper plugins, BukkitScheduler is still fine. If you claim Folia support,\nroute player, entity, region, global, and async work through the matching Folia-aware\nscheduler. Keep scheduling behind a small project-local interface when one plugin must\nsupport both Paper and Folia.
See references/runtime-patterns.md for copy-ready sync, async, cancelable, and\nFolia-safe scheduler examples.
PDC stores arbitrary data on any PersistentDataHolder (players, entities, items, chunks).\nData is saved with the world and persists across restarts.
Create NamespacedKey instances once, keep data types stable after release, and use\nPDC for small metadata rather than large datasets. Prefer config files or a database\nfor large or query-heavy plugin state.
See references/runtime-patterns.md for player, item, chunk, and world PDC examples.
Paper uses Adventure natively for all text. No legacy chat colors.\nUse Component builders for code-owned messages and MiniMessage for config-driven\nmessages. Avoid legacy ChatColor unless the target project already depends on it\nfor compatibility.
See references/runtime-patterns.md for simple messages, hover/click events,\nMiniMessage parsing, titles, and action bars.
src/main/resources/config.yml# Default config\nsettings:\n max-players: 20\n welcome-message: \"<green>Welcome to the server!\"\n cooldown-seconds: 30\n\ndatabase:\n host: localhost\n port: 3306\n name: myplugin_db\nCall saveDefaultConfig() in onEnable(), provide explicit defaults when reading\nvalues, and validate config shape before starting long-running tasks.
Use custom YAML files only when separating user config from mutable plugin data is\nworth the extra file handling. Keep blocking disk writes off hot event paths.
\nSee references/runtime-patterns.md for config read/write and custom YAML examples.
Declare Vault as compileOnly, soft-depend on it in plugin metadata, and disable\neconomy features cleanly when the service provider is unavailable. Never assume a\nVault-compatible economy plugin is installed just because Vault itself is present.
When Vault support is required, add the JitPack repository and\ncompileOnly(\"com.github.MilkBowl:VaultAPI:1.7\") to the Gradle build.
See references/runtime-patterns.md for a minimal economy setup and charge example.
Use Paper APIs when they remove main-thread blocking or simplify Adventure-native\nbehavior. Keep optional plugin integrations behind presence checks and metadata\nsoft-dependencies.
\nSee references/runtime-patterns.md for async chunk loading, custom item meta,\nprofile lookup, and protection-plugin integration examples.
Listener@EventHandlergetServer().getPluginManager().registerEvents(listener, plugin) in onEnable()ignoreCancelled = true unless you need cancelled eventsplugin.yml, create a CommandExecutor, and register it with getCommand(\"name\")LifecycleEvents.COMMANDS; do not add a commands fieldconfig.yml via getConfig() / saveConfig()NamespacedKeyrunTaskTimer) or is I/O (use runTaskTimerAsynchronously)BukkitTask reference so you can cancel in onDisable()onDisable() or use getServer().getScheduler().cancelTasks(plugin)./gradlew build\n# Output: build/libs/my-plugin-1.0.0-SNAPSHOT.jar\n./scripts/validate-plugin-layout.sh --root /path/to/plugin-project\n# Strict mode treats warnings as failures:\n./scripts/validate-plugin-layout.sh --root /path/to/plugin-project --strict\nserver/plugins/ and restart the Paper server.\nIf the real project already applies a Paper dev-server plugin such as xyz.jpenilla.run-paper,\nuse that project's documented dev task instead of assuming ./gradlew runServer exists.The validator checks:
\nplugin.yml or paper-plugin.yml required keys (name, version, main, api-version) and repo-supported current 26.<release> or legacy 1.21 / positive 1.21.<patch> values, with warnings for versions newer than the documented examplespaper-plugin.yml is selected as activeJavaPlugin/reload anti-patterns such as Bukkit.reload() or dispatching the server reload command