Agones SDK Overview

Agones provides official SDKs in multiple languages to integrate your game server with the Agones platform. Each SDK communicates with the Agones sidecar container via gRPC, providing lifecycle management, health checking, and metadata operations.

Quick Comparison

SDK Details

Go SDK

The Go SDK is the reference implementation and offers excellent performance with minimal overhead.

Installation
Usage
Features

go get agones.dev/agones/sdks/go

package main

import (
    "log"
    "time"
    sdk "agones.dev/agones/sdks/go"
)

func main() {
    // Create SDK instance
    s, err := sdk.NewSDK()
    if err != nil {
        log.Fatalf("Could not connect to sdk: %v", err)
    }
    
    // Start health checking
    go func() {
        tick := time.Tick(2 * time.Second)
        for {
            err := s.Health()
            if err != nil {
                log.Printf("Health ping failed: %v", err)
            }
            <-tick
        }
    }()
    
    // Mark as ready
    err = s.Ready()
    if err != nil {
        log.Fatalf("Could not send ready: %v", err)
    }
    
    // Get GameServer info
    gs, err := s.GameServer()
    if err != nil {
        log.Printf("Could not get gameserver: %v", err)
    } else {
        log.Printf("GameServer name: %s", gs.ObjectMeta.Name)
    }
    
    // Set label
    err = s.SetLabel("game-mode", "deathmatch")
    if err != nil {
        log.Printf("Could not set label: %v", err)
    }
    
    // Watch for updates
    err = s.WatchGameServer(func(gs *sdk.GameServer) {
        log.Printf("GameServer Update: state=%s", gs.Status.State)
    })
    if err != nil {
        log.Printf("Could not watch gameserver: %v", err)
    }
    
    // Your game logic here...
    
    // Shutdown when done
    err = s.Shutdown()
    if err != nil {
        log.Printf("Could not shutdown: %v", err)
    }
}

Go SDK Documentation

View full API reference on pkg.go.dev

C# SDK

Designed for .NET game servers and Unity integration with async/await patterns.

Installation
Usage
Features

dotnet add package Agones

Or in Unity, copy the SDK files to your Assets folder.

using Agones;
using System;
using System.Threading.Tasks;

class GameServer
{
    private AgonesSDK sdk;
    
    public async Task StartAsync()
    {
        // Create SDK instance
        sdk = new AgonesSDK();
        
        // Start health checking
        _ = Task.Run(async () =>
        {
            while (true)
            {
                await sdk.HealthAsync();
                await Task.Delay(2000);
            }
        });
        
        // Mark as ready
        var result = await sdk.ReadyAsync();
        Console.WriteLine($"Ready result: {result.StatusCode}");
        
        // Get GameServer info
        var gs = await sdk.GetGameServerAsync();
        Console.WriteLine($"GameServer: {gs.ObjectMeta.Name}");
        
        // Set label
        await sdk.SetLabelAsync("game-mode", "capture-the-flag");
        
        // Set annotation
        await sdk.SetAnnotationAsync("session-id", "abc123");
        
        // Watch for updates
        sdk.WatchGameServer((gameServer) =>
        {
            Console.WriteLine($"GameServer Update: {gameServer.Status.State}");
        });
        
        // Access Alpha SDK
        var alpha = sdk.Alpha();
        await alpha.SetPlayerCapacityAsync(10);
        
        // Access Beta SDK
        var beta = sdk.Beta();
        var counter = await beta.GetCounterAsync("sessions");
        
        // Your game logic here...
    }
    
    public async Task StopAsync()
    {
        await sdk.ShutDownAsync();
        sdk.Dispose();
    }
}

Node.js SDK

Ideal for JavaScript and TypeScript game servers with modern async/await API.

Installation
Usage
TypeScript
Features

npm install @google-cloud/agones-sdk

const AgonesSDK = require('@google-cloud/agones-sdk');

async function main() {
    // Create and connect SDK
    const sdk = new AgonesSDK();
    await sdk.connect();
    console.log('Connected to Agones');
    
    // Start health checking
    setInterval(() => {
        sdk.health();
    }, 2000);
    
    // Mark as ready
    await sdk.ready();
    console.log('Server marked as ready');
    
    // Get GameServer info
    const gameServer = await sdk.getGameServer();
    console.log(`GameServer: ${gameServer.objectMeta.name}`);
    console.log(`State: ${gameServer.status.state}`);
    console.log(`Address: ${gameServer.status.address}`);
    
    // Set label
    await sdk.setLabel('map', 'de_dust2');
    
    // Set annotation
    await sdk.setAnnotation('match-id', '12345');
    
    // Reserve for 60 seconds
    await sdk.reserve(60);
    
    // Watch for updates
    sdk.watchGameServer(
        (gameServer) => {
            console.log(`Update: ${gameServer.status.state}`);
        },
        (error) => {
            console.error('Watch error:', error);
        }
    );
    
    // Access Alpha features
    await sdk.alpha.setPlayerCapacity(16);
    const connected = await sdk.alpha.playerConnect('player-123');
    console.log(`Player connected: ${connected}`);
    
    // Your game logic here...
    
    // Shutdown
    await sdk.shutdown();
    sdk.close();
}

