Try SpatialOS

Sites

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

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 C++, C# and Java SDKs: for details, see the documentation for your SDK:

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.

When you start the cloud deployment, DO NOT use the --snapshot flag: it would override these settings.

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

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

You can’t set load_snapshot_at_startup to false. This is an error (because a deployment requires a snapshot to start from) and the deployment won’t start.

Take a snapshot from a running deployment

Automatically take snapshots

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.

Manually take a snapshot - local deployments

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

Manually take a snapshot - cloud deployments

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

Create snapshots from scratch

You can manipulate snapshots or create them from scratch using the C++, C# and Java SDKs. For details, see the documentation for your SDK:

Convert a snapshot

You can convert binary snapshots to and from a text-based format using spatial project history snapshot convert. 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.

To use a snapshot in a deployment, you must convert it back to the binary format first.

To convert a binary snapshot to text snapshot, or vice versa:

  1. Important: Before you start, you must have uploaded your project with spatial cloud upload or spatial project assembly 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.

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

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

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums