Introducing SpatialOS Platform SDK APIs for player management

Back in August 2018, we told you about our plans to enable user-created tools, workflows, and services with the Platform SDK for SpatialOS. Today, we’re excited to announce the next iteration of the SDK in alpha phase, which gives you the flexible building blocks needed to securely implement player authentication, authorisation and matchmaking for your games.

This release includes three things: new APIs which handle how players connect to your game; services that let you run small-scale playtests in the cloud; and enhanced deployment APIs that let you configure how many players can join your game and at what rate. Please note, the existing authentication integration is replaced by the new player auth APIs and will be deprecated in SpatialOS 14.0.

Player auth APIs

The player auth service is a set of APIs for handling how players connect to your game. In combination with the deployment service, now you have the flexible building blocks needed to implement and customise game authentication and matchmaking for your game. These APIs are currently at alpha stage but have been designed to eventually work for matches and lobbies of any size, supporting your game throughout your development and testing iterations. For example, they are used in the player authentication and matchmaking systems for Automaton’s Mavericks playtest that was launched in late November.

The player auth service replaces the player token service. It provides methods to create and validate player identity tokens (PITs), and to create login tokens (LTs). PITs signify authentication of a particular player against your project. LTs signify authorisation of a particular player to join a deployment.

Below is a diagram showing how a player connects to a SpatialOS deployment using the player auth APIs as well as third-party or custom services for authentication and matchmaking.

Here’s how the workflow process goes:

1. The player logs in using a third-party auth provider. A signed provider token is returned.
2. The game client makes a request to a game authentication server to retrieve a PIT.
3. The game authentication server is a service you write (and host) that validates the provider token (making calls to the third-party auth provider where required).
4. The game authentication server makes use of the SpatialOS Platform SDK player auth service to generate a signed PIT. It then returns the PIT to the game client to fulfil the request made in step 2.
5. The game client makes a request to a matchmaker or lobby system. This is a service you write (and host) to get information about the SpatialOS deployment(s) that the player can connect to.
6. After verifying the PIT, the matchmaker uses the Platform SDK deployment service to list the available deployments.
7. In this example, the matchmaker uses the Platform SDK player auth service to generate an LT for the relevant deployment. It then returns the LT to the game client along with some deployment metadata to fulfil the request made in step 5. You can implement any logic here, and even return the list of deployments to the player to choose from before creating the LT.
8. The game client then has all the information it needs to connect to the SpatialOS deployment using the Worker SDK.

Check out how to create your own authentication server in the docs.

Services to help you get started with small-scale playtests

While flexible building blocks are powerful, we recognise that early on in development you want to focus on building and testing core gameplay rather than backend services. With that in mind, we have developed additional functionality to facilitate small-scale playtests in the cloud (up to 1000 concurrent players across a maximum of 10 deployments):

• Development authentication token (exposed via the player auth service)
• Development authentication service
• Development login service

As shown in the diagram below, these services act in place of the auth provider, game authentication, and matchmaker/lobby systems in the diagram above. They purposefully mirror the flow to ease migration to your own services when you are ready.

Please note, this flow does not require the player to log in and instead relies on an embedded (revokable) development authentication token. However, players can still be distinguished pseudonymously for troubleshooting and analytical purposes. As such, it should not be used for live games.

Check out how to use the development auth services in the docs.

Enhanced Deployment APIs

The final part of this release is an update to the Deployment Service that enables you to configure the player capacity and join rate of your deployments via the API. This gives you greater control and configurability on the number of players that can be connected to your game when you set up your matchmaking or lobby systems. In the near future, we will make this configurable also via the SpatialOS Console.

Check out Worker connection limits in the docs.

Get started now – download the Platform SDK

The new APIs are accessible through the Platform SDK, which is currently available in C#. You can download it using the spatial CLI with the following command:

spatial package retrieve platform_sdk csharp 13.5.0 <file_name>.zip

Alternatively, you can access it through NuGet. Please note: For your local deployments to accept API calls, you need to enable local deployment access using ‘spatial service start’. You can find more information about this here. This an alpha release. We want to hear your feedback on the functionality and interface. Please provide feedback and discuss your experience in our forums and Discord!