diff --git a/tools/gradle-plugin/index.mdx b/tools/gradle-plugin/index.mdx index 0f3275a..f0cc810 100644 --- a/tools/gradle-plugin/index.mdx +++ b/tools/gradle-plugin/index.mdx @@ -3,7 +3,7 @@ title: "Overview" description: "Gradle plugin bundle providing standardized build configurations for Grounds projects" --- -The `library-gradle-plugin` is a Gradle plugin bundle that provides standardized build configurations for Grounds projects. It consolidates common setup tasks, dependency management, and build configurations to ensure consistency across all Grounds projects while reducing boilerplate configuration. +The `library-gradle-plugin` is a Gradle convention plugin bundle that provides standardized build configurations for Grounds projects. It consolidates common setup tasks, dependency management, and build configurations to ensure consistency across all Grounds projects while reducing boilerplate configuration. ## Quick Links @@ -22,34 +22,64 @@ The `library-gradle-plugin` is a Gradle plugin bundle that provides standardized To get started with the Gradle plugin bundle: 1. [Install the plugins](/tools/gradle-plugin/usage) in your project -2. Choose the appropriate plugin for your project type: - - Use Root Plugin for shared repository configuration - - Use Paper Plugin for Paper server plugins - - Use Velocity Plugin for Velocity proxy plugins +2. Apply the base conventions plugin with a version +3. Add the project-specific conventions (Paper, Velocity, Minestom, gRPC) as needed ## Functionality -The plugin bundle consists of three main plugins, each providing specific functionality: +The plugin bundle consists of convention plugins, each providing specific functionality: -### Root Plugin (`gg.grounds.root`) +## Plugin Structure -- Applies standard plugins (maven-publish, Kotlin JVM, Kapt, Spotless) +The convention plugins build on each other. Base conventions sit at the bottom, Kotlin conventions add publishing, and the platform-specific conventions layer on top. + +```mermaid +graph TB + kotlin["kotlin-conventions"] --> base["base-conventions"] + minestom["minestom-conventions"] --> kotlin + paperbase["paper-base-conventions"] --> kotlin + grpc["grpc-conventions"] --> kotlin + paper["paper-conventions"] --> paperbase + velocity["velocity-conventions"] --> paperbase +``` + +### Base Conventions (`gg.grounds.base-conventions`) + +- Applies standard plugins (Kotlin JVM, Kapt, Spotless) - Code formatting with Spotless (ktfmt, Google Style, 4-space indentation) -- Configures Maven Central repository for all projects -- Automatic Kotlin project configuration (Group: gg.grounds, version management, JVM Toolchain 25) +- Configures Maven Central repository +- Kotlin + Java toolchain configuration (JVM 25, Java 24) +- Group/version defaults with optional `versionOverride` property - JUnit Platform for tests with full exception output + +### Kotlin Conventions (`gg.grounds.kotlin-conventions`) + - Maven publishing to GitHub Packages +- Maven publication naming for root and subprojects -### Paper Plugin (`gg.grounds.paper`) +### Paper Base Conventions (`gg.grounds.paper-base-conventions`) - Adds Paper repository - Shadow packaging configuration (Fat JAR) -- Optional Paper API dependency (configurable via extension) -- Automatic version replacement in plugin.yml +- Disables default `jar` task and wires `shadowJar` into `build` +- Standardized Shadow JAR naming -### Velocity Plugin (`gg.grounds.velocity`) +### Paper Conventions (`gg.grounds.paper-conventions`) + +- Paper API dependency (compileOnly) +- Automatic version replacement in `plugin.yml` + +### Velocity Conventions (`gg.grounds.velocity-conventions`) -- Adds Paper repository -- Shadow packaging configuration (Fat JAR) - Optional Velocity API dependencies (compileOnly and kapt) -- Automatic generation of BuildInfo class with version for dynamic plugin versioning +- Automatic generation of `BuildInfo` class with version for dynamic plugin versioning + +### Minestom Conventions (`gg.grounds.minestom-conventions`) + +- Minestom dependency +- JVM target attribute pinned to 25 for resolved configurations + +### gRPC Conventions (`gg.grounds.grpc-conventions`) + +- Protobuf + gRPC dependencies +- Protobuf code generation with gRPC plugin diff --git a/tools/gradle-plugin/usage.mdx b/tools/gradle-plugin/usage.mdx index 32f412e..b16ba9a 100644 --- a/tools/gradle-plugin/usage.mdx +++ b/tools/gradle-plugin/usage.mdx @@ -59,35 +59,65 @@ The `gradlePluginPortal()` should remain in the repositories list to allow Gradl ## Step 4: Apply the Plugin -Apply the appropriate plugin in your `build.gradle.kts` file based on your project type: +Apply the base conventions plugin with a version, then add the conventions that match your project type: -### Root Plugin +### Base Conventions (required) -For root projects or shared configurations: +Apply once per project (usually in the root project): ```kotlin build.gradle.kts plugins { - id("gg.grounds.root") version "0.1.1" + id("gg.grounds.base-conventions") version "0.3.0" } ``` -### Paper Plugin +### Kotlin Conventions + +For Kotlin projects (typically shared/common modules): + +```kotlin build.gradle.kts +plugins { + id("gg.grounds.kotlin-conventions") +} +``` + +### Paper Conventions For Paper server plugin projects: ```kotlin build.gradle.kts plugins { - id("gg.grounds.paper") version "0.1.1" + id("gg.grounds.paper-conventions") } ``` -### Velocity Plugin +### Velocity Conventions For Velocity proxy plugin projects: ```kotlin build.gradle.kts plugins { - id("gg.grounds.velocity") version "0.1.1" + id("gg.grounds.velocity-conventions") +} +``` + +### Minestom Conventions + +For Minestom server plugin projects: + +```kotlin build.gradle.kts +plugins { + id("gg.grounds.minestom-conventions") +} +``` + +### gRPC Conventions + +For gRPC projects: + +```kotlin build.gradle.kts +plugins { + id("gg.grounds.grpc-conventions") } ``` @@ -99,7 +129,22 @@ 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 the root plugin, you'll see Spotless formatting tasks. +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` + +```kotlin +dependencies { + // Overrides the Paper version with a higher one + compileOnly("io.papermc.paper:paper-api:1.21.12-R0.1-SNAPSHOT") +} +``` ## Multi-Module Projects @@ -123,25 +168,31 @@ rootProject.name = "my-project" include("paper-plugin", "velocity-plugin") ``` -Then apply the root plugin in the root `build.gradle.kts`: +Then apply the base conventions in the root `build.gradle.kts`: ```kotlin build.gradle.kts plugins { - id("gg.grounds.root") version "0.1.1" + id("gg.grounds.base-conventions") version "0.3.0" } ``` -And apply specific plugins in each subproject's `build.gradle.kts`: +And apply specific conventions in each subproject's `build.gradle.kts`: ```kotlin paper-plugin/build.gradle.kts plugins { - id("gg.grounds.paper") version "0.1.1" + id("gg.grounds.paper-conventions") } ``` ```kotlin velocity-plugin/build.gradle.kts plugins { - id("gg.grounds.velocity") version "0.1.1" + id("gg.grounds.velocity-conventions") +} +``` + +```kotlin grpc-module/build.gradle.kts +plugins { + id("gg.grounds.grpc-conventions") } ``` @@ -165,11 +216,11 @@ If Gradle cannot find the plugin: ### Version Updates -To update to a newer version, change the version number in your `build.gradle.kts`: +To update to a newer version, change the version number only on `gg.grounds.base-conventions`: ```kotlin build.gradle.kts plugins { - id("gg.grounds.root") version "0.1.1" // Update this version + id("gg.grounds.base-conventions") version "0.3.0" // Update this version } ```