main().catch(console.error);

import AgonesSDK, { GameServer } from '@google-cloud/agones-sdk';

async function main(): Promise<void> {
    const sdk = new AgonesSDK();
    await sdk.connect();
    
    // Type-safe health checking
    setInterval(() => {
        sdk.health((error: unknown) => {
            if (error) console.error('Health failed:', error);
        });
    }, 2000);
    
    await sdk.ready();
    
    const gs: GameServer = await sdk.getGameServer();
    console.log(`Running on: ${gs.status.address}:${gs.status.portsList[0]?.port}`);
}

Rust SDK

Type-safe SDK for Rust game servers with excellent performance.

Installation
Usage
Features

Cargo.toml

[dependencies]
agones = "1.0"
tokio = { version = "1", features = ["full"] }

use agones::Sdk;
use std::time::Duration;
use tokio::time;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create SDK instance
    let sdk = Sdk::new(None, None).await?;
    println!("Connected to Agones");
    
    // Start health checking
    let health_sdk = sdk.clone();
    tokio::spawn(async move {
        let mut interval = time::interval(Duration::from_secs(2));
        loop {
            interval.tick().await;
            if let Err(e) = health_sdk.health().await {
                eprintln!("Health ping failed: {}", e);
            }
        }
    });
    
    // Mark as ready
    sdk.ready().await?;
    println!("Server marked as ready");
    
    // Get GameServer info
    let gs = sdk.get_gameserver().await?;
    println!("GameServer: {}", gs.object_meta.name);
    println!("State: {}", gs.status.state);
    
    // Set label
    sdk.set_label("difficulty", "hard").await?;
    
    // Set annotation
    sdk.set_annotation("region", "us-west").await?;
    
    // Your game logic here...
    
    // Shutdown
    sdk.shutdown().await?;
    Ok(())
}

C++ SDK

Native C++ SDK for game engines and custom servers.

Installation
Usage
Features

# Clone the Agones repository
git clone https://github.com/googleforgames/agones.git

# Build the SDK
cd agones/sdks/cpp
cmake .
make
make install

#include <agones/sdk.h>
#include <iostream>
#include <thread>
#include <chrono>

int main() {
    agones::SDK* sdk = new agones::SDK();
    
    // Connect to Agones
    bool connected = sdk->Connect();
    if (!connected) {
        std::cerr << "Could not connect to SDK server" << std::endl;
        return 1;
    }
    std::cout << "Connected to Agones" << std::endl;
    
    // Start health checking in separate thread
    std::thread health_thread([sdk]() {
        while (true) {
            bool ok = sdk->Health();
            if (!ok) {
                std::cerr << "Health ping failed" << std::endl;
            }
            std::this_thread::sleep_for(std::chrono::seconds(2));
        }
    });
    health_thread.detach();
    
    // Mark as ready
    grpc::Status status = sdk->Ready();
    if (!status.ok()) {
        std::cerr << "Could not mark ready" << std::endl;
        return 1;
    }
    std::cout << "Server marked as ready" << std::endl;
    
    // Get GameServer info
    agones::dev::sdk::GameServer gameserver;
    status = sdk->GameServer(&gameserver);
    if (status.ok()) {
        std::cout << "GameServer name: " 
                  << gameserver.object_meta().name() << std::endl;
    }
    
    // Set label
    status = sdk->SetLabel("version", "1.2.3");
    
    // Set annotation
    status = sdk->SetAnnotation("build", "12345");
    
    // Your game logic here...
    
    // Shutdown
    status = sdk->Shutdown();
    delete sdk;
    
    return 0;
}

Unity SDK

Specialized SDK for Unity game servers with Unity-friendly patterns.

Installation
Usage
Features

Download the Unity SDK from the Agones releases
Import the package into your Unity project
Add the AgonesSdk component to a GameObject

using Agones;
using UnityEngine;
using System.Threading.Tasks;

public class AgonesManager : MonoBehaviour
{
    private AgonesSdk sdk;
    
    async void Start()
    {
        // Create SDK instance
        sdk = gameObject.AddComponent<AgonesSdk>();
        
        // Connect
        bool ok = await sdk.Connect();
        if (!ok)
        {
            Debug.LogError("Failed to connect to Agones");
            return;
        }
        Debug.Log("Connected to Agones");
        
        // Start health checking
        InvokeRepeating(nameof(SendHealthPing), 0f, 2f);
        
        // Mark as ready
        ok = await sdk.Ready();
        Debug.Log($"Ready: {ok}");
        
        // Get GameServer info
        var gs = await sdk.GameServer();
        Debug.Log($"GameServer: {gs.ObjectMeta.Name}");
        Debug.Log($"State: {gs.Status.State}");
        
        // Set label
        await sdk.SetLabel("game-mode", "battle-royale");
        
        // Access Alpha features
        await sdk.Alpha().SetPlayerCapacity(100);
    }
    
    void SendHealthPing()
    {
        sdk.Health();
    }
    
    async void OnApplicationQuit()
    {
        await sdk.Shutdown();
    }
}

Unreal SDK

Plugin for Unreal Engine with Blueprint support.

Installation
Usage
Features

Copy the Agones plugin to your project’s Plugins folder
Enable the plugin in your .uproject file
Restart Unreal Editor

#include "AgonesComponent.h"
#include "GameFramework/Actor.h"

void AMyGameMode::BeginPlay()
{
    Super::BeginPlay();
    
    // Get Agones component
    UAgonesComponent* AgonesSDK = 
        NewObject<UAgonesComponent>(this, UAgonesComponent::StaticClass());
    AgonesSDK->RegisterComponent();
    
    // Connect
    AgonesSDK->Connect();
    
    // Start health checking
    GetWorldTimerManager().SetTimer(
        HealthTimerHandle,
        [AgonesSDK]()
        {
            AgonesSDK->Health();
        },
        2.0f,
        true
    );
    
    // Mark as ready
    AgonesSDK->Ready();
    
    // Set label
    AgonesSDK->SetLabel("map", "BR_Island");
}

REST API

Language-agnostic HTTP/REST interface for any technology stack.

Endpoints
Usage
Features

All endpoints are available at http://localhost:9358 (configurable via AGONES_SDK_HTTP_PORT).

Method	Endpoint	Description
POST	`/ready`	Mark server as ready
POST	`/shutdown`	Shutdown server
POST	`/health`	Send health ping
POST	`/allocate`	Self-allocate server
GET	`/gameserver`	Get GameServer info
GET	`/watch/gameserver`	Stream GameServer updates
PUT	`/metadata/label`	Set label
PUT	`/metadata/annotation`	Set annotation
POST	`/reserve`	Reserve server

cURL Examples

# Mark as ready
curl -X POST http://localhost:9358/ready

# Health ping
curl -X POST http://localhost:9358/health

# Get GameServer
curl http://localhost:9358/gameserver

# Set label
curl -X PUT http://localhost:9358/metadata/label \
  -H 'Content-Type: application/json' \
  -d '{"key": "game-mode", "value": "tdm"}'

# Reserve for 30 seconds
curl -X POST http://localhost:9358/reserve \
  -H 'Content-Type: application/json' \
  -d '{"seconds": 30}'

# Shutdown
curl -X POST http://localhost:9358/shutdown

Python Example

import requests
import time

BASE_URL = "http://localhost:9358"

# Mark as ready
response = requests.post(f"{BASE_URL}/ready")
print(f"Ready: {response.status_code}")

# Health checking loop
def health_loop():
    while True:
        requests.post(f"{BASE_URL}/health")
        time.sleep(2)

# Get GameServer info
response = requests.get(f"{BASE_URL}/gameserver")
gs = response.json()
print(f"GameServer: {gs['objectMeta']['name']}")

# Set label
requests.put(
    f"{BASE_URL}/metadata/label",
    json={"key": "region", "value": "us-east"}
)

Choosing an SDK

Use this decision tree to choose the right SDK:

What's your primary language?

Go: Use Go SDK
C# / .NET: Use C# SDK
JavaScript / TypeScript: Use Node.js SDK
Rust: Use Rust SDK
C++: Use C++ SDK
Other: Use REST API

What engine are you using?

Unity: Use Unity SDK (specialized C# SDK)
Unreal: Use Unreal SDK (plugin)
Custom / Other: Use language-specific SDK

What features do you need?

All SDKs support core features. Check specific SDK documentation for:

Alpha features (player tracking)
Beta features (counters and lists)
Async/await patterns
Streaming updates

SDK Feature Matrix

Next Steps

Lifecycle Management

Learn about Ready, Shutdown, and state transitions

Health Checking

Configure health monitoring

Example Servers

See complete integration examples

Local Development

Test your integration locally

Get Started

Core Concepts

Installation

Game Server Integration

Client SDKs

Operations

Advanced

Agones SDK Overview

Quick Comparison

SDK Details

Go SDK

Go SDK Documentation

C# SDK

Node.js SDK

Rust SDK

C++ SDK

Unity SDK

Unreal SDK

REST API

Choosing an SDK

SDK Feature Matrix

Next Steps

Lifecycle Management

Health Checking

Example Servers

Local Development

Build docs developers (and LLMs) love

Get Started

Core Concepts

Installation

Game Server Integration

Client SDKs

Operations

Advanced

​Quick Comparison

​SDK Details

​Go SDK

Go SDK Documentation

​C# SDK

​Node.js SDK

​Rust SDK

​C++ SDK

​Unity SDK

​Unreal SDK

​REST API

​Choosing an SDK

​SDK Feature Matrix

​Next Steps

Lifecycle Management

Health Checking

Example Servers

Local Development

Build docs developers (and LLMs) love

Quick Comparison

SDK Details

Go SDK

C# SDK

Node.js SDK

Rust SDK

C++ SDK

Unity SDK

Unreal SDK

REST API

Choosing an SDK

SDK Feature Matrix

Next Steps