> ## Documentation Index
> Fetch the complete documentation index at: https://grounds-docs-scene-editor-design.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agones Integration

> Overview of plugin-agones across Paper, Velocity, and Minestom gameservers

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

<Info>
  `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.
</Info>

## Module Layout

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

| Module     | Target            | Delivery                               |
| ---------- | ----------------- | -------------------------------------- |
| `common`   | shared runtime    | used transitively by the three others  |
| `velocity` | Velocity proxy    | Velocity plugin JAR                    |
| `paper`    | Paper gameservers | Paper plugin JAR                       |
| `minestom` | Minestom servers  | Kotlin library you embed into your app |

## 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`.

```mermaid theme={null}
flowchart LR
    A[GameServer CRD] -- labeled `grounds/server-type` --> B[Agones state Ready/Allocated/Reserved]
    B --> C[Velocity DiscoveryService poll]
    C --> D[Registered with Velocity proxy]
    D --> E[Players routed to lobby on login]
    F[Player joins Paper or Minestom] --> G[AgonesHelper.allocate]
    H[Last player leaves] --> I[AgonesHelper.ready]
```

<Note>
  `lobby` is treated specially: at least one `Ready`/`Allocated`/`Reserved` gameserver with
  `grounds/server-type=lobby` must exist for new proxy logins to succeed.
</Note>

## 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](/reference/plugins/agones/velocity#static-servers) for the configuration
format, rollout and validation rules, and forwarding requirements.

## Choose Your Platform

<CardGroup cols={3}>
  <Card title="Velocity" icon="network-wired" href="/reference/plugins/agones/velocity">
    Learn how the Velocity proxy discovers gameservers, routes players to lobbies, and exposes the
    `/agones` operator command.
  </Card>

  <Card title="Paper" icon="server" href="/reference/plugins/agones/paper">
    Install the Paper plugin and let the runtime manage your Agones state from player join and quit
    events.
  </Card>

  <Card title="Minestom" icon="cubes" href="/reference/plugins/agones/minestom">
    Embed the Minestom library in your gamemode server to sync Agones state without touching the SDK
    directly.
  </Card>
</CardGroup>

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