Minestom

Use the Minestom module of plugin-agones when your gamemode runs on Minestom. Unlike Paper, Minestom has no plugin loader. Runtime-based servers discover the module from the classpath and select its grounds.agones provider during GroundsServer composition. Once started, the library syncs Agones state from Minestom’s player events the same way the Paper build does: the first player switches the gameserver to Allocated, the last one returning to Ready.

Requirements

Your Minestom pod must run with an Agones sidecar exposing the SDK on http://localhost:9358. The Grounds container images configure this by default.

The module targets Minestom 2026.03.03-1.21.11 and newer. It uses an internal coroutine scope for the sidecar calls, so you do not need to provide an executor.

Add the Dependency

The module is published to the groundsgg GitHub Packages Maven registry as gg.grounds:plugin-agones-minestom.

Gradle Kotlin DSL
Gradle Groovy DSL

build.gradle.kts

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/groundsgg/*")
        credentials {
            username = providers.gradleProperty("github.user").get()
            password = providers.gradleProperty("github.token").get()
        }
    }
}

dependencies {
    implementation("gg.grounds:grounds-minestom-runtime-runtime-core:0.4.0")
    runtimeOnly("gg.grounds:plugin-agones-minestom:0.6.0")
}

build.gradle

repositories {
    maven {
        url "https://maven.pkg.github.com/groundsgg/*"
        credentials {
            username = providers.gradleProperty('github.user').get()
            password = providers.gradleProperty('github.token').get()
        }
    }
}

dependencies {
    implementation "gg.grounds:grounds-minestom-runtime-runtime-core:0.4.0"
    runtimeOnly "gg.grounds:plugin-agones-minestom:0.6.0"
}

GitHub Packages requires authentication even for public artifacts. Configure github.user and github.token in your ~/.gradle/gradle.properties or through environment variables.

Compose with grounds-minestom-runtime

plugin-agones-minestom 0.6.0 exposes a GroundsModuleProvider with the stable ID grounds.agones. Add the runtime dependency, discover providers, and select this provider in the server entrypoint:

import gg.grounds.runtime.core.GroundsServer

fun main() {
    GroundsServer.builder()
        .discoverProviders()
        .useProvider("grounds.agones")
        .start()
}

The runtime owns the module lifecycle: it installs the module before Minestom starts, then starts it after the server starts and stops it during shutdown. See Runtime composition for provider selection and validation behavior.

Low-level direct usage

Use direct lifecycle calls only when embedding Agones without grounds-minestom-runtime. Runtime-based servers should select the provider instead.

GroundsPluginAgones remains available for a custom Minestom bootstrap:

import gg.grounds.GroundsPluginAgones
import net.minestom.server.MinecraftServer

fun main() {
    val server = MinecraftServer.init()
    val agones = GroundsPluginAgones()

    agones.enable()
    Runtime.getRuntime().addShutdownHook(Thread { agones.disable() })
    server.start("0.0.0.0", 25565)
}

enable() installs listeners and starts reconciliation. disable() cancels the fallback task, removes the event node, and releases the coroutine scope.

State Sync Semantics

Event	Resulting Agones state
`PlayerSpawnEvent` when the server had no other players	`Allocated`
`PlayerSpawnEvent` with existing players	No change
`PlayerDisconnectEvent` that leaves the server empty	`Ready`
Fallback tick every 10 seconds	Reconciled from current player count

The disconnect path schedules its check on the next Minestom tick so that the connection manager’s player list is already updated when the check runs.

All state transitions go through AgonesHelper, which first fetches the gameserver state from the sidecar and only sends Allocate or Ready when it differs. Repeat calls are no-ops.

Label Your GameServer

The library only handles state sync. For the Velocity proxy to discover your Minestom gameserver, you still need to follow the discovery contract:

deploy into the games namespace
add grounds/server-type: <lobby|game|match> to the GameServer resource metadata
listen on port 25565 in the pod

Failure Modes

Agones sidecar unreachable

Errors from the sidecar are logged at error level through the class logger. The fallback loop keeps retrying every 10 seconds, so a short sidecar outage is recovered automatically without any action from your gamemode.

enable called twice without a disable in between

The second call disables the previous runtime first, so the event node and coroutine scope are cleaned up before the new one is created. No duplicate listeners are registered.

No Agones sidecar at all

If your deployment has no Agones sidecar, every sidecar call fails. The plugin continues to run, but cannot influence Agones state. In that setup, consider not loading the module at all to keep logs clean.

Next Steps

Read the Velocity page to see how the proxy picks up this gameserver once it reaches a running Agones state.
Review the Agones Integration overview for the cross-platform picture.

Plugins SDK

Convention plugins

Development libraries

Conventions

Requirements

Add the Dependency

Compose with grounds-minestom-runtime

Low-level direct usage

State Sync Semantics

Label Your GameServer

Failure Modes

Next Steps

​Requirements

​Add the Dependency

​Compose with grounds-minestom-runtime

​Low-level direct usage

​State Sync Semantics

​Label Your GameServer

​Failure Modes

​Next Steps

Requirements

Add the Dependency

Compose with grounds-minestom-runtime

Low-level direct usage

State Sync Semantics

Label Your GameServer

Failure Modes

Next Steps