Spigot Plugin Template
You can use this template to develop your own high quality Spigot plugins using Gradle with ease.
- Features
- Quickstart setup
- Releasing a new version of your plugin
- Publishing your maven package
- Debugging your plugin
- References
Features
The template or better boilerplate comes with a lot of features that are useful if you want to develop high quality plugins. However you don't need to use all of them, you can simply remove the features you don't need.
- Ready to use Gradle project with lots of utility tasks
- Automatic generation of
plugin.yamlbased of project properties with SpiGradle - Integrated Spigot test server with a one click build, copy plugin and start debugging in IntelliJ task
- Gradle shadow plugin to easily ship your needed dependencies with your plugin
- JUnit 5 test setup including MockBukkit and AssertJ
- Jacoco code coverage report including an upload task to codecov
- Fully integrated semantic-release release pipeline
- Automatic changelog generation based on conventional commit messages
- Github Actions workflow for build and release
- Publishing of maven artifacts to GitHub Packages
no more need for self hosted nexus or artifactory server
- GitHub issue templates for bug and feature requests
- Contributing and Code of Conduct guidelines
- Nice badges to show of your project
Quickstart setup
- Create a new Github project using this template.
- Clone the new repository and open it in IntelliJ.
- Update the gradle.properties file and change the following variables:
group: your-maven-group-id (e.g.: io.github.silthus)pluginName: YourPluginNameauthor: YourName
- Update the
root.projectNameinside settings.gradle. This will be yourartifactId. - Delete the
CHANGELOG.md. It will be generated on your first release. - Update the
READMEto point to your project and spigot resource id. - Rename the java package and plugin to match your project.
- Then execute the
Serverrun configuration and the template will run the Spigot BuildTools to download and build spigot or paper for you. - Code away :) - and once you are ready, push your commit (in conventional commit style) to master.
Please read the Contributing Guidelines before submitting any pull requests or opening issues.
Releasing a new version of your plugin
One of the major benefits of this template is the fact that it will automatically release a new version on every push to master based on your commit messages. This makes sure your plugin is released following the semantic versioning guidelines. For this to work you have to follow a few simple rules:
- Commit only working and tested code to the master branch. Use Pull Requests to work on bigger features or bug fixes and merge them when you are ready.
- Every bugfix, feature and change should have one commit associated with it. Do not mix multiple bugs, features, etc. into one huge commit message. Keep your commit size small and commit often.
- Your commit messages must follow the conventional commit rules.
Commit message format
See the conventional commit homepage for more details and examples on the topic. But here is a quick summary to get you started.
The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
The commit message should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
The commit contains the following structural elements, to communicate intent to the consumers of your library or plugin:
fix:a commit of the type fix patches a bug in your codebase (this correlates with PATCH in semantic versioning).feat:a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in semantic versioning).BREAKING CHANGE:a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in semantic versioning). A BREAKING CHANGE can be part of commits of any type.- types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the the Angular convention) recommends
build:,chore:,ci:,docs:,style:,refactor:,perf:,test:, and others. - footers other than
BREAKING CHANGE: <description>may be provided and follow a convention similar to git trailer format. Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE).
A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays.
Here are some examples:
Commit message with description and breaking change footer
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
Commit message with no body
docs: correct spelling of CHANGELOG
Commit message with scope
feat(lang): add polish language
Commit message with multi-paragraph body and multiple footers
fix: correct minor typos in code
see the issue for details
on typos fixed.
Reviewed-by: Z
Refs #133
Publishing your maven package
Your plugin will be automatically published as a maven package on Github packages as soon as you release a new version.
About the group and artifactId
The group appended by your artifactId is used to uniquely identify your project when importing it in other projects. When you import spigot in your project you use the group org.spigotmc followed by the artifactId spigot-api and the version.
The following was taken from the offical maven naming guide.
groupIduniquely identifies your project across all projects. A group ID should follow Java's package name rules. This means it starts with a reversed domain name you control. For example:org.apache.maven,org.apache.commons.
If you dont't own a domain, you can use the github domainio.githubappended by your Github username, e.g.io.github.silthusartifactIdis the name of the jar without version. If you created it, then you can choose whatever name you want with lowercase letters and no strange symbols. For example: `maven, commons-math
Github Package Authentication
You need to configure authentication for Github Packages if you want to use your maven package in other projects.
- Create a Github Personal Access Token
- Create or update the
gradle.propertiesinsideC:\Users\%username%\.gradlewith the following and replaceYOUR_GITHUB_USERNAMEwith your Github username andYOUR_PERSONAL_ACCESS_TOKENwith the access token from step 1.
gpr.user=YOUR_GITHUB_USERNAME
gpr.key=YOUR_PERSONAL_ACCESS_TOKEN
Debugging your plugin
Copy your plugin automatically
You can export your plugin to the plugins directory from your working directory with the Gradle prepareSpigotPlugins task. The task will build and copy your plugin automatically into the plugins/ directory.
Running and debugging the Minecraft server
You can run or debug your plugin using the Server run configuration from within IntelliJ to automatically download the Minecraft server, built it, copy your and dependent plugins into it and start it in debugging mode.
This is due to the awesome power of Spigradle's debug tasks. Find out more on the Spigradle Github page.
References
- Spigradle: provides awesome gradle tasks that make your live a lot easier
- semantic-release: in my opinion every project should use this!
- conventional commit messages: do commit message the right way
9 Jun 6, 2022
11 Dec 18, 2022
4 Jan 30, 2022
3 Nov 12, 2022
8 Jan 30, 2022
0 Apr 29, 2022
7 Dec 25, 2022
3 Oct 2, 2021
32 Dec 1, 2022
2 Jan 2, 2022
16 Dec 2, 2022
3 Sep 18, 2022
12 Apr 18, 2022
6 Aug 30, 2022
56 Dec 28, 2022
110 May 25, 2022
9 Nov 21, 2022
1 Jan 13, 2022