The SDKs are integration points for game servers with Agones itself.
They are required for a game server to work with Agones.
There are currently two support SDKs:
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! 😊 ).
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.
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.
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.
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.
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
is currently a development feature and has not been released
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.
When the game server is running on Agones, the SDK communicates over TCP to a small gRPC server that Agones coordinated to run in a container in the same network namespace as it - usually referred to in Kubernetes terms as a "sidecar".
Therefore, when developing locally, we also need a process for the SDK to connect to!
To do this, we can run the same binary that runs inside Agones, but pass in a flag to run it in "local mode". Local mode means that the sidecar binary won't try and connect to anything, and will just send logs messages to stdout so that you can see exactly what the SDK in your game server is doing, and can confirm everything works.
To do this you will need to download the latest agonessdk-server-{VERSION}.zip from releases, and unzip it. You will find the executables for the SDK server, one for each type of operating system.
sdk-server.windows.amd64.exe
- Windowssdk-server.darwin.amd64
- macOSsdk-server.linux.amd64
- Linux
To run in local mode, pass the flag --local
to the executable.
For example:
$ ./sidecar.linux.amd64 --local
{"level":"info","local":true,"msg":"Starting sdk sidecar","port":59357,"time":"2017-12-22T16:09:03-08:00","version":"0.1-5217b21"}
{"level":"info","msg":"Ready request has been received!","time":"2017-12-22T16:09:19-08:00"}
{"level":"info","msg":"Shutdown request has been received!","time":"2017-12-22T16:10:19-08:00"}
If there isn't a SDK for the language and platform you are looking for, you have several options:
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.
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!
If you wish to build the binaries for local development 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.