Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/crimsonwarpedcraft/plugin-template
A template for building PaperMC Minecraft server plugins
https://github.com/crimsonwarpedcraft/plugin-template
checkstyle dependabot gitops gradle issue-templates java junit5 minecraft papermc shadowjar spotbugs stale-bot workflows
Last synced: 3 months ago
JSON representation
A template for building PaperMC Minecraft server plugins
- Host: GitHub
- URL: https://github.com/crimsonwarpedcraft/plugin-template
- Owner: CrimsonWarpedcraft
- License: gpl-3.0
- Created: 2020-07-29T06:30:00.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-09-22T08:33:35.000Z (4 months ago)
- Last Synced: 2024-09-28T12:02:35.086Z (4 months ago)
- Topics: checkstyle, dependabot, gitops, gradle, issue-templates, java, junit5, minecraft, papermc, shadowjar, spotbugs, stale-bot, workflows
- Language: Java
- Homepage:
- Size: 640 KB
- Stars: 36
- Watchers: 2
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# PaperMC/Spigot Minecraft Server Plugin Template
A template for building PaperMC/Spigot Minecraft server plugins!
[](https://github.com/CrimsonWarpedcraft/plugin-template/actions/workflows/main.yml)
[](https://discord.gg/5XMmeV6EtJ)
## Features
### Github Actions 🎬
* Automated builds, testing, and release drafting
* [Discord notifcations](https://github.com/marketplace/actions/discord-message-notify) for snapshots and releases
### Bots 🤖
* **Probot: Stale**
* Mark issues stale after 30 days
* **Dependabot**
* Update GitHub Actions workflows
* Update Gradle dependencies
### Issue Templates 📋
* Bug report template
* Feature request template
### Gradle Builds 🏗
* Shadowed [PaperLib](https://github.com/PaperMC/PaperLib) build
* [Checkstyle](https://checkstyle.org/) Google standard style check
* [SpotBugs](https://spotbugs.github.io/) code analysis
* [JUnit](https://junit.org/) testing
### Config Files 📁
* Sample plugin.yml with autofill name, version, and main class.
* Empty config.yml (just to make life \*that\* much easier)
* Gradle build config
* Simple .gitignore for common Gradle files
## Usage
In order to use this template for yourself, there are a few things that you will need to keep in mind.
### Release Info
#### PaperMC Version Mapping
Here's a list of the PaperMC versions and the versions of this latest compatible version.
| PaperMC | ExamplePlugin |
|---------|---------------|
| 1.21.1 | 3.12.2+ |
| 1.21 | 3.12.0 |
| 1.20.6 | 3.11.0 |
| 1.20.4 | 3.9.3 |
| 1.20.2 | 3.8.4 |
| 1.20.1 | 3.7.1 |
| 1.19.4 | 3.2.1 |
| 1.18.2 | 3.0.2 |
| 1.17.1 | 2.2.0 |
| 1.16.5 | 2.1.2 |
This chart would make more sense if this plugin actually did anything and people would have a reason
to be looking for older releases to run on older servers.
To use this as a template, just use the latest version of this project and update the PaperMC
version as needed. See more info on release stability below.
#### Release and Versioning Strategy
Stable versions of this repo are tagged `vX.Y.Z` and have an associated [release](https://github.com/CrimsonWarpedcraft/plugin-template/releases).
Testing versions of this repo are tagged `vX.Y.Z-RC-N` and have an associated [pre-release](https://github.com/CrimsonWarpedcraft/plugin-template/releases).
Development versions of this repo are pushed to the master branch and are **not** tagged.
| Event | Plugin Version Format | CI Action | GitHub Release Draft? |
|-------------------|-----------------------|----------------------------------|-----------------------|
| PR | yyMMdd-HHmm-SNAPSHOT | Build and test | No |
| Cron | yyMMdd-HHmm-SNAPSHOT | Build, test, and notify | No |
| Push to `main` | 0.0.0-SNAPSHOT | Build, test, release, and notify | No |
| Tag `vX.Y.Z-RC-N` | X.Y.Z-SNAPSHOT | Build, test, release, and notify | Pre-release |
| Tag `vX.Y.Z` | X.Y.Z | Build, test, release, and notify | Release |
### Discord Notifications
In order to use Discord notifications, you will need to create two GitHub secrets. `DISCORD_WEBHOOK_ID`
should be set to the id of your Discord webhook. `DISCORD_WEBHOOK_TOKEN` will be the token for the webhook.
You can find these values by copying the Discord Webhook URL:
`https://discord.com/api/webhooks//`
Optionally, you can also configure `DISCORD_RELEASE_WEBHOOK_ID` and `DISCORD_RELEASE_WEBHOOK_TOKEN`
to send release announcements to a separate channel.
For more information, see [Discord Message Notify](https://github.com/marketplace/actions/discord-message-notify).
---
**I've broken the rest of the changes up by their files to make things a bit easier to find.**
---
### settings.gradle
Update the line below with the name of your plugin.
```groovy
rootProject.name = 'ExamplePlugin'
```
### build.gradle
Make sure to update the `group` to your package's name in the following section.
```groovy
group = "com.crimsonwarpedcraft.exampleplugin"
```
Add any required repositories for your dependencies in the following section.
```groovy
repositories {
maven {
name 'papermc'
url 'https://papermc.io/repo/repository/maven-public/'
content {
includeModule("io.papermc.paper", "paper-api")
includeModule("io.papermc", "paperlib")
includeModule("net.md-5", "bungeecord-chat")
}
}
mavenCentral()
}
```
Also, update your dependencies as needed (of course).
```groovy
dependencies {
compileOnly 'io.papermc.paper:paper-api:1.20.1-R0.1-SNAPSHOT'
compileOnly 'com.github.spotbugs:spotbugs-annotations:4.7.3'
implementation 'io.papermc:paperlib:1.0.8'
spotbugsPlugins 'com.h3xstream.findsecbugs:findsecbugs-plugin:1.12.0'
testCompileOnly 'com.github.spotbugs:spotbugs-annotations:4.7.3'
testImplementation 'io.papermc.paper:paper-api:1.20.1-R0.1-SNAPSHOT'
testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.0'
testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.10.0'
}
```
### src/main/resources/plugin.yml
First, update the following with your information.
```yaml
author: AUTHOR
description: DESCRIPTION
```
Next, the `commands` and `permissions` sections below should be updated as needed.
```yaml
commands:
ex:
description: Base command for EXAMPLE
usage: "For a list of commands, type /ex help"
aliases: example
permissions:
example.test:
description: DESCRIPTION
default: true
example.*:
description: Grants all other permissions
default: false
children:
example.test: true
```
### .github/dependabot.yml
You will need to replace all instances of `leviem1`, such as the one below, with your GitHub
username.
```yaml
reviewers:
- "leviem1"
```
### .github/CODEOWNERS
You will need to replace `leviem1`, with your GitHub username.
```text
* @leviem1
```
### .github/FUNDING.yml
Update or delete this file, whatever applies to you.
```yaml
github: leviem1
```
For more information see: [Displaying a sponsor button in your repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository)
### CODE_OF_CONDUCT.md
If you chose to adopt a Code of Conduct for your project, please update line 63 with your preferred
contact method.
## Creating a Release
Below are the steps you should follow to create a release.
1. Create a tag on `main` using semantic versioning (e.g. v0.1.0)
2. Push the tag and get some coffee while the workflows run
3. Publish the release draft once it's been automatically created
## Building locally
Thanks to [Gradle](https://gradle.org/), building locally is easy no matter what platform you're on. Simply run the following command:
```text
./gradlew build
```
This build step will also run all checks and tests, making sure your code is clean.
JARs can be found in `build/libs/`.
## Contributing
See [CONTRIBUTING.md](https://github.com/CrimsonWarpedcraft/plugin-template/blob/main/CONTRIBUTING.md).
---
I think that's all... phew! Oh, and update this README! ;)