Skip to main content

​
Rust SDK

The Rust SDK provides a type-safe, async implementation for Rust game servers using Tokio.

​
Installation

Add to your Cargo.toml:
Cargo.toml
[dependencies]
agones = "1.40"
tokio = { version = "1", features = ["full"] }

​
Quick Start

main.rs
use agones::Sdk;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize SDK
    let sdk = Sdk::new(None, None).await?;
    println!("Connected to Agones SDK");
    
    // Mark as ready
    sdk.ready().await?;
    println!("Server marked as Ready");
    
    // Start health checking
    let health_sdk = sdk.clone();
    tokio::spawn(async move {
        loop {
            if let Err(e) = health_sdk.health().await {
                eprintln!("Health check failed: {}", e);
            }
            tokio::time::sleep(Duration::from_secs(2)).await;
        }
    });
    
    // Get GameServer
    let gameserver = sdk.get_gameserver().await?;
    println!("GameServer name: {}", gameserver.object_meta.unwrap().name);
    
    // Run your game server logic
    // ...
    
    // Shutdown
    sdk.shutdown().await?;
    
    Ok(())
}

​
SDK Reference

​
Creating SDK Instance

use agones::Sdk;

let sdk = Sdk::new(None, None).await?;

// Or with custom host/port
let sdk = Sdk::new(
    Some("localhost".to_string()),
    Some(9357)
).await?;

​
Lifecycle Methods

sdk.ready().await?;
sdk.shutdown().await?;
sdk.allocate().await?;
sdk.reserve(seconds).await?;

​
Health Checking

sdk.health().await?;

​
Metadata

sdk.set_label("key", "value").await?;
sdk.set_annotation("key", "value").await?;

​
State Monitoring

let gameserver = sdk.get_gameserver().await?;

sdk.watch_gameserver(|gameserver| {
    println!("GameServer updated: {:?}", gameserver.status);
}).await?;

​
Alpha Features

​
Player Tracking

sdk.alpha().player_connect("player-1").await?;
sdk.alpha().player_disconnect("player-1").await?;
let connected = sdk.alpha().is_player_connected("player-1").await?;
let players = sdk.alpha().get_connected_players().await?;
let count = sdk.alpha().get_player_count().await?;
let capacity = sdk.alpha().get_player_capacity().await?;
sdk.alpha().set_player_capacity(100).await?;

​
Beta Features

​
Counters

use agones::types::Counter;

let counter = sdk.beta().get_counter("sessions").await?;
sdk.beta().update_counter("sessions", Counter {
    count: 5,
    capacity: 10,
}).await?;

​
Lists

use agones::types::List;

let list = sdk.beta().get_list("players").await?;
sdk.beta().add_list_value("players", "player-1").await?;
sdk.beta().remove_list_value("players", "player-1").await?;
sdk.beta().update_list("players", List {
    values: vec!["player-1".to_string(), "player-2".to_string()],
    capacity: 100,
}).await?;

​
Error Handling

All SDK methods return Result<T, Box<dyn Error>>: 
match sdk.ready().await {
    Ok(_) => println!("Ready!"),
    Err(e) => eprintln!("Error: {}", e),
}

// Or use ?
sdk.ready().await?;

​
Async Runtime

The SDK requires Tokio runtime: 
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Your code here
    Ok(())
}

​
Best Practices

Run health checks and game logic in separate Tokio tasks.
The SDK is Clone and can be shared across tasks.
Always handle Result types returned by SDK methods.
Call shutdown().await? before exiting to clean up resources.

​
Example

See the rust-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