Runtime libraries

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

Updating runtime libraries

Update shared runtime libraries in plugin-grounds-runtime. That repository owns the runtime platform:

• 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.

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
• 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.