Skip to main content

​
Go SDK

The Go SDK is the reference implementation for Agones and provides the most complete feature set with excellent performance and minimal overhead.

​
Installation

Install the SDK using go get: 
go get agones.dev/agones/sdks/go

​
Quick Start

Here’s a complete example of integrating the Go SDK:
main.go
package main

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

func main() {
    // Initialize the SDK
    s, err := sdk.NewSDK()
    if err != nil {
        log.Fatalf("Could not connect to SDK: %v", err)
    }
    
    // Mark server as ready
    if err := s.Ready(); err != nil {
        log.Fatalf("Could not send Ready: %v", err)
    }
    log.Print("Server marked as Ready")
    
    // Start health checking
    go func() {
        tick := time.Tick(2 * time.Second)
        for range tick {
            if err := s.Health(); err != nil {
                log.Fatalf("Health check failed: %v", err)
            }
        }
    }()
    
    // Get current GameServer state
    gs, err := s.GameServer()
    if err != nil {
        log.Printf("Could not get GameServer: %v", err)
    } else {
        log.Printf("GameServer name: %s", gs.ObjectMeta.Name)
    }
    
    // Run your game server logic here
    // ...
    
    // Shutdown gracefully
    if err := s.Shutdown(); err != nil {
        log.Printf("Could not shutdown: %v", err)
    }
}

​
SDK Reference

​
Creating an SDK Instance

func NewSDK() (*SDK, error)
Creates a new SDK instance and connects to the sidecar at localhost:9357 (or AGONES_SDK_GRPC_HOST:AGONES_SDK_GRPC_PORT if set).

​
Lifecycle Methods

​
Ready

func (s *SDK) Ready() error
Marks the game server as ready to accept player connections.

​
Shutdown

func (s *SDK) Shutdown() error
Gracefully shuts down the game server.

​
Allocate

func (s *SDK) Allocate() error
Self-allocates the game server for a game session.

​
Reserve

func (s *SDK) Reserve(seconds int64) error
Reserves the game server for the specified duration.

​
Health Checking

​
Health

func (s *SDK) Health() error
Sends a health ping to the sidecar. Call this every few seconds.

​
Metadata Management

​
SetLabel

func (s *SDK) SetLabel(key, value string) error
Sets a metadata label on the GameServer resource.

​
SetAnnotation

func (s *SDK) SetAnnotation(key, value string) error
Sets a metadata annotation on the GameServer resource.

​
State Monitoring

​
GameServer

func (s *SDK) GameServer() (*coresdk.GameServer, error)
Retrieves the current GameServer state.

​
WatchGameServer

func (s *SDK) WatchGameServer(callback GameServerCallback) error
Watches for GameServer changes and calls the callback function.
Example
err := sdk.WatchGameServer(func(gs *coresdk.GameServer) {
    log.Printf("GameServer updated: %s", gs.Status.State)
})

​
Alpha Features

Access Alpha features via sdk.Alpha():

​
Player Tracking

// Connect a player
err := sdk.Alpha().PlayerConnect("player-1")

// Disconnect a player
err := sdk.Alpha().PlayerDisconnect("player-1")

// Check if player is connected
isConnected, err := sdk.Alpha().IsPlayerConnected("player-1")

// Get connected players
players, err := sdk.Alpha().GetConnectedPlayers()

// Get player count
count, err := sdk.Alpha().GetPlayerCount()

// Get player capacity
capacity, err := sdk.Alpha().GetPlayerCapacity()

// Set player capacity
err := sdk.Alpha().SetPlayerCapacity(100)

​
Beta Features

Access Beta features via sdk.Beta():

​
Counters

// Get counter
count, err := sdk.Beta().GetCounter("sessions")

// Update counter
err := sdk.Beta().UpdateCounter("sessions", &coresdk.Counter{
    Count: 5,
    Capacity: 10,
})

​
Lists

// Get list
list, err := sdk.Beta().GetList("players")

// Add value to list
err := sdk.Beta().AddListValue("players", "player-1")

// Remove value from list
err := sdk.Beta().RemoveListValue("players", "player-1")

// Update list
err := sdk.Beta().UpdateList("players", &coresdk.List{
    Values: []string{"player-1", "player-2"},
    Capacity: 100,
})

​
Error Handling

All SDK methods return errors. Always check for errors: 
if err := sdk.Ready(); err != nil {
    log.Fatalf("Could not send Ready: %v", err)
}

​
Best Practices

Create the SDK instance during server startup, before accepting connections.
Always check and handle errors returned by SDK methods.
Run health checks in a separate goroutine to avoid blocking your game loop.
Send health pings every 2-5 seconds. Too frequent causes overhead, too infrequent risks false failures.
Always call Shutdown() before exiting to clean up resources properly.

​
Example: Complete Game Server

See the simple-game-server example in the Agones repository for a complete working implementation.

​
Next Steps

SDK API Reference

Complete SDK API documentation

Integration Guide

Learn how to integrate the SDK

Build docs developers (and LLMs) love

Get started for freeTalk to us