Player Tracking

Track connected players in real time across your game servers. Your game server reports player connections through the Agones SDK, and GameFlow surfaces live player counts in the dashboard.

How It Works

1. When you create a game, set Max Players per Server (e.g. 64)
2. GameFlow provisions a players list with that capacity
3. Your game server calls the Agones SDK when players connect and disconnect
4. GameFlow surfaces the live count in the dashboard

Each game server only has access to its own player list, scoped to that server instance.

Configuration

When creating or editing a game in the dashboard, set the Max Players per Server field in the Resources section. This defines the maximum concurrent players each server instance can hold.

The value is used for:

• Dashboard display: shows current / capacity (e.g. 12 / 64)
• Allocation filtering: only allocate to servers with available capacity (future)
• Fleet autoscaling: scale based on player load (future)

Integrating with Your Game Server

Use the Agones SDK that ships with your engine or language. Player tracking uses the SDK's Beta namespace: call AppendListValue when a player connects and DeleteListValue when they disconnect, against the players list.

The value should be a unique identifier for the player (session ID, account ID, etc).

Node.js / Colyseus

Install the SDK:

npm install @google-cloud/agones-sdk

Connect on startup, then add and remove players in your room lifecycle:

import AgonesSDK from "@google-cloud/agones-sdk";
import { Room, Client } from "colyseus";

const agonesSDK = new AgonesSDK();
await agonesSDK.connect();

export class LobbyRoom extends Room {
	async onJoin(client: Client) {
		await agonesSDK.beta.appendListValue("players", client.sessionId);
	}

	async onLeave(client: Client) {
		await agonesSDK.beta.deleteListValue("players", client.sessionId);
	}
}

C# / Unity

using Agones;
using UnityEngine;

public class GameServer : MonoBehaviour
{
	private AgonesSdk agones;

	async void Start()
	{
		agones = GetComponent<AgonesSdk>();
		await agones.Connect();
	}

	public async void AddPlayer(string playerId)
	{
		await agones.Beta.AppendListValueAsync("players", playerId);
	}

	public async void RemovePlayer(string playerId)
	{
		await agones.Beta.DeleteListValueAsync("players", playerId);
	}
}

Go

import sdk "agones.dev/agones/sdks/go"

s, _ := sdk.NewSDK()

// Player connects
s.Beta().AppendListValue("players", "player-123")

// Player disconnects
s.Beta().DeleteListValue("players", "player-123")

Unreal

UAgonesSubsystem* Agones = UAgonesSubsystem::Get(this);

// Player connects
Agones->AppendListValue("players", "player-123", {}, {});

// Player disconnects
Agones->DeleteListValue("players", "player-123", {}, {});

Rust

// Player connects
sdk.beta().append_list_value("players", "player-123").await?;

// Player disconnects
sdk.beta().delete_list_value("players", "player-123").await?;

Godot / GDScript

Godot has no native Agones SDK for Counters & Lists, so call the local Agones REST API directly. It is available on the server instance at http://localhost:${AGONES_SDK_HTTP_PORT}.

var agones_port = OS.get_environment("AGONES_SDK_HTTP_PORT")
if agones_port == "":
	agones_port = "9358"
var base_url = "http://localhost:" + agones_port

func add_player(player_id: String):
	var http = HTTPRequest.new()
	add_child(http)
	var body = JSON.stringify({"value": player_id})
	http.request(base_url + "/v1beta1/lists/players:addValue",
		["Content-Type: application/json"], HTTPClient.METHOD_POST, body)

func remove_player(player_id: String):
	var http = HTTPRequest.new()
	add_child(http)
	var body = JSON.stringify({"value": player_id})
	http.request(base_url + "/v1beta1/lists/players:removeValue",
		["Content-Type: application/json"], HTTPClient.METHOD_POST, body)

REST API

For any other engine, call the local Agones REST API directly:

# Player connects
curl -d '{"value":"player-123"}' -H "Content-Type: application/json" \
  -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/v1beta1/lists/players:addValue

# Player disconnects
curl -d '{"value":"player-123"}' -H "Content-Type: application/json" \
  -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/v1beta1/lists/players:removeValue

Where Player Data Appears

Location	What it shows
Server list	Players: 12 / 64 per server
Server details	Player Count: 12 / 64
Games page	Total players across all servers for the game
Server history	Final player count when the server exited

API Reference

Player data is included in the following API responses:

GameServer (List/Detail)

{
  "playerCount": 12,
  "playerCapacity": 64,
  "connectedPlayers": ["player-1", "player-2", "..."]
}

GameView (Games List)

{
  "playersCount": 48
}

Notes

• Player tracking only works when Max Players is set to a value greater than 0.
• The player list key is always players and cannot be changed.
• Agones Counters & Lists is a Beta feature in Agones, enabled by default.
• Agones SDK calls run locally on the server instance, so they're fast.
• AppendListValue / DeleteListValue only update the tracking list. They do not connect or disconnect players: your game server is responsible for managing real connections.