Skip to main content

​
Unity SDK

The Unity SDK provides specialized integration for Unity game servers with Unity Package Manager support.

​
Installation

​
Unity Package Manager

Add the package via Git URL in Unity Package Manager: 
https://github.com/googleforgames/agones.git?path=/sdks/unity

​
Manual Installation

  1. Download the Unity package from Agones releases
  2. Import into Unity via Assets > Import Package > Custom Package

​
Quick Start

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

public class GameServerManager : MonoBehaviour
{
    private AgonesSdk agones;
    
    async void Start()
    {
        // Initialize SDK
        agones = GetComponent<AgonesSdk>();
        
        if (agones == null)
        {
            Debug.LogError("AgonesSdk component not found!");
            return;
        }
        
        // Connect to SDK
        bool connected = await agones.Connect();
        if (!connected)
        {
            Debug.LogError("Could not connect to SDK server");
            return;
        }
        Debug.Log("Connected to Agones SDK");
        
        // Mark as ready
        var status = await agones.Ready();
        if (status.Ok)
        {
            Debug.Log("Server marked as Ready");
        }
        
        // Start health checking
        InvokeRepeating(nameof(SendHealth), 1f, 2f);
        
        // Get GameServer info
        var gameServer = await agones.GameServer();
        Debug.Log($"GameServer name: {gameServer.ObjectMeta.Name}");
    }
    
    async void SendHealth()
    {
        var status = await agones.Health();
        if (!status.Ok)
        {
            Debug.LogError($"Health check failed: {status.Message}");
        }
    }
    
    async void OnApplicationQuit()
    {
        // Shutdown gracefully
        await agones.Shutdown();
    }
}

​
SDK Component

Add the AgonesSdk component to a GameObject:
  1. Create an empty GameObject (e.g., “AgonesSDK”)
  2. Add the AgonesSdk component
  3. Reference it in your scripts

​
SDK Reference

​
Connection

Task<bool> Connect();

​
Lifecycle Methods

Task<Status> Ready();
Task<Status> Shutdown();
Task<Status> Allocate();
Task<Status> Reserve(long seconds);

​
Health Checking

Task<Status> Health();
Use InvokeRepeating for periodic health checks: 
void Start()
{
    InvokeRepeating(nameof(SendHealth), 1f, 2f);
}

async void SendHealth()
{
    await agones.Health();
}

​
Metadata

Task<Status> SetLabel(string key, string value);
Task<Status> SetAnnotation(string key, string value);

​
State Monitoring

Task<GameServer> GameServer();
void WatchGameServer(Action<GameServer> callback);
Example: 
agones.WatchGameServer(gs => {
    Debug.Log($"GameServer state changed: {gs.Status.State}");
});

​
Alpha Features

​
Player Tracking

await agones.Alpha().PlayerConnect(playerID);
await agones.Alpha().PlayerDisconnect(playerID);
bool connected = await agones.Alpha().IsPlayerConnected(playerID);
string[] players = await agones.Alpha().GetConnectedPlayers();
long count = await agones.Alpha().GetPlayerCount();
long capacity = await agones.Alpha().GetPlayerCapacity();
await agones.Alpha().SetPlayerCapacity(100);

​
Beta Features

​
Counters

Counter counter = await agones.Beta().GetCounter("sessions");
await agones.Beta().UpdateCounter("sessions", new Counter 
{ 
    Count = 5, 
    Capacity = 10 
});

​
Lists

List list = await agones.Beta().GetList("players");
await agones.Beta().AddListValue("players", "player-1");
await agones.Beta().RemoveListValue("players", "player-1");
await agones.Beta().UpdateList("players", new List 
{ 
    Values = new[] { "player-1", "player-2" }, 
    Capacity = 100 
});

​
Unity Coroutines

You can also use Unity coroutines: 
IEnumerator Start()
{
    var connectTask = agones.Connect();
    yield return new WaitUntil(() => connectTask.IsCompleted);
    
    if (connectTask.Result)
    {
        yield return agones.Ready();
        Debug.Log("Ready!");
    }
}

​
Editor Testing

The SDK requires a connection to the Agones sidecar, which is only available in a Kubernetes cluster. You cannot test SDK functionality in the Unity Editor.
For local testing, use conditional compilation: 
#if UNITY_EDITOR
    // Mock SDK behavior
    Debug.Log("Running in Editor - SDK disabled");
#else
    // Real SDK calls
    await agones.Ready();
#endif

​
Best Practices

Use DontDestroyOnLoad if needed across scenes.
More Unity-friendly than async loops.
Ensure graceful cleanup when Unity exits.
Check the return value of Connect() before proceeding.

​
Example Project

See the Unity example in the Agones repository for a complete implementation.

​
Next Steps

C# SDK

For non-Unity .NET servers

SDK Overview

Compare all available SDKs

Build docs developers (and LLMs) love

Get started for freeTalk to us