Snapshots

A snapshot is a representation of the state of a simulated world at some point in time. It stores each entity (as long as the entity has the Persistence component) and the values of the entity’s components’ properties.

You use a snapshot as the starting point for your world when you deploy, locally or to the cloud.

Backward compatibility

Snapshots are tied to the schema of the world they were created from.

When you change your schema, make sure you change it in a backward compatible manner.

If you want to load a snapshot from before a schema change, make sure you migrate the snapshot to the new schema before you try to load it. You can do this using the Worker SDK: for details, see the documentation for your SDK:

• C++
• C#
• Java

Deployments

Start a local deployment from a snapshot

When you start a local deployment, you need to have a snapshot to start the world from.

Use the --snapshot flag on spatial local launch to specify a snapshot file. For example:

spatial local launch --snapshot=snapshots/start.snapshot

If you don’t specify a snapshot, spatial local launch uses the snapshot file snapshots/default.snapshot in the root of your project directory (if the file exists). (Local deployments only)

Start a cloud deployment from a snapshot

When you start a cloud deployment, you need to have a snapshot to start the world from.

Use a snapshot on disk

Use the --snapshot flag on spatial cloud launchto specify a snapshot file. For example:

spatial cloud launch <assembly name> <launch configuration> <deployment name> --snapshot=snapshots/start.snapshot

Use a snapshot in the history

To run a cloud deployment from a snapshot in the deployment’s history, use legacy_flags in the launch configuration file:

• To use the latest snapshot in the deployment’s history, set load_snapshot_at_startup to true.

• To start from a particular snapshot in the deployment’s history, set snapshot_read_id to the ID of a snapshot (you can find the IDs in the Console).

  This overrides snapshot_tags.

• To start from a snapshot matching a tag or set of tags, set snapshot_tags to a comma-separated set of tags, and set load_snapshot_at_startup to true.

  Any snapshot taken from the deployment will also have these tags. See Tags below.

For example, to use the latest snapshot in the history:

"world": {
    "legacy_flags": [
        {
          "name": "load_snapshot_at_startup",
          "value": "true"
        }
    ],
    ...

Taking snapshots

You can take snapshots automatically or manually, for both local and cloud deployments. You can only take a snapshot of a running deployment.

Automatically

Using the launch configuration file

You can configure how often to automatically take snapshots using snapshot_write_period_seconds in the launch configuration file. The minimum is 600 seconds (10 minutes).

For example, to take snapshots automatically every twenty minutes:

"world": {
    "snapshots": {
        "snapshot_write_period_seconds": 1200
    },
    ...

For cloud deployments the default interval is 600 seconds (10 minutes).

If the snapshots field is empty, no snapshots will be taken. If you set snapshot_write_period_seconds to 0, no snapshots will be taken.

Using the Platform SDK

You can use the Platform SDK’s snapshot service (API reference) to write a script to take snapshots automatically according to your specific use case. You can also use it to automatically download and upload snapshots. See the Replicate local state to cloud scenario for an example of how to do this.

Manually

For local deployments

For local deployments, use the Save snapshot button in the Inspector. This saves snapshots to ~/.improbable/local_snapshots/$SnapshotId.

For cloud deployments

To take a snapshot from a running cloud deployment, use spatial cloud history snapshot create.

Creating snapshots from scratch

You can manipulate snapshots or create them from scratch using the Worker SDK. For details, see the documentation for your SDK:

• C++
• C#
• Java

Converting snapshots

You can convert binary snapshots to and from a text-based format. You might want to do this if you want to have human-readable snapshots, use standard diff tools on them, or store them in version control systems.

You can do this using the CLI or using the snapshot converter directly.

Using the CLI

You can convert a snapshot by using spatial project history snapshot convert.

1. Important: Before you start, you must have uploaded your project with spatial cloud upload at least once since the last schema change.

2. Open a terminal in the root directory of your project.

   If you run the command from a different directory, it won’t work.

3. Run:

   spatial project history snapshot convert --input <path> --input-format <format> --output <path> --output-format <format>
   

   The four arguments are mandatory. The possible values for <format> are binary and text. Run spatial project history snapshot convert --help for more details.

Using the snapshot converter directly

If you are using the flexible project layout (currently in beta), you can use the snapshot converter directly. You first need to retrieve the package using:

spatial package get tools snapshot_converter-x86_64-{PLATFORM} <SDK version> snapshot_converter-x86_64-{PLATFORM}.zip

Remember to specify your SDK version, and replace PLATFORM with win32, linux or macos.

The downloaded zip contains:

• The snapshot_converter binary
• A file called snapshot.descriptor

You can then call the snapshot converter with these arguments:

./snapshot_converter convert <input_filename> <input_format> <output_filename> <output_format> <descriptor_filename> [descriptor_filename...]

Argument	Description
<input_filename>	The snapshot file you want to convert
<input_format>	The format you want to convert from. Possible values are: text or binary
<output_filename>	The file name for your converted snapshot
<output_format>	The format you want to convert to. Possible values are: text or binary
<descriptor_filename>	The list of descriptors needed to convert your snapshots. They are generated using the schema compiler. You need to pass snapshot.descriptor last

Caveats

• If you rename a field, type or component in the schema, you must make the same change in a text snapshot if you want the two to remain compatible. This is because field IDs are serialized using their human-readable names in text snapshots.

• If you upgrade your SpatialOS project , you must first convert your snapshot to binary before upgrading, then convert back into text after upgrading. This is to ensure that field IDs in SpatialOS provided components are correctly updated if they were renamed.

Deployment history

When you configure a remote deployment to take snapshots (see above), these snapshots are added to the history for that deployment. Successive snapshots in the history represent the evolution of that simulated world over time.

You can see the snapshot history for a deployment on console.improbable.io.

A snapshot’s history name is the same as its deployment name.

Download a snapshot

To download a snapshot from a deployment’s history, use:

spatial project history snapshot download

See spatial project history snapshot download for more details.

Upload a snapshot

To upload a local snapshot to a project, use:

spatial project history snapshot upload

See spatial project history snapshot upload for more details.

Tags

You can tag snapshots with arbitrary strings: for example, prod, alpha. Use tags if you want more granular filtering within a history.

For example, to upload a snapshot with the tag alpha, run:

spatial project history snapshot upload deployment_name snapshots/default.snapshot --tags="alpha"

If you want all automatic snapshots to have particular tags, use legacy_flags in the launch configuration file. Set snapshot_tags to a comma-separated set of tags that you want to add.

Search results