Sites

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

Migrating snapshots to SpatialOS 11

The required format of entities has changed in SpatialOS 11. In particular:

  • The position property you defined must be replaced with the new improbable.Position component.
  • The improbable.EntityAcl component has been restructured.
  • Every entity needs to have the new improbable.Persistence component.
  • The prefab field has been replaced with the new improbable.Metadata component.

This means that snapshots taken in SpatialOS 10 or earlier aren’t compatiable with SpatialOS 11. If you have any snapshots that can’t be regenerated from code, you must migrate them using the snapshot migration tool (which makes the above changes for you).

You ONLY need to do this if you cannot regenerate snapshots from code.

If you can regenerate your snapshots from code after you’ve upgraded, you should do that instead: it’ll be significantly easier than migrating them using the tool.

The migration tool can only be run on projects on SpatialOS version 10.4. You cannot run it on a project you have upgraded to SpatialOS 11.

We recommend committing the current state of your SpatialOS project in a branch, upgrading your project, then coming back to the branch to migrate your snapshots.

You’ll find it easier to migrate your snapshots once you’ve understood how your schema will change in SpatialOS 11.

The resulting snapshot is not compatible with SpatialOS 10 projects.

To migrate your snapshots:

  1. Open a terminal in the root directory of your project.
  2. Run spatial update.
  3. In the schema/ directory of your project, find all schema components where a position property is defined.

    If your project is based on one of the starter projects, it’s likely to be defined in WorldTransform.schema.

  4. Check what the contents of these schema components are.

    • If the position property is the ONLY property in this component, your upgrade path will be simple.

      For each snapshot you want to migrate, run the following command (in the root directory of your project):

      spatial project history snapshot upgrade_11 --input old.snapshot --output new.snapshot
      
    • If there are other properties in this component, you’ll need to make a decision about how to migrate.

      This is complicated: read through all the options carefully before picking one.

      Your options are as follows:

      • Option 1: add the new Position component AND leave your existing component as it is. The position data will be duplicated in both.

        You’ll need to make sure your project stops using the old position component, to avoid unexpected behaviour.

        To do this, for each snapshot you want to migrate, run the following command (in the root directory of your project):

        spatial project history snapshot upgrade_11 --preserve_extra_position_data --input old.snapshot --output new.snapshot
        
      • Option 2: Manually update the snapshot yourself to split out the EntityPosition data into its own separate Position component.

        Once you’ve done that, run the migration tool as above to make the rest of the changes, using spatial project history snapshot upgrade_11 --input old.snapshot --output new.snapshot (in the root directory of your project).

      • Option 3: Decide to destroy the data in the other fields in the component. This will destroy all data other than the position in any component containing an EntityPosition field.

        You’ll also need to remove all references to that data from your code.

        To do this, for each snapshot you want to migrate, run the following command (in the root directory of your project):

        spatial project history snapshot upgrade_11 --destroy_extra_position_data --input old.snapshot --output new.snapshot
        
  5. Once you’ve migrated all your snapshots, if you haven’t already, switch your project over to using the new components by following the SpatialOS 11 upgrade guide.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums