Skip to main content

​
Unreal SDK

The Unreal SDK provides a plugin for Unreal Engine game servers with both C++ and Blueprint support.

​
Installation

​
Plugin Installation

  1. Download the Agones Unreal Plugin from Agones releases
  2. Extract to your project’s Plugins folder: 
    YourProject/Plugins/Agones/
  3. Enable the plugin in Unreal Editor:
    • Edit > Plugins
    • Search for “Agones”
    • Enable the plugin
    • Restart the editor

​
Building from Source

git clone https://github.com/googleforgames/agones.git
cp -r agones/sdks/unreal YourProject/Plugins/Agones

​
Quick Start (C++)

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

class AGameServerManager : public AActor
{
private:
    UAgonesComponent* AgonesSDK;
    
public:
    virtual void BeginPlay() override
    {
        Super::BeginPlay();
        
        // Get Agones component
        AgonesSDK = FindComponentByClass<UAgonesComponent>();
        
        if (AgonesSDK)
        {
            // Connect to SDK
            AgonesSDK->Connect();
            
            // Mark as ready
            AgonesSDK->Ready();
            UE_LOG(LogTemp, Log, TEXT("Server marked as Ready"));
            
            // Start health checking
            GetWorld()->GetTimerManager().SetTimer(
                HealthTimerHandle,
                this,
                &AGameServerManager::SendHealth,
                2.0f,
                true
            );
            
            // Get GameServer info
            FGameServerResponse GameServer;
            AgonesSDK->GameServer(GameServer);
            UE_LOG(LogTemp, Log, TEXT("GameServer: %s"), *GameServer.ObjectMeta.Name);
        }
    }
    
    void SendHealth()
    {
        if (AgonesSDK)
        {
            AgonesSDK->Health();
        }
    }
    
    virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override
    {
        if (AgonesSDK)
        {
            AgonesSDK->Shutdown();
        }
        Super::EndPlay(EndPlayReason);
    }
    
private:
    FTimerHandle HealthTimerHandle;
};

​
Quick Start (Blueprints)

  1. Add AgonesComponent to your GameMode or GameInstance
  2. In BeginPlay:
    • Call Connect
    • Call Ready
    • Set a timer to call Health every 2 seconds
  3. In EndPlay:
    • Call Shutdown

​
SDK Reference (C++)

​
Agones Component

Add to your Actor: 
UAgonesComponent* AgonesSDK = CreateDefaultSubobject<UAgonesComponent>(TEXT("AgonesSDK"));

​
Connection

void Connect();

​
Lifecycle Methods

void Ready();
void Shutdown();
void Allocate();
void Reserve(int64 Seconds);

​
Health Checking

void Health();
Use a timer: 
GetWorld()->GetTimerManager().SetTimer(
    TimerHandle,
    this,
    &AMyClass::SendHealth,
    2.0f,  // Interval in seconds
    true   // Loop
);

​
Metadata

void SetLabel(FString Key, FString Value);
void SetAnnotation(FString Key, FString Value);

​
State Monitoring

void GameServer(FGameServerResponse& GameServerResponse);
void WatchGameServer(TFunction<void(FGameServerResponse)> Callback);

​
Blueprint Nodes

The Unreal SDK provides Blueprint nodes for all SDK functions:
  • Connect - Connect to SDK server
  • Ready - Mark server as ready
  • Health - Send health ping
  • Shutdown - Shutdown server
  • Allocate - Self-allocate
  • Reserve - Reserve for duration
  • Set Label - Set metadata label
  • Set Annotation - Set metadata annotation
  • Get Game Server - Get current state
  • Watch Game Server - Watch for changes

​
Alpha Features (Blueprints)

  • Player Connect
  • Player Disconnect
  • Is Player Connected
  • Get Connected Players
  • Get Player Count
  • Get Player Capacity
  • Set Player Capacity

​
Beta Features

​
Counters (Blueprints)

  • Get Counter
  • Update Counter

​
Lists (Blueprints)

  • Get List
  • Update List
  • Add List Value
  • Remove List Value

​
Testing in Editor

The SDK requires a connection to the Agones sidecar. You cannot test in the Unreal Editor. Use conditional compilation or build for Linux server.

​
Best Practices

This ensures it persists across level transitions.
Unreal’s timer system is more efficient than Tick.
Ensure cleanup when the game ends.
Always verify the component exists before calling methods.

​
Dedicated Server Build

When building for Linux server:
  1. Set target platform to Linux
  2. Select Server build configuration
  3. Package the project
  4. Build Docker image with the packaged server

​
Next Steps

C++ SDK

For non-Unreal C++ servers

SDK Overview

Compare all available SDKs

Build docs developers (and LLMs) love

Get started for freeTalk to us