Agones Game Server Client SDKs

The SDKs are integration points for game servers with Agones itself.

Overview

The client SDKs are required for a game server to work with Agones.

The current supported SDKs are:

The SDKs are relatively thin wrappers around gRPC generated clients, or an implementation of the REST API (exposed via grpc-gateway), where gRPC client generation and compilation isn’t well supported.

They connect to a small process that Agones coordinates to run alongside the Game Server in a Kubernetes Pod. This means that more languages can be supported in the future with minimal effort (but pull requests are welcome! 😊 ).

There is also local development tooling for working against the SDK locally, without having to spin up an entire Kubernetes infrastructure.

Function Reference

While each of the SDKs are canonical to their languages, they all have the following functions that implement the core responsibilities of the SDK.

For language specific documentation, have a look at the respective source (linked above), and the examples .

Ready()

This tells Agones that the Game Server is ready to take player connections. Once a Game Server has specified that it is Ready, then the Kubernetes GameServer record will be moved to the Ready state, and the details for its public address and connection port will be populated.

Health()

This sends a single ping to designate that the Game Server is alive and healthy. Failure to send pings within the configured thresholds will result in the GameServer being marked as Unhealthy.

See the gameserver.yaml for all health checking configurations.

Shutdown()

This tells Agones to shut down the currently running game server. The GameServer state will be set Shutdown and the backing Pod will be deleted, if they have not shut themselves down already.

SetLabel(key, value)

This will set a Label value on the backing GameServer record that is stored in Kubernetes. To maintain isolation, the key value is automatically prefixed with “stable.agones.dev/sdk-”

Note: There are limits on the characters that be used for label keys and values. Details are here.

This can be useful if you want to information from your running game server process to be observable or searchable through the Kubernetes API.

SetAnnotation(key, value)

This will set a Annotation value on the backing Gameserver record that is stored in Kubernetes. To maintain isolation, the key value is automatically prefixed with “stable.agones.dev/sdk-”

This can be useful if you want to information from your running game server process to be observable through the Kubernetes API.

GameServer()

This returns most of the backing GameServer configuration and Status. This can be useful for instances where you may want to know Health check configuration, or the IP and Port the GameServer is currently allocated to.

Since the GameServer contains an entire PodTemplate the returned object is limited to that configuration that was deemed useful. If there are areas that you feel are missing, please file an issue or pull request.

The easiest way to see what is exposed, is to check the `sdk.proto` , specifically at the message GameServer.

For language specific documentation, have a look at the respective source (linked above), and the examples .

WatchGameServer(function(gameserver){…})

This executes the passed in callback with the current GameServer details whenever the underlying GameServer configuration is updated. This can be useful to track GameServer > Status > State changes, metadata changes, such as labels and annotations, and more.

In combination with this SDK, manipulating Annotations and Labels can also be a useful way to communicate information through to running game server processes from outside those processes. This is especially useful when combined with FleetAllocation applied metadata.

Since the GameServer contains an entire PodTemplate the returned object is limited to that configuration that was deemed useful. If there are areas that you feel are missing, please file an issue or pull request.

The easiest way to see what is exposed, is to check the `sdk.proto` , specifically at the message GameServer.

For language specific documentation, have a look at the respective source (linked above), and the examples .

Writing your own SDK

If there isn’t a SDK for the language and platform you are looking for, you have several options:

gRPC Client Generation

If client generation is well supported by gRPC, then generate a client from the `sdk.proto` , and look at the current sdks to see how the wrappers are implemented to make interaction with the SDK server simpler for the user.

REST API Implementation

If client generation is not well supported by gRPC, or if there are other complicating factors, implement the SDK through the REST HTTP+JSON interface. This could be written by hand, or potentially generated from the Swagger/OpenAPI Spec .

Finally, if you build something that would be usable by the community, please submit a pull request!

Building the Tools

If you wish to build the binaries from source the make target build-agones-sdk-binary will compile the necessary binaries for all supported operating systems (64 bit windows, linux and osx).

You can find the binaries in the bin folder in `cmd/sdk-server` once compilation is complete.

See Developing, Testing and Building Agones for more details.

Last modified March 17, 2019: Simplify homepage messaging (ec04f2b)