Get SpatialOS


These are the docs for 13.7, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 13.8 is the newest →

Replicate local state to cloud

The deployment and snapshot services are in alpha and may have breaking changes before stabilizing. For more information on maturity stages see Maturity stages.


Debugging gameplay behavior can be tricky in a massive game such as the type made possible by SpatialOS. Attempting to reproduce game behavior across local and cloud deployments can be difficult, and it’s often necessary to find the root cause of an issue.

With the Platform SDK you can add snapshot functionality directly in your editor of choice to assist you in the debugging process. You can upload a snapshot of your local deployment into the cloud, and use it to start a cloud deployment with the same settings as the local deployment, which you can then use to reproduce issues you observed locally.

The following debugging scenario requires you to start with an active local deployment, and you’ll end with an active cloud deployment. For the purposes of this example we’re starting the local deployment with Setup() and stopping the local deployment with Cleanup().

It’s important to remember that you can only run one deployment locally at a time. For more information on local deployments, see Local API service.

Find out how to download the Platform SDK from the setup guide.

You can find the full code example for this scenario on GitHub.

Example: replicating local state to the cloud

1. Start the SpatialOS CLI local API service

You need to run the local API service in order to use the Platform SDK locally. For information on how to do this, see Starting the local API service.

In order to communicate with the local API service, you must specify the port when creating the client. This port is either the default setting of 9876, or the value you manually set when starting the service. For example:

private const int SpatialDPort = 9876;

private static Deployment _localDeployment;

private static readonly SnapshotServiceClient SnapshotServiceClient = SnapshotServiceClient.Create();

private static readonly SnapshotServiceClient LocalSnapshotServiceClient = SnapshotServiceClient.Create(
    new PlatformApiEndpoint

private static readonly DeploymentServiceClient LocalDeploymentServiceClient = DeploymentServiceClient.Create(
    new PlatformApiEndpoint

In this example, the optional parameter insecure is set to true for the PlatformApiEndpoint. This indicates that the connection is not encrypted, and that no authentication is required. This is acceptable when initiating a connection to a local deployment, but you should leave it as false (the default) when connecting to a cloud deployment.

2. Take a local snapshot of the deployment

Use PollUntilCompleted to wait for the long-running operation to complete.

var localSnapshot = LocalSnapshotServiceClient.TakeSnapshot(new TakeSnapshotRequest
    Snapshot = new Snapshot
        ProjectName = "my_local_project",
        DeploymentName = "my_local_deployment"

3. Download the snapshot

var snapshotFile = Path.GetTempPath() + Guid.NewGuid();
using (var client = new WebClient())
    client.DownloadFile(localSnapshot.DownloadUrl, snapshotFile);

4. Upload the snapshot to the cloud

  1. Make a request to upload a snapshot:

    localSnapshot.ProjectName = "my_cloud_project";
    localSnapshot.DeploymentName = "my_cloud_deployment";
    var uploadSnapshotResponse = SnapshotServiceClient.UploadSnapshot(new UploadSnapshotRequest {Snapshot = localSnapshot});
    1. The upload request results in an UploadSnapshotResponse, which provides a URL you can upload the file to:
    var httpRequest = WebRequest.Create(uploadSnapshotResponse.UploadUrl) as HttpWebRequest;
    httpRequest.Method = "PUT";
    httpRequest.ContentLength = newSnapshot.Size;
    httpRequest.Headers.Set("Content-MD5", newSnapshot.Checksum);
    using (var dataStream = httpRequest.GetRequestStream())
        var bytesToSend = File.ReadAllBytes(snapshotFile);
        dataStream.Write(bytesToSend, 0, bytesToSend.Length);
  2. Once the file is uploaded, you need a ConfirmUpload request to tell SpatialOS that the snapshot has been uploaded and is ready to be associated with your project:

    var newSnapshot = uploadSnapshotResponse.Snapshot;
    SnapshotServiceClient.ConfirmUpload(new ConfirmUploadRequest
        DeploymentName = newSnapshot.DeploymentName,
        Id = newSnapshot.Id,
        ProjectName = newSnapshot.ProjectName

    5. Start a new deployment

    You now have a snapshot of your local game state uploaded to your project in the cloud. You can use this to start a new deployment in the cloud, to reproduce an issue in your pre-production environment:

    _cloudDeployment = new Deployment
        ProjectName = ProjectName,
        Name = DeploymentName,
        LaunchConfig = new LaunchConfig
            ConfigJson = File.ReadAllText(LaunchConfigFilePath)
        AssemblyId = AssemblyId,
        StartingSnapshotId = newSnapshot.Id
    _cloudDeployment = CloudDeploymentServiceClient.CreateDeployment(new CreateDeploymentRequest
        Deployment = _cloudDeployment

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums