> ## Documentation Index
> Fetch the complete documentation index at: https://grounds-docs-platform-architecture.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Step-by-step guide to install and configure the Gradle plugin bundle

The plugins are published to GitHub Packages. To use them, you need to configure your project to access the GitHub Packages Maven repository.

<Info>
  **Prerequisites**:

  * Gradle 7.0 or higher
  * A GitHub account with access to the `groundsgg` organization
  * A GitHub personal access token with `read:packages` permission
</Info>

Follow these steps to install and configure the Gradle plugin bundle.

<Steps>
  <Step title="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

    <Warning>
      Store your token securely. You won't be able to see it again after leaving the page.
    </Warning>
  </Step>

  <Step title="Configure Gradle Properties">
    Add your GitHub credentials to `~/.gradle/gradle.properties`:

    ```properties ~/.gradle/gradle.properties theme={null}
    github.user=your-github-username
    github.token=your-personal-access-token
    ```
  </Step>

  <Step title="Configure Plugin Management">
    Add the GitHub Packages repository to your `pluginManagement` block in `settings.gradle.kts`:

    ```kotlin settings.gradle.kts theme={null}
    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()
        }
    }
    ```

    <Note>
      The `gradlePluginPortal()` should remain in the repositories list to allow Gradle to resolve other plugins from the Gradle Plugin Portal.
    </Note>
  </Step>

  <Step title="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):

    ```kotlin build.gradle.kts theme={null}
    plugins {
        id("gg.grounds.base-conventions") version "0.3.0"
    }
    ```

    ### Kotlin Conventions

    For Kotlin projects (typically shared/common modules):

    ```kotlin build.gradle.kts theme={null}
    plugins {
        id("gg.grounds.kotlin-conventions")
    }
    ```

    ### Paper Conventions

    For Paper server plugin projects:

    ```kotlin build.gradle.kts theme={null}
    plugins {
        id("gg.grounds.paper-conventions")
    }
    ```

    ### Velocity Conventions

    For Velocity proxy plugin projects:

    ```kotlin build.gradle.kts theme={null}
    plugins {
        id("gg.grounds.velocity-conventions")
    }
    ```

    ### Minestom Conventions

    For Minestom server plugin projects:

    ```kotlin build.gradle.kts theme={null}
    plugins {
        id("gg.grounds.minestom-conventions")
    }
    ```

    ### gRPC Conventions

    For gRPC projects:

    ```kotlin build.gradle.kts theme={null}
    plugins {
        id("gg.grounds.grpc-conventions")
    }
    ```
  </Step>

  <Step title="Verify Installation">
    Verify the plugin is correctly installed by running:

    ```bash theme={null}
    ./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.
  </Step>
</Steps>

## 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`

```kotlin theme={null}
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:

```kotlin settings.gradle.kts theme={null}
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`:

```kotlin build.gradle.kts theme={null}
plugins {
    id("gg.grounds.base-conventions") version "0.3.0"
}
```

And apply specific conventions in each subproject's `build.gradle.kts`:

```kotlin paper-plugin/build.gradle.kts theme={null}
plugins {
    id("gg.grounds.paper-conventions")
}
```

```kotlin velocity-plugin/build.gradle.kts theme={null}
plugins {
    id("gg.grounds.velocity-conventions")
}
```

```kotlin grpc-module/build.gradle.kts theme={null}
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](https://github.com/orgs/groundsgg/packages?repo_name=library-gradle-plugin) for available versions)

### Version Updates

To update to a newer version, change the version number only on `gg.grounds.base-conventions`:

```kotlin build.gradle.kts theme={null}
plugins {
    id("gg.grounds.base-conventions") version "0.3.0" // Update this version
}
```

Check the [GitHub repository releases](https://github.com/groundsgg/library-gradle-plugin/releases) for the latest version.