Skip to main content
The plugins are published to GitHub Packages. To use them, you need to configure your project to access the GitHub Packages Maven repository.
Prerequisites:
  • Gradle 7.0 or higher
  • A GitHub account with access to the groundsgg organization
  • A GitHub personal access token with read:packages permission
Follow these steps to install and configure the Gradle plugin bundle.
1

Create GitHub Personal Access Token

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click “Generate new token (classic)”
  3. Give it a descriptive name (e.g., “Gradle Packages Access”)
  4. Select the read:packages scope
  5. Generate the token and copy it immediately
Store your token securely. You won’t be able to see it again after leaving the page.
2

Configure Gradle Properties

Add your GitHub credentials to ~/.gradle/gradle.properties:
~/.gradle/gradle.properties
github.user=your-github-username
github.token=your-personal-access-token
3

Configure Plugin Management

Add the GitHub Packages repository to your pluginManagement block in settings.gradle.kts:
settings.gradle.kts
pluginManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/groundsgg/*")
            credentials {
                username = providers.gradleProperty("github.user").get()
                password = providers.gradleProperty("github.token").get()
            }
        }
        gradlePluginPortal()
    }
}
The gradlePluginPortal() should remain in the repositories list to allow Gradle to resolve other plugins from the Gradle Plugin Portal.
4

Apply the Plugin

Apply the base conventions plugin with a version, then add the conventions that match your project type:

​
Base Conventions (required)

Apply once per project (usually in the root project):
build.gradle.kts
plugins {
    id("gg.grounds.base-conventions") version "0.3.0"
}

​
Kotlin Conventions

For Kotlin projects (typically shared/common modules):
build.gradle.kts
plugins {
    id("gg.grounds.kotlin-conventions")
}

​
Paper Conventions

For Paper server plugin projects:
build.gradle.kts
plugins {
    id("gg.grounds.paper-conventions")
}

​
Velocity Conventions

For Velocity proxy plugin projects:
build.gradle.kts
plugins {
    id("gg.grounds.velocity-conventions")
}

​
Minestom Conventions

For Minestom server plugin projects:
build.gradle.kts
plugins {
    id("gg.grounds.minestom-conventions")
}

​
gRPC Conventions

For gRPC projects:
build.gradle.kts
plugins {
    id("gg.grounds.grpc-conventions")
}
5

Verify Installation

Verify the plugin is correctly installed by running:
./gradlew tasks --all
You should see tasks provided by the plugin in the output. For example, with base conventions, you’ll see Spotless formatting tasks.

​
Overriding Paper, Velocity, or Minestom Versions

Your project can request a higher Paper, Velocity, or Minestom version by declaring it in dependencies. Lower versions are not supported.
  • Current Paper version: 1.21.11-R0.1-SNAPSHOT
  • Current Velocity version: 3.4.0-SNAPSHOT
  • Current Minestom version: 2026.01.08-1.21.11
dependencies {
    // Overrides the Paper version with a higher one
    compileOnly("io.papermc.paper:paper-api:1.21.12-R0.1-SNAPSHOT")
}

​
Multi-Module Projects

For projects with multiple modules, configure the plugin management at the root level:
settings.gradle.kts
pluginManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/groundsgg/*")
            credentials {
                username = providers.gradleProperty("github.user").get()
                password = providers.gradleProperty("github.token").get()
            }
        }
        gradlePluginPortal()
    }
}

rootProject.name = "my-project"
include("paper-plugin", "velocity-plugin")
Then apply the base conventions in the root build.gradle.kts:
build.gradle.kts
plugins {
    id("gg.grounds.base-conventions") version "0.3.0"
}
And apply specific conventions in each subproject’s build.gradle.kts:
paper-plugin/build.gradle.kts
plugins {
    id("gg.grounds.paper-conventions")
}
velocity-plugin/build.gradle.kts
plugins {
    id("gg.grounds.velocity-conventions")
}
grpc-module/build.gradle.kts
plugins {
    id("gg.grounds.grpc-conventions")
}
When a module uses the Paper or Velocity conventions, the shared shaded-plugin packaging relocates com.google.protobuf to gg.grounds.shaded.protobuf in the final jar. That keeps bundled protobuf classes isolated from the server runtime while leaving plain library modules unchanged.

​
Troubleshooting

​
Authentication Errors

If you encounter authentication errors:
  1. Verify your GitHub token has read:packages permission
  2. Check that github.user and github.token are correctly set in your Gradle properties
  3. Ensure the token hasn’t expired

​
Plugin Not Found

If Gradle cannot find the plugin:
  1. Verify the repository URL is correct: https://maven.pkg.github.com/groundsgg/*
  2. Check that gradlePluginPortal() is included in the repositories list
  3. Ensure you’re using the correct plugin version (check GitHub Packages for available versions)

​
Version Updates

To update to a newer version, change the version number only on gg.grounds.base-conventions:
build.gradle.kts
plugins {
    id("gg.grounds.base-conventions") version "0.3.0" // Update this version
}
Check the GitHub repository releases for the latest version.