Player Tracking

Track player connections, disconnections, counts and capacities through the Agones SDK

Counters and Lists will eventually replace the Beta functionality of Player Tracking, which will subsequently be removed from Agones.

If you are currently using this Beta feature, we would love for you to test (and ideally migrate to!) this new functionality to Counters and Lists to ensure it meet all your needs.

Managing GameServer Capacities

To track your GameServer current player capacity, Agones gives you the ability to both set an initial capacity at GameServer creation, as well be able to change it during the lifecycle of the GameServer through the Agones SDK.

To set the initial capacity, you can do so via GameServer.Spec.Players.InitialCapacity like so:

apiVersion: ""
kind: GameServer
  name: "gs-example"
  # ...
    # set this GameServer's initial player capacity to 10
    initialCapacity: 10

From there, if you need to change the capacity of the GameSever as gameplay is in progress, you can also do so via SDK.Alpha().SetPlayerCapacity(count)

The current player capacity is represented in GameServer.Status.Players.Capacity resource value.

We can see this in action, when we look at the Status section of a GameServer resource , wherein the capacity has been set to 20:

  Node Name:  gke-test-cluster-default-6cd0ba67-1mps
    Capacity:  20
    Count:     0
    Ids:       <nil>
    Name:          gameport
    Port:          7983
  Reserved Until:  <nil>
  State:           Ready

From the SDK, the game server binary can also retrieve the current player capacity via SDK.Alpha().GetPlayerCapacity().

Connecting and Disconnecting Players

As players connect and disconnect from your game, the Player Tracking functions enable you to track which players are currently connected.

It assumed that each player that connects has a unique token that identifies them as a player.

When a player connects to the game server binary, calling SDK.Alpha().PlayerConnect(playerID) with the unique player token will register them as connected, and store their player id.

At disconnection time, call SDK.Alpha().PlayerDisconnect(playerID) , which will deregister them and remove their player id from the list.

Each of these playerIDs is stored on GameServer.Status.Players.IDs, and the current count of connected players can be seen in GameServer.Status.Players.Count.

You can see this in action below in the GameServer Status section, where there are 4 players connected:

  Node Name:  gke-test-cluster-default-6cd0ba77-1mps
    Capacity:  10
    Count:     4
    Name:          gameport
    Port:          7166
  Reserved Until:  <nil>
  State:           Ready

Checking Player Data

Not only is the connected player data stored on the GameServer resource, it is also stored in memory within the SDK, so that it can be used from within the game server binary as a realtime, thread safe, registry of connected players.

Therefore, if you want to:

Next Steps

Last modified July 23, 2024: Graduate Passthrough Port Policy to Beta on Autopilot (#3916) (205e87e)