A snapshot is a representation of the state of a SpatialOS world at a given point in time. It stores each persistent entity and the values of their SpatialOS components' properties in a .json or binary file. The entities and their component properties represent replicated Actors in the game world.
You use a snapshot:

  • as the starting point (using an “initial snapshot”) for your SpatialOS world when you deploy your game locally or to the cloud.
  • to save the state of a running SpatialOS cloud deployment.

You might take and use a snapshot in the following situations:

  • To begin a playtest session from a specific saved game state that you reached during a previous playtest session
  • To save a world state when you notice something going wrong during testing. If you generate a snapshot, you can reload the world state later and investigate
  • To save the world state of a live game, so that you can stop and start the server for maintenance. If you generate a snapshot, you can resume the world from the saved state

A snapshot contains only the Actor state held by the SpatialOS Runtime. It does not store Unreal world states. This applies to both single-server and multiserver games.

Type of file

The file contains serialised data. When you generate a snapshot, it is in binary format. If you want a human readable snapshot in json (text) format, you can convert it with the SpatialOS CLI.

Contents of snapshots

The snapshot file stores critical entities and some, but not all, Actors in your game.

Critical entities

Critical entities are listed in snapshot files by default. These entities do not represent Actors in a game. The SpatialOS Runtime requires critical entities: do not delete them.

The critical entities are:

  • SpatialSpawner - An entity with a PlayerSpawner component which contains the spawn_player command. Client-worker instances connecting to a deployment use this entity to spawn their player.
  • GlobalStateManager - The GDK uses this entity to orchestrate deployment startup. For more information, see the Global State Manager glossary entry.


A snapshot does not store all Actors in your game. It stores:

  • All Actors that the SpatialOS Runtime has replicated in the SpatialOS world
  • Details of which placed-in-level Actors the SpatialOS Runtime has deleted from the SpatialOS world.

However, the snapshot does not store any destroyed or torn-off Actors.

Exclude Actors from snapshots

To prevent snapshots from storing a replicated Actor, set the Actor to be NotPersistent in your code. There are two ways you can do this:

  • In C++, annotate the Actor definition with: UCLASS(SpatialType = NotPersistent).
  • In Blueprints, navigate to Class Settings > Spatial Description, and enter NotPersistent.

Recommended practices
We recommend the following good practices:

  • Always mark player controllers and the player state as NotPersistent
  • Consider marking pawns as NotPersistent
  • Consider marking short-lived Actors as NotPersistent
  • If an Actor type A can easily recreate instances of another Actor type, B, consider marking B as NotPersistent
    • For example, if you can recreate a pack of animals (Actors of type B) from an animal-maker object (Actor of type A), you can mark the animals as NotPersistent and not store them in snapshots
    • However, if the animals have long-lived behaviors, such as they grow larger over time, then you should store them in snapshots

More information
For more information, see:

2020-08-04 Page updated with editorial review: updated description of GlobalStateManager to remove reference to Singleton Actors
2020-06-22 Page updated with editorial review: more detail, and generation material moved to sub-page

Updated 12 months ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.