Snapshots

A snapshot is a representation of the state of a simulated world taken at some point in time. It stores each entity and the values of their components’ properties.

You’ll use a snapshot as the starting point for your simulated world when you deploy, locally or remotely.

Using snapshots

Loading from snapshots

To run SpatialOS from a snapshot on your local filesystem, you can use the --snapshot flag on the spatial cloud launch and spatial local launch commands to specify the relative path to a local snapshot.

For example, to launch SpatialOS locally with snapshot file stored at snapshots/start.snapshot, run:

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

And to launch a SpatialOS deployment with the same snapshot file:

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

When running locally, if no snapshot is specified spatial local launch will default to using the snapshot file snapshots/default.snapshot in the root of your project directory. If this default snapshot does not exist on the file system, spatial will report a warning.

For more fine-grained control on starting SpatialOS from a snapshot, see the Flag configuration section below. This section describes how you can set flags in your launch configuration for a more permanent setup, or for more involved behaviour, such as writing snapshots periodically.

Note that setting the --snapshot command-line flag will override any behaviour specified by these launch configuration flags.

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 SDKs: for details, see their API documentation:

• C++
• C#
• Java

Creating snapshots from scratch

The worker SDKs include functionality to manipulate snapshots offline, including the ability to create them from scratch for use as the starting point of a simulated world. For details on how to create a snapshot, see the API documentation:

• C++
• C#
• Java

Downloading a snapshot

You can download a snapshot from a deployment’s history with:

spatial project history snapshot download

See this page for more details.

Uploading a snapshot

You can upload a local snapshot to a deployment with:

spatial project history snapshot upload

See this page for more details.

Taking a snapshot

To take a snapshot from a running deployment, use spatial cloud history snapshot create. See this page for more details.

Converting a snapshot

If you want to have human-readable snapshots, use standard diff tools on them, and store them in version control systems, you can convert the binary snapshots (taken from a running simulation or created from scratch, as described elsewhere in this document) to a text-based format.

spatial can convert a binary snapshot to a text snapshot, or vice versa. Note that in order to upload a snapshot and use it with a simulated world, it needs to be converted back to the binary format first.

Using spatial project history snapshot convert

To convert a binary snapshot to text snapshot, or vice versa, go to the root of your project, make sure you have uploaded it first (see the caveats below), and 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.

Caveats

• In order to use spatial project history snapshot convert, you must run it from the root of your project, and you must have uploaded your project with spatial cloud upload or spatial project assembly upload at least once since the last schema change. These restrictions will be relaxed or removed in future releases.

• 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 between major versions, 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.

Flag configuration

Configuring local deployments

To configure snapshots for local deployments, you can add the following flag to the legacy_flags section of your launch configuration file:

{
      "name": "snapshot_storage_type",
      "value": "file"
}

You can then use these other flags:

• To take snapshots:
  • snapshot_write_period_seconds: Interval of time (in seconds) to take snapshots. Set to 0 to disable. This flag is in the world>snapshots section, rather than legacy_flags.
  • snapshot_destination_file: Local file to write to when taking snapshots. Specified as a relative path from the project root directory. If you don’t specify a file, snapshots will be written to ~/.improbable/local_snapshots on macOS or to C:\Users\(user-name)\AppData\Local\.improbable\local_snapshots on Windows. This flag is in the legacy_flags section.
• To load the world from a snapshot:
  • load_snapshot_at_startup: true.
  • snapshot_source_file: The local snapshot file to start the deployment from. Specified as a relative path from the project root directory.

For example, to take snapshots every ten minutes, and load the world from a specific snapshot:

...
    "world": {
        "snapshots": {
            "snapshot_write_period_seconds": 600
        },
        "legacy_flags": [
          {
            "name": "snapshot_storage_type",
            "value": "file"
          },
          {
            "name": "load_snapshot_at_startup",
            "value": "true"
          },
          {
            "name": "snapshot_source_file",
            "value": "start_state.snapshot"
          },
          {
            "name": "snapshot_destination_file",
            "value": "most_recent_state.snapshot"
          }
        ],
...

Configuring remote deployments

To configure snapshots for remote deployments, you can add the following flag to the legacy_flags section of your launch configuration file:

{
    "name": "snapshot_storage_type",
    "value": "remote"
}

You can then use these other flags:

• To take snapshots:
  • snapshot_write_period_seconds: the frequency in seconds to write snapshots of your simulated world. Defaults to 600 seconds (i.e., 10 minutes). Set to 0 to disable automatic snapshots.
  • snapshot_tags: A comma-separated set of snapshot tags. Snapshots will be tagged with these tags. See Tags below. Also affects the default behaviour of loading the world from a snapshot (see below).

• To load the world from a snapshot:

  • load_snapshot_at_startup: true.

    By default, SpatialOS will load the world from the latest snapshot in the deployment’s history.

  • snapshot_tags A comma-separated set of snapshot tags. SpatialOS will only load a snapshot matching these tags. Also affects snapshot-taking behaviour (see above).

  • snapshot_read_id: ID of a remote snapshot. Load the world from this snapshot. This overrides snapshot_tags, and the default behaviour of load_snapshot_at_startup.

For example, to take snapshots every ten minutes, and load the world from the latest snapshot (when you deploy):

...
    "world": {
        "snapshots": {
            "snapshot_write_period_seconds": 600
        },
        "legacy_flags": [
          {
            "name": "snapshot_storage_type",
            "value": "remote"
          },
          {
            "name": "load_snapshot_at_startup",
            "value": "true"
          }
        ],
...

Snapshot 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.

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:

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

Search results