3f8e3924-photo-by-rob-bye-on-unsplash_banner-1200x770

Enabling user-created tools, workflows, and services through our API-first approach.

12 June 2018

As the SpatialOS community has grown over the last few years and our partner games have matured from early prototypes to publicly available MMOs, we have realised the need to enable users to create their own tools, workflows and services. As a result, we are prioritising exposing all the services that SpatialOS provides, locally and in the cloud, through a public Platform API. In this post we will explain our plans for the Platform API, where we are in our development progress, and when you can expect to get your hands on it.

Why expose our APIs?

Exposing the APIs means users will be able to create their own tools, workflows and services. We have done this, firstly, because it give users the flexibility to integrate their own solutions, as well as the option to use our native ones. For example, if you wanted to use an existing matchmaking or player monitoring system, you could now integrate it.

In addition, we believe that enabling you to build and share solutions with the wider SpatialOS developer community is crucial for enabling you to create successful games with greater scope and depth. Creating and operating these games will require faster iteration, testing and validation of new ideas.

One example from the early days of Worlds Adrift was Bossa Studios’ need for tools that would help them balance creature populations. The game’s flying manta rays were sometimes overpopulating the game world by reproducing too much, or were sometimes on the verge of extinction due to organised players exterminating them.

This example highlights that many challenges will arise when making new types of games, and we won’t be able to solve all of them alone. This will only increase with the increasing breadth, scope and depth of SpatialOS games. Emergent gameplay leads to emergent requirements!

Platform API services and use cases

All the services that SpatialOS provides will receive well-documented public APIs. For each service there will be local and cloud interfaces, providing a uniform way of interacting with both types of deployments. This includes all the following services, whose names are subject to change:

  • Deployment service (includes assembly service and snapshot service): create, read, update, and delete deployments, assemblies, and snapshots, with as much flexibility on deployment configuration as there is currently available through the SpatialOS Command Line Interface.
  • Worker service: list, get metadata, restart workers in a given deployment, start test client workers for scale testing.
  • Player management service: generate player identity tokens to authenticate players with SpatialOS, manage deployment queues and rate limits.
  • Logs and metrics service: run queries and assertions on logs and metrics.

Collectively these services will enable you to do things that were previously impossible, such as building a robust matchmaking system with SpatialOS. It will also let you do things that previously were only achievable through use of the available tools in a way that we hadn’t intended, like building automated workflows by invoking the SpatialOS CLI.

Below are some examples of Platform API workflows, along with the services they would use:

  • Cloud CI load testing: start a nightly cloud deployment with the latest build (deployment service), connect 1000 test players (worker service), and run metrics assertions and alerts on deployment health (logs and metrics service).
  • Hot Reloading Workflows: create a game engine plugin that builds and reloads all workers of a given type (worker service) while keeping the deployment running (deployment service). Use this workflow locally for faster iteration time and in the cloud to patch your game with zero downtime (also using the assembly service).
  • Matchmaking: build a matchmaking system that accepts player requests to join the game and connects players into the right deployments (player management service), and spins deployments up or down based on demand (deployment service).

Finally, over time, all the native SpatialOS tools will move to use the same public Platform API, because we believe this is the best way to ensure these APIs are fit for purpose.

Using the Platform API

The Platform API will be available in the C# and C++ SDKs, alongside the existing Worker API for developing managed and client workers.

This will give you a consistent experience when developing with the Platform and Worker APIs, and will provide useful libraries, example clients and helper functions for talking to the Platform services (which are gRPC services). Here is an example of how a C# client might look like using this SDK. It lists the deployments of project foobar using a DeploymentServiceClient object to perform async requests:

/// <summary>Snippet for ListDeploymentsAsync</summary>
public async Task ListDeploymentsAsync_RequestObject()
{
    // Snippet: ListDeploymentsAsync(ListDeploymentsRequest,CallSettings)
    // Create client
    DeploymentServiceClient deploymentServiceClient = await DeploymentServiceClient.CreateAsync();
    // Initialize request argument(s)
    ListDeploymentsRequest request = new ListDeploymentsRequest
    {
        ProjectName = "foobar",
    };
    // Make the request
    PagedAsyncEnumerable<ListDeploymentsResponse, Deployment> response =
        deploymentServiceClient.ListDeploymentsAsync(request);

    // Iterate over all response items, lazily performing RPCs as required
    await response.ForEachAsync((Deployment item) =>
    {
        // Do something with each item
        Console.WriteLine(item);
    });
}

We will enable and encourage users to develop in new environments (including game engines), build new tools, auxiliary web services and data processing systems, for which we will likely introduce support for new languages such as Python or TypeScript based on interest.

What to expect next

We are currently developing the foundations for the new API. We expect to release an alpha version of the C# Platform API around September this year, which will expose the deployment, snapshot, and worker services locally and in the cloud. This will enable a number of new use cases, and we will provide example implementations for some of these.

After releasing the alpha, we will work with our users to validate our approach, get feedback and improve stability. We will then start tackling the player management service and adding support for more languages.

Watch out for a follow-up blog post within the next few months, explaining how you can access the Platform API alpha. In the meantime, follow the button below to discuss this announcement on our forums.