Skip to main content
Use plugin-agones when your gameserver runs inside the Grounds Kubernetes cluster and you need Agones lifecycle state to track your actual player activity without writing custom SDK code. The plugin translates player events into Agones Ready and Allocated transitions, and lets the Velocity proxy discover running gameservers through the Kubernetes API so players are routed to a lobby automatically.

​
What the Plugin Does

On Paper and Minestom, the plugin reports your gameserver’s Agones state from the current player count:
  • the first player joins → the runtime calls Allocate
  • the last player leaves → the runtime calls Ready
  • a 10 second fallback loop reconciles the state if an event is missed
On Velocity, the plugin adds three responsibilities on top of proxy-side state sync:
  • it polls the Kubernetes API for running gameservers and registers them with the proxy
  • it registers explicitly configured non-Agones backends from GROUNDS_STATIC_SERVERS
  • it routes newly joining players to a lobby server and rejects logins when no lobby is available
plugin-agones assumes your gameserver pod runs with an Agones sidecar exposing the SDK on http://localhost:9358. The Grounds container images ship this configuration by default.

​
Module Layout

The repository ships four modules. Gamemode developers consume the platform module matching their runtime.

​
Gameserver Discovery Contract

The Velocity discovery path depends on three conventions that your gameserver deployment must follow:
  • the pod runs in the configured discovery namespace (default: games)
  • the Agones GameServer carries the label grounds/server-type with one of lobby, game, or match
  • the pod exposes Minecraft on port 25565 and reports its PodIP under status.addresses
When these conditions are met, the Velocity proxy picks up the gameserver automatically as soon as Agones transitions it into Ready, Allocated, or Reserved.
lobby is treated specially: at least one Ready/Allocated/Reserved gameserver with grounds/server-type=lobby must exist for new proxy logins to succeed.

​
Static Backends

Use GROUNDS_STATIC_SERVERS for a backend that does not run as an Agones GameServer, such as a temporary buildserver deployed as a regular Kubernetes Deployment. Static servers join the Velocity registry without participating in Agones lifecycle management or lobby selection. In production, every Java Velocity proxy reads the same required value from the dedicated immutable, versioned static-server ConfigMap; the plugin loads and caches it at startup. Local development may provide the value directly as an environment literal. Continue with Velocity for the configuration format, rollout and validation rules, and forwarding requirements.

​
Choose Your Platform

Velocity

Learn how the Velocity proxy discovers gameservers, routes players to lobbies, and exposes the /agones operator command.

Paper

Install the Paper plugin and let the runtime manage your Agones state from player join and quit events.

Minestom

Embed the Minestom library in your gamemode server to sync Agones state without touching the SDK directly.

​
Typical Use

Use this plugin when:
  • your gameserver deploys into the Grounds Agones-managed cluster
  • a regular backend must be reachable through the same Velocity proxies
  • you want Agones state to reflect real player activity instead of a static allocation call
  • your gamemode publishes its role through grounds/server-type so the Velocity proxy can route to it
If you are integrating a new gamemode server now, continue with the platform page that matches your runtime.