Skip to main content

​
Overview

The Agones SDK provides a gRPC interface for game servers to communicate with the Agones sidecar. This API enables game servers to:
  • Manage their lifecycle states
  • Update metadata dynamically
  • Track player connections
  • Manage counters and lists for capacity tracking
  • Report health status

​
Architecture

The SDK runs as a sidecar container alongside your game server container in the same Kubernetes Pod. Communication happens over localhost using gRPC, with both binary protocol buffer and HTTP/JSON interfaces available. 
┌─────────────────────────────────┐
│          Game Server Pod         │
│                                  │
│  ┌──────────────────┐            │
│  │   Game Server    │            │
│  │   Container      │            │
│  │                  │            │
│  │  Uses SDK to ──────────┐     │
│  │  communicate    │       │     │
│  └──────────────────┘       │     │
│                             ▼     │
│  ┌──────────────────────────┐    │
│  │   Agones SDK Sidecar     │    │
│  │   (localhost:9357)       │    │
│  │                          │    │
│  │  • Lifecycle Management  │    │
│  │  • Health Checking       │    │
│  │  • Metadata Updates      │    │
│  └──────────────────────────┘    │
└─────────────────────────────────┘

​
SDK Stability Stages

The SDK is organized into three stability stages:

​
Stable (GA)

The core SDK service (agones.dev.sdk.SDK) provides production-ready lifecycle and metadata management. These features are stable and recommended for all deployments. Key capabilities:
  • Lifecycle state transitions (Ready, Shutdown, Allocate)
  • Health reporting
  • Metadata updates (labels, annotations)
  • Game server state queries
  • Reservation system

​
Alpha Features

Alpha SDK features (agones.dev.sdk.alpha.SDK) provide player tracking capabilities. These require the PlayerTracking feature gate to be enabled. Key capabilities:
  • Player connection/disconnection tracking
  • Player capacity management
  • Player ID queries
Alpha features may have breaking changes in future releases. Use in production with caution and test thoroughly before upgrading.

​
Beta Features

Beta SDK features (agones.dev.sdk.beta.SDK) provide Counters and Lists for advanced capacity management. These require the CountsAndLists feature gate to be enabled. Key capabilities:
  • Counter get/update operations
  • List get/update operations
  • List value add/remove operations
Beta features are more stable than alpha but may still evolve. APIs are unlikely to change significantly, but minor adjustments may occur based on feedback.

​
Service Endpoints

The SDK sidecar exposes services on localhost:9357 by default:
  • Core SDK: / (root path)
  • Alpha SDK: /alpha/* paths
  • Beta SDK: /v1beta1/* paths

​
Client Libraries

Official SDK client libraries are available for multiple languages:
  • Go: agones.dev/agones/pkg/sdk
  • C#: Agones Unity SDK
  • C++: Native gRPC client
  • Node.js: gRPC-node client
  • Rust: Agones Rust SDK
  • REST: HTTP/JSON gateway for any language

​
Common Workflows

​
Basic Game Server Lifecycle

  1. Startup: Game server container starts
  2. Initialization: Game server completes loading assets and configuration
  3. Ready: Call SDK.Ready() to signal readiness for allocation
  4. Allocated: Agones allocates the server (or call SDK.Allocate() for self-allocation)
  5. Match: Players connect and play
  6. Shutdown: Call SDK.Shutdown() when match ends

​
Health Monitoring

If health checking is enabled (default), send health pings:
  1. Open a streaming connection with SDK.Health()
  2. Send Empty messages at regular intervals (default: every 5 seconds)
  3. If health pings stop, Agones marks the server as unhealthy

​
Dynamic Metadata

Update game server metadata during runtime:
  1. Call SDK.SetLabel() to add/update labels
  2. Call SDK.SetAnnotation() to add/update annotations
  3. Use for dynamic tagging (game mode, map, version, etc.)

​
Player Tracking (Alpha)

Track connected players with the Alpha SDK:
  1. Call PlayerConnect() when a player joins
  2. Call PlayerDisconnect() when a player leaves
  3. Query player counts with GetPlayerCount()
  4. Check specific player connections with IsPlayerConnected()

​
Capacity Management (Beta)

Manage complex capacity with Counters and Lists:
  1. Use Counters for numeric capacity (e.g., current players, match count)
  2. Use Lists for string-based tracking (e.g., player IDs, room names)
  3. Update values during gameplay with increment/decrement operations
  4. Query current state for allocation decisions

​
Protocol Details

  • Protocol: gRPC with Protocol Buffers (proto3)
  • Packages:
    • agones.dev.sdk (stable)
    • agones.dev.sdk.alpha (alpha)
    • agones.dev.sdk.beta (beta)
  • Transport: HTTP/2 over localhost
  • Default Port: 9357
  • HTTP Gateway: REST endpoints via gRPC-Gateway

​
Error Handling

The SDK uses standard gRPC status codes:
  • OK (0): Success
  • NOT_FOUND (5): Resource doesn’t exist (e.g., counter, list)
  • ALREADY_EXISTS (6): Value already present (e.g., duplicate player ID)
  • OUT_OF_RANGE (11): Capacity exceeded or invalid count
  • INVALID_ARGUMENT (3): Invalid field or parameter

​
Best Practices

​
Call Ready() Promptly

Call SDK.Ready() as soon as your game server can accept player connections. Delaying this call wastes resources and increases allocation latency.

​
Implement Health Checks

Always implement health checking unless you have a specific reason to disable it. Health checks ensure Agones can detect and recover from server failures.

​
Clean Shutdown

Always call SDK.Shutdown() when your match ends to release resources promptly. Don’t rely on pod termination timeouts.

​
Minimize Metadata Updates

While metadata updates are fast, avoid excessive calls. Batch updates when possible and only update when values actually change.

​
Use Reservations for Matchmaking

Use SDK.Reserve() to temporarily hold a game server during matchmaking without fully allocating it. This prevents allocation by other systems while you finalize player matching.

​
Next Steps

Lifecycle Methods

Core SDK methods for managing game server lifecycle

Metadata Methods

Methods for updating labels and annotations

Alpha SDK

Player tracking features (alpha stage)

Beta SDK

Counters and Lists for capacity management (beta stage)

Build docs developers (and LLMs) love

Get started for freeTalk to us