Skip to main content
grounds-minestom-runtime is the process-level runtime for Minestom-based Grounds servers. It lets you compose a lobby or minigame from normal Gradle dependencies, select explicit runtime modules, and push the resulting distribution through Grounds. Minestom does not have a Paper-style plugin folder. A Minestom server is a JVM application that embeds Minestom and every module it needs. Grounds follows that model: build the server at compile time, publish one immutable distribution, then let Forge build and deploy the image.
The runtime is not a hot plugin system. It discovers providers from the application classpath and starts only the providers your server selects.

​
What the runtime provides

  • module lifecycle hooks with install, start, and stop;
  • GroundsServerContext with server type, runtime environment, shutdown hooks, and typed services;
  • provider discovery through Java ServiceLoader;
  • explicit provider selection through useProvider("module.id");
  • module descriptor validation, service dependency ordering, and server type filtering;
  • Minestom bootstrap and clean shutdown orchestration.

​
When to use it

Use the runtime for Minestom servers that need reusable Grounds integrations such as Agones, config, permissions, matchmaking, or shared services. Do not use it when you only need a small standalone Minestom experiment with no reusable modules. Plain Minestom code still works; the runtime exists to make composed Grounds servers reproducible.

​
Typical shape

my-minigame/
  settings.gradle.kts
  build.gradle.kts
  grounds.yaml
  server/
    build.gradle.kts
    src/main/kotlin/example/Main.kt
The Gradle app depends on released module artifacts:
server/build.gradle.kts
dependencies {
    implementation("gg.grounds:grounds-minestom-runtime-runtime-core:<version>")
    runtimeOnly("gg.grounds:plugin-agones-minestom:0.6.0")
}
The server entrypoint selects the modules it wants: 
import gg.grounds.runtime.core.GroundsServer

fun main() {
    GroundsServer.builder()
        .discoverProviders()
        .useProvider("grounds.agones")
        .start()
}
The project pushes a distribution tar:
grounds.yaml
name: minigame-agones
type: minestom-server
baseImage: minestom
build:
  task: :server:distTar
  artifact: server/build/distributions/*.tar
modules:
  - id: plugin-agones
    variant: minestom
    source: github:groundsgg/plugin-agones@v0.6.0:plugin-agones-minestom.jar

​
Start here

Runtime modules

Define GroundsModule and GroundsModuleProvider implementations with descriptors and typed service contracts.

Runtime composition

Discover providers, select module IDs, and understand validation and startup behavior.

Local modules

Replace release module dependencies with local repositories during grounds push.

Manifest reference

See the grounds.yaml fields used for Minestom distribution pushes.