These are the docs for 13.3, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.5 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. You can find the full code example on GitHub.

Find out how to download the SDK from the Introduction.

Example: replicating local state to the cloud

1. Start the spatial local API service

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