From c2c69a9c47b528c4e74781a3e8e4a8f21d0ebf81 Mon Sep 17 00:00:00 2001 From: Lukas Jost Date: Sun, 17 May 2026 17:20:20 +0200 Subject: [PATCH 1/5] docs: document runtime libraries --- build/gradle-plugin/setup.mdx | 15 ++++++++++ build/runtime-libraries.mdx | 54 +++++++++++++++++++++++++++++++++++ build/troubleshooting.mdx | 12 ++++++++ docs.json | 1 + 4 files changed, 82 insertions(+) create mode 100644 build/runtime-libraries.mdx diff --git a/build/gradle-plugin/setup.mdx b/build/gradle-plugin/setup.mdx index fcd02ea..58c207c 100644 --- a/build/gradle-plugin/setup.mdx +++ b/build/gradle-plugin/setup.mdx @@ -9,6 +9,21 @@ The `gg.grounds.push` Gradle plugin is what actually uploads your JAR to forge. `gg.grounds.push` is **separate** from the convention-plugin bundle (`gg.grounds.paper-conventions`, `gg.grounds.kotlin-conventions`, …). The conventions plugins shape your build; `push` ships its output. You almost certainly want both. +## Convention plugins + +Grounds plugin repositories use convention plugins from `library-gradle-plugin` to shape JVM plugin artifacts: + +- `gg.grounds.paper-conventions` +- `gg.grounds.velocity-conventions` +- `gg.grounds.paper-standalone-conventions` +- `gg.grounds.paper-runtime-consumer-conventions` +- `gg.grounds.paper-runtime-provider-conventions` +- `gg.grounds.velocity-standalone-conventions` +- `gg.grounds.velocity-runtime-consumer-conventions` +- `gg.grounds.velocity-runtime-provider-conventions` + +Runtime-consumer conventions are for internal Paper and Velocity plugins that run with [`plugin-grounds-runtime`](/build/runtime-libraries). Standalone conventions are for plugins that must carry their own runtime libraries. + ## Prerequisites - A GitHub personal access token with `read:packages` scope (the plugin lives on GitHub Packages). diff --git a/build/runtime-libraries.mdx b/build/runtime-libraries.mdx new file mode 100644 index 0000000..6145424 --- /dev/null +++ b/build/runtime-libraries.mdx @@ -0,0 +1,54 @@ +--- +title: "Runtime libraries" +description: "Share selected JVM libraries through plugin-grounds-runtime for Paper and Velocity plugins." +--- + +`plugin-grounds-runtime` is an internal Paper and Velocity plugin that provides selected shared JVM libraries to Grounds plugins at runtime. + +Runtime-consumer conventions automatically add baseline shared runtime libraries to the compile-only classpath. Plugin modules should not declare those libraries as implementation dependencies and must not bundle them in their shadow JARs. + +## When to use runtime consumers + +Use runtime-consumer conventions for internal Paper and Velocity plugins that run on Grounds base images and can require `plugin-grounds-runtime` in local, dev, test, and production environments. + +Use standalone conventions when a plugin must run without `plugin-grounds-runtime`. + +## Provided libraries + +- Kotlin standard library family +- Kotlin coroutines +- protobuf-java +- gRPC baseline modules + +## Not provided + +- Paper API +- Velocity API +- Minestom +- Plugin-specific clients such as NATS +- Jackson and other private implementation dependencies + +## Gradle convention IDs + +- `gg.grounds.paper-standalone-conventions` +- `gg.grounds.paper-runtime-consumer-conventions` +- `gg.grounds.paper-runtime-provider-conventions` +- `gg.grounds.velocity-standalone-conventions` +- `gg.grounds.velocity-runtime-consumer-conventions` +- `gg.grounds.velocity-runtime-provider-conventions` + +## Migrating a plugin + +1. Switch Paper or Velocity modules to runtime-consumer conventions. +2. Remove shared runtime libraries from `implementation`. +3. Keep plugin-private dependencies as `implementation`. +4. Keep test-only runtime requirements in `testImplementation`. +5. Add the loader dependency on `plugin-grounds-runtime`. +6. Build and inspect the final shadow JAR. +7. Run the plugin locally with the matching runtime plugin installed. + +## Debugging + +Run `/grounds-runtime` in Paper or Velocity to inspect the installed runtime version, platform, manifest source, and provided libraries. + +Runtime-consumer artifacts do not have a standalone fallback. Local, dev, test, and production environments must install the matching `plugin-grounds-runtime` plugin. diff --git a/build/troubleshooting.mdx b/build/troubleshooting.mdx index af86dd5..1da8a12 100644 --- a/build/troubleshooting.mdx +++ b/build/troubleshooting.mdx @@ -61,6 +61,18 @@ resources: Local mode only runs Paper and Velocity. Use `grounds push --target=dev` for `minestom` / `service` workloads. +### Runtime consumer starts without `plugin-grounds-runtime` + +Runtime-consumer artifacts do not have a standalone fallback. Install the matching `plugin-grounds-runtime` Paper or Velocity plugin in local, dev, test, and production environments. + +Use `/grounds-runtime` to confirm the runtime plugin is loaded and to inspect the runtime version, platform, manifest source, and provided libraries. + +### Runtime consumer bundles shared libraries + +Runtime-consumer builds fail when the final shadow JAR includes shared runtime packages such as `io/grpc`, `com/google/protobuf`, `kotlinx/coroutines`, or `kotlin`. + +Remove those libraries from `implementation` and rely on the runtime-consumer compile-only baseline. Keep plugin-private dependencies, such as NATS or Jackson, as `implementation`. If tests need a shared runtime library on the test runtime classpath, add it to `testImplementation`. + ### `unknown baseImage` Your manifest references a base image source key that Forge does not know, or that is not allowed for the selected `type`. diff --git a/docs.json b/docs.json index 04e0b38..782cd25 100644 --- a/docs.json +++ b/docs.json @@ -39,6 +39,7 @@ "build/concepts/targets", "build/concepts/pushes", "build/concepts/base-images", + "build/runtime-libraries", "build/concepts/preview-environments" ] }, From ee729fe638e5fef9dcd2f78c43b645a16faf63f6 Mon Sep 17 00:00:00 2001 From: Lukas Jost Date: Sun, 17 May 2026 17:54:03 +0200 Subject: [PATCH 2/5] docs: document runtime library catalog updates --- build/runtime-libraries.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/build/runtime-libraries.mdx b/build/runtime-libraries.mdx index 6145424..b4563df 100644 --- a/build/runtime-libraries.mdx +++ b/build/runtime-libraries.mdx @@ -20,6 +20,12 @@ Use standalone conventions when a plugin must run without `plugin-grounds-runtim - protobuf-java - gRPC baseline modules +## Updating runtime libraries + +Update shared runtime libraries in the runtime catalog used by `plugin-grounds-runtime`. The Paper and Velocity base images use `GROUNDS_RUNTIME_PLUGIN_VERSION` to download both the runtime plugin release asset and the `grounds-runtime-libraries.json` catalog from the matching Git tag, then generate `/opt/grounds/runtime-manifest.json` from that catalog during the image build. + +When a bundled runtime library changes, release `plugin-grounds-runtime` with the updated catalog before bumping `GROUNDS_RUNTIME_PLUGIN_VERSION` in `containers`. Do not duplicate the library list in Dockerfiles. + ## Not provided - Paper API From 3be0cda256f251948f35791517cb6e0e9f19f6cc Mon Sep 17 00:00:00 2001 From: Lukas Jost Date: Sun, 17 May 2026 18:31:36 +0200 Subject: [PATCH 3/5] docs: document runtime platform release flow --- build/runtime-libraries.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/build/runtime-libraries.mdx b/build/runtime-libraries.mdx index b4563df..cdfaff5 100644 --- a/build/runtime-libraries.mdx +++ b/build/runtime-libraries.mdx @@ -22,9 +22,15 @@ Use standalone conventions when a plugin must run without `plugin-grounds-runtim ## Updating runtime libraries -Update shared runtime libraries in the runtime catalog used by `plugin-grounds-runtime`. The Paper and Velocity base images use `GROUNDS_RUNTIME_PLUGIN_VERSION` to download both the runtime plugin release asset and the `grounds-runtime-libraries.json` catalog from the matching Git tag, then generate `/opt/grounds/runtime-manifest.json` from that catalog during the image build. +Update shared runtime libraries in `plugin-grounds-runtime`. That repository owns the runtime platform: -When a bundled runtime library changes, release `plugin-grounds-runtime` with the updated catalog before bumping `GROUNDS_RUNTIME_PLUGIN_VERSION` in `containers`. Do not duplicate the library list in Dockerfiles. +- Paper and Velocity runtime plugin artifacts +- `grounds-runtime-bom`, which pins the shared library versions +- `grounds-runtime-catalog`, which is used by base images to generate `/opt/grounds/runtime-manifest.json` + +Runtime-consumer Gradle conventions depend on `grounds-runtime-bom` through `groundsRuntime.runtimeVersion` or the `groundsRuntime.version` Gradle property. They keep shared libraries on the compile-only classpath without declaring versions in each plugin. + +When a bundled runtime library changes, release `plugin-grounds-runtime` first. Then bump `groundsRuntime.version` in consumer builds and `GROUNDS_RUNTIME_PLUGIN_VERSION` in `containers` to the same released version. Do not duplicate shared library versions in Dockerfiles or consumer plugin builds. ## Not provided From 85ddc63e0b8239b8d3de5ff3377eef968aac6cbe Mon Sep 17 00:00:00 2001 From: Lukas Jost Date: Sun, 17 May 2026 20:56:20 +0200 Subject: [PATCH 4/5] docs: explain shared runtime dependency updates --- build/runtime-libraries.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/build/runtime-libraries.mdx b/build/runtime-libraries.mdx index cdfaff5..f35392a 100644 --- a/build/runtime-libraries.mdx +++ b/build/runtime-libraries.mdx @@ -32,6 +32,22 @@ Runtime-consumer Gradle conventions depend on `grounds-runtime-bom` through `gro When a bundled runtime library changes, release `plugin-grounds-runtime` first. Then bump `groundsRuntime.version` in consumer builds and `GROUNDS_RUNTIME_PLUGIN_VERSION` in `containers` to the same released version. Do not duplicate shared library versions in Dockerfiles or consumer plugin builds. +## Adding a shared dependency + +Add a dependency to the shared runtime only when it is common runtime surface for multiple internal Paper or Velocity plugins. Keep plugin-private clients, app-specific libraries, and test-only libraries in the consumer plugin build. + +1. Add or update the dependency in `plugin-grounds-runtime` under `runtime-catalog/grounds-runtime-libraries.json`. +2. If the dependency exposes packages that can conflict with server or plugin classpaths, update the runtime relocation policy and consumer shadow exclusions. +3. If this is a version-only update, release `plugin-grounds-runtime` and bump consumer `groundsRuntime.version`. +4. If this adds or removes a module, also update `library-gradle-plugin` so the runtime-consumer conventions add the versionless dependency and validate the correct package prefixes. +5. Release `plugin-grounds-runtime` before `library-gradle-plugin`, consumer plugins, and `containers`. + +The split is intentional: + +- `plugin-grounds-runtime` owns versions through `grounds-runtime-bom`. +- `library-gradle-plugin` owns build policy: which modules are added, what gets relocated, and what must not be bundled by runtime consumers. +- `containers` owns installation of the released runtime plugin and matching catalog. + ## Not provided - Paper API From 20919eb3ba9c8d43ac8db6b35b5852f334c174a2 Mon Sep 17 00:00:00 2001 From: Lukas Jost Date: Mon, 18 May 2026 10:27:34 +0200 Subject: [PATCH 5/5] docs: move runtime libraries under convention plugins --- build/gradle-plugin/setup.mdx | 2 +- docs.json | 4 ++-- .../development/gradle-plugin}/runtime-libraries.mdx | 0 3 files changed, 3 insertions(+), 3 deletions(-) rename {build => reference/development/gradle-plugin}/runtime-libraries.mdx (100%) diff --git a/build/gradle-plugin/setup.mdx b/build/gradle-plugin/setup.mdx index 58c207c..6fd25e3 100644 --- a/build/gradle-plugin/setup.mdx +++ b/build/gradle-plugin/setup.mdx @@ -22,7 +22,7 @@ Grounds plugin repositories use convention plugins from `library-gradle-plugin` - `gg.grounds.velocity-runtime-consumer-conventions` - `gg.grounds.velocity-runtime-provider-conventions` -Runtime-consumer conventions are for internal Paper and Velocity plugins that run with [`plugin-grounds-runtime`](/build/runtime-libraries). Standalone conventions are for plugins that must carry their own runtime libraries. +Runtime-consumer conventions are for internal Paper and Velocity plugins that run with [`plugin-grounds-runtime`](/reference/development/gradle-plugin/runtime-libraries). Standalone conventions are for plugins that must carry their own runtime libraries. ## Prerequisites diff --git a/docs.json b/docs.json index 782cd25..76ea2bc 100644 --- a/docs.json +++ b/docs.json @@ -39,7 +39,6 @@ "build/concepts/targets", "build/concepts/pushes", "build/concepts/base-images", - "build/runtime-libraries", "build/concepts/preview-environments" ] }, @@ -161,7 +160,8 @@ "group": "Convention plugins", "pages": [ "reference/development/gradle-plugin/index", - "reference/development/gradle-plugin/usage" + "reference/development/gradle-plugin/usage", + "reference/development/gradle-plugin/runtime-libraries" ] }, { diff --git a/build/runtime-libraries.mdx b/reference/development/gradle-plugin/runtime-libraries.mdx similarity index 100% rename from build/runtime-libraries.mdx rename to reference/development/gradle-plugin/runtime-libraries.mdx