Paper Plugin Template (Gradle)

---

Description

This is a configured and ready to go template for making Minecraft plugins. It includes a plethora of useful boilerplate, libraries and examples to quickly get you going when creating a new plugin.

All of the included libraries and tooling has been hand-picked for its stability and extendability. Its purpose is to minimize duplicated code, while providing powerful and ergonomic ways of working with the Bukkit API, databases, configuration and repository maintenance.

---

Information

---

Template Features

Note

Is there some feature/library you don't need? Remove it!

GitHub Setup:

• Issue Templates - Templates to streamline bug reports and feature requests.
• Funding - You can configure your sponsor button by editing a FUNDING.yml....
• Codeowners - Listed users are automatically requested for review when....
• Contributor Code of Conduct - A code of conduct for all contributors to follow.
• Contributing Guidelines - Provides a guide and technical specifications regarding your project.
• License - Change this to whatever license you wish to use.

Automation:

• Stale Workflow - Issues and PRs are marked as stale after 60 days.
• Build Workflow - Each commit builds a snapshot jar for testing.
• Release Workflow - Automated releases and pre-releases using tags.
• Dependabot - Dependabot will create PRs to keep your dependencies up-to date.

Specifications:

• Commit Messages: Conventional Commits
• Versioning: Semantic Versioning 2.0.0
• Style Guide: .editorconfig

Versioning Strategy:

• Stable releases as: ExamplePlugin-1.0.0.jar
• Testing releases as: ExamplePlugin-1.0.0-RC-X.jar
• Development releases as: ExamplePlugin-1.0.0-SNAPSHOT-X.jar

GitHub Event	Version Format	CI Action	GitHub Release Draft?
Tag X.Y.Z	X.Y.Z	Build, test & release	Release
Tag X.Y.Z-RC-N	X.Y.Z-RC-N	Build, test & release	Pre-release
Schedule	X.Y.Z-SNAPSHOT-TIME	Build & test	No
Push to main or master	X.Y.Z-SNAPSHOT-TIME	Build & test	No
Pull Request	X.Y.Z-SNAPSHOT-TIME	Build & test	No

---

Template Libraries

• MiniMessage support using Adventure with utility library ColorParser.
• Command creation and handling using CommandAPI.
• GUIs using Triumph GUI.
• YAML, JSON & TOML Configuration files using Crate.
• Database Setup & Tooling:
  • Database versioning and migrations using Flyway.
  • jOOQ to build and execute type safe SQL queries.
  • Uses HikariCP to manage the connection pool.
  • Supports the following database engines out of the box:
    • HyperSQL (Local)
    • H2 (Local)
    • MySQL (Remote)
    • MariaDB (Remote)

---

Documentation Links

Adventure Library

• ColorParser - Link
• MiniMessage Formatting - Link
• MiniMessage Previewer - Link
• Adventure Documentation - Link

Minecraft APIs

• CommandAPI - Link
• Triumph GUI - Link
• Crate - Link

Database Tooling

• Flyway - Link
• jOOQ - Link

Gradle Plugin.yml Generation

• Plugin.yml Generator - Link

---

Setup

1. Change .github/CODEOWNERS

   Replace GITHUB_USERNAME with your GitHub username.

   *       @darksaid98 @SOME_OTHER_USER

2. Change .github/FUNDING.yml

   Replace GITHUB_USERNAME with your GitHub username. You can configure your sponsor button by editing the FUNDING.yml.

   github: darksaid98
   github: SOME_OTHER_USER

3. Change Code of Conduct

   If you choose to adopt the Code of Conduct in this template, please replace GITHUB_CONTACT_EMAIL at line 63 with your preferred method of contact. Otherwise replace or remove it.

4. Change Project Name

   Replace all occurances of ExamplePlugin with your new plugin name. Don't forget to rename the main class ExamplePlugin.java to the same value.

   rootProject.name = "MyNamePlugin"

5. Change build.gradle.kts

   1. Change Plugin Info

      The final package path for your plugin will end up being something like io.github.darksaid98.exampleplugin. It's made up of these components io.github.<USERNAME>.<PLUGINNAME> where <USERNAME> is your github name in lowercase, and <PLUGINNAME> is added by rootProject.name lowercased.

      Don't forget to change package locations in src/main/java/ when changing the group.

      group = "io.github.darksaid98"
      version = "0.9.8"
      description = "Some plugin description here..."

   2. Change Plugin.yml

      [!NOTE] The plugin.yml is automatically generated by gradle.

      Update the authors list and any other required settings.

      authors = listOf("GITHUB_USERNAME") // Replace with your username
      contributors = listOf()
      apiVersion = "1.19"
      
      // Misc properties
      load = net.minecrell.pluginyml.bukkit.BukkitPluginDescription.PluginLoadOrder.POSTWORLD // STARTUP or POSTWORLD
      depend = listOf()
      softDepend = listOf()

   3. Change Dependencies

      Lastly, remove/add any dependecies you don't need/want.

      You can also make the development server install any plugin dependencies:

      downloadPlugins {
          //modrinth("carbon", "2.1.0-beta.21")
          //github("jpenilla", "MiniMOTD", "v2.0.13", "minimotd-bukkit-2.0.13.jar")
          //hangar("squaremap", "1.2.0")
          //url("https://download.luckperms.net/1515/bukkit/loader/LuckPerms-Bukkit-5.4.102.jar")
          github("MilkBowl", "Vault", "1.7.3", "Vault.jar")
      }

---

Testing & Debugging

The template includes jpenilla's run-task gradle plugin. This allows you to easily setup and run a development server for your plugin.

By default IntelliJ IDEA has excellent integration for debugging, and enables running your test server with a debugger attached, in one click.

If using other IDEs you can connect a debugger to port 5005 which the development server listens on by default.

Development Server

1. Run gradlew runServer to start a minecraft server on localhost:25565.

Debugging (IntelliJ IDEA)

The Development Server is configured to work with the IntelliJ Debugger by default.

Simply press the Debug button to launch your Development Server with a Debugger attached.

Debugging (External Debugger)

Note

The steps here are mirrored from PaperMC's Guide and are meant for IntelliJ IDEA. Other IDEs may be similar.

1. Open the Run/Debug Configurations page by clicking Edit Configurations....

2. Click the + button in the top left and select Remote JVM Debug.

3. Name the config whatever you want (like Debug), then hit Apply.

Note

The Development Server listens for Debuggers on port 5005.

4. When your Development Server is running, connect your debugger by pressing the Debug button.

---

Credits

• leviem1: For their excellent Spigot plugin-template which this was originally a fork of. I highly recommend their more minimalistic and much less opinionated template.
• A248: For exposing me to Flyway and jOOQ, inspiring me to include it in this template. I highly recommend you check out their projects LibertyBans & MorePaperLib which are of exceptional quality.