Try SpatialOS

Sites

Menu

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.

Introduction

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
    (
        "localhost",
        SpatialDPort,
        true
    ));

private static readonly DeploymentServiceClient LocalDeploymentServiceClient = DeploymentServiceClient.Create(
    new PlatformApiEndpoint
    (
        "localhost",
        SpatialDPort,
        true
    ));

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"
    }
})
.PollUntilCompleted()
.GetResultOrNull();

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});
    
  2. 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);
    }
    
  3. 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
}).PollUntilCompleted().GetResultOrNull();

Cleanup();
}

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums