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:
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:
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 withspatial cloud upload
orspatial 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 theworld
>snapshots
section, rather thanlegacy_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 toC:\Users\(user-name)\AppData\Local\.improbable\local_snapshots
on Windows. This flag is in thelegacy_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 overridessnapshot_tags
, and the default behaviour ofload_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"