C# Game Server Client SDK
Note
The C# SDK will also be available as a NuGet package in a future release.Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.
Download
Download the source directly from GitHub .
Install using NuGet
- Download the nuget package directly
- Install the latest version using the Package Manager:
Install-Package AgonesSDK
- Install the latest version using the .NET CLI:
dotnet add package AgonesSDK
To select a specific version, append --version
, for example: --version 1.8.0
to either commands.
Prerequisites
- .Net Standard 2.0 compliant framework.
Usage
Reference the SDK in your project & create a new instance of the SDK wrapper:
Initialization
To use the AgonesSDK, you will need to import the namespace by adding using Agones;
at the beginning of your relevant files.
var agones = new AgonesSDK();
Connection
To connect to the SDK server, either locally or when running on Agones, run the ConnectAsync()
method.
This will wait for up to 30 seconds if the SDK server has not yet started and the connection cannot be made,
and will return false
if there was an issue connecting.
bool ok = await agones.ConnectAsync();
Ready
To mark the game server as ready to receive player connections, call the async method ReadyAsync()
.
async void SomeMethod()
{
var status = await agones.ReadyAsync();
}
Health
To send Health
pings, call the async method HealthAsync()
await agones.HealthAsync();
GetGameServer
To get the details on the backing GameServer
call GetGameServerAsync()
.
Will return null
if there is an error in retrieving the GameServer
record.
var gameserver = await agones.GetGameServerAsync();
Reserve
To mark the GameServer as Reserved for a duration call
ReserveAsync(long duration)
.
long duration = 30;
var status = await agones.ReserveAsync(duration);
ShutDown
To mark that the game session is completed and the game server should be shut down call ShutdownAsync()
.
var status = await agones.ShutdownAsync();
SetAnnotation & SetLabel
Similarly SetAnnotation(string key, string value)
and SetLabel(string key, string value)
are async methods that perform an action & return a Status
object.
WatchGameServer
To watch when
the backing GameServer
configuration changes
call WatchGameServer(callback)
, where the delegate function callback
of type Action<GameServer>
will be executed every time the GameServer
configuration changes.
This process is non-blocking internally.
agonesSDK.WatchGameServer((gameServer) => { Console.WriteLine($"Server - Watch {gameServer}");});
Player Tracking
Warning
The Player Tracking feature is currently Alpha, not enabled by default, and may change in the future.
Use the FeatureGate PlayerTracking
to enable and test this feature.
See the Feature Gate documentation for details on how to enable features.
Alpha: PlayerConnect
This method increases the SDK’s stored player count by one, and appends this playerID to GameServer.Status.Players.IDs. Returns true and adds the playerID to the list of playerIDs if the playerIDs was not already in the list of connected playerIDs.
bool ok = await agones.Alpha().PlayerConnectAsync(playerId);
Alpha: PlayerDisconnect
This function decreases the SDK’s stored player count by one, and removes the playerID from GameServer.Status.Players.IDs. Will return true and remove the supplied playerID from the list of connected playerIDs if the playerID value exists within the list.
bool ok = await agones.Alpha().PlayerDisconnectAsync(playerId);
Alpha: SetPlayerCapacity
Update the GameServer.Status.Players.Capacity
value with a new capacity.
var capacity = 100;
var status = await agones.Alpha().SetPlayerCapacityAsync(capacity);
Alpha: GetPlayerCapacity
This function retrieves the current player capacity GameServer.Status.Players.Capacity
.
This is always accurate from what has been set through this SDK, even if the value has yet to be updated on the GameServer status resource.
long cap = await agones.Alpha().GetPlayerCapacityAsync();
Alpha: GetPlayerCount
Returns the current player count
long count = await agones.Alpha().GetPlayerCountAsync();
Alpha: IsPlayerConnected
This returns if the playerID is currently connected to the GameServer. This is always accurate, even if the value hasn’t been updated to the GameServer status yet.
var playerId = "player1";
bool isConnected = await agones.Alpha().IsPlayerConnectedAsync(playerId);
Remarks
- All requests other than
ConnectAsync
will wait for up to 15 seconds before giving up, time to wait can also be set in the constructor. - Default host & port are
localhost:9357
- Methods that do not return a data object such as
GameServer
will return a gRPCGrpc.Core.Status
object. To check the state of the request, checkStatus.StatusCode
&Status.Detail
. Ex:
if(status.StatusCode == StatusCode.OK)
//do stuff
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.
Last modified September 14, 2023: Upgrade Hugo (#3369) (c8649e2)