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:
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 launch
to 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
totrue
. 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 setload_snapshot_at_startup
totrue
.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:
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
.
- Important: Before you start, you must have uploaded your project with
spatial cloud upload
at least once since the last schema change. Open a terminal in the root directory of your project.
If you run the command from a different directory, it won’t work.
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>
arebinary
andtext
. Runspatial 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.