Skip to main content

​
C++ SDK

The C++ SDK provides native integration for C++ game servers and custom game engines.

​
Installation

The C++ SDK uses CMake for building and can be integrated into your project.

​
Prerequisites

  • CMake 3.15+
  • C++17 compatible compiler
  • gRPC and Protobuf

​
Building from Source

git clone https://github.com/googleforgames/agones.git
cd agones/sdks/cpp
mkdir build && cd build
cmake ..
make
make install

​
CMake Integration

CMakeLists.txt
find_package(agones CONFIG REQUIRED)

add_executable(gameserver main.cpp)
target_link_libraries(gameserver agones::agones)

​
Quick Start

main.cpp
#include <agones/sdk.h>
#include <iostream>
#include <thread>

int main() {
    // Initialize SDK
    agones::SDK* sdk = new agones::SDK();
    
    // Connect to the sidecar
    bool connected = sdk->Connect();
    if (!connected) {
        std::cerr << "Could not connect to SDK server" << std::endl;
        return 1;
    }
    
    // Mark as ready
    grpc::Status status = sdk->Ready();
    if (!status.ok()) {
        std::cerr << "Could not send Ready: " << status.error_message() << std::endl;
        return 1;
    }
    std::cout << "Server marked as Ready" << std::endl;
    
    // Start health checking
    std::thread health_thread([sdk]() {
        while (true) {
            grpc::Status health_status = sdk->Health();
            if (!health_status.ok()) {
                std::cerr << "Health check failed: " << health_status.error_message() << std::endl;
            }
            std::this_thread::sleep_for(std::chrono::seconds(2));
        }
    });
    health_thread.detach();
    
    // Get GameServer
    agones::dev::sdk::GameServer gameserver;
    status = sdk->GameServer(&gameserver);
    if (status.ok()) {
        std::cout << "GameServer name: " << gameserver.object_meta().name() << std::endl;
    }
    
    // Run your game server logic
    // ...
    
    // Shutdown
    sdk->Shutdown();
    delete sdk;
    
    return 0;
}

​
SDK Reference

​
Connection

bool Connect();
Connects to the SDK server sidecar.

​
Lifecycle Methods

grpc::Status Ready();
grpc::Status Shutdown();
grpc::Status Allocate();
grpc::Status Reserve(std::chrono::seconds seconds);

​
Health Checking

grpc::Status Health();

​
Metadata

grpc::Status SetLabel(std::string key, std::string value);
grpc::Status SetAnnotation(std::string key, std::string value);

​
State Monitoring

grpc::Status GameServer(agones::dev::sdk::GameServer* gameserver);
grpc::Status WatchGameServer(const std::function<void(agones::dev::sdk::GameServer)>& callback);

​
Error Handling

All SDK methods return grpc::Status. Check the status: 
grpc::Status status = sdk->Ready();
if (!status.ok()) {
    std::cerr << "Error: " << status.error_message() << std::endl;
}

​
Best Practices

  • Check the return status of all SDK calls
  • Run health checks in a separate thread
  • Call Shutdown() before exiting
  • Use smart pointers for SDK lifecycle management

​
Example Code

See the cpp-simple example for a complete implementation.

​
Next Steps

SDK Overview

Compare all available SDKs

API Reference

Complete SDK API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us