Deploying a SpatialOS project
In a nutshell
To deploy a SpatialOS project to the cloud:
Build the project:
spatial worker build -t=deployment.
Upload the project assembly:
spatial cloud upload <assembly name>
spatial cloud launch <assembly name> <launch configuration file> <deployment name> --snapshot=<snapshot file>
Unity cheat sheet
For a handy guide to how to deploy Unity changes, see this cheat sheet:
1. (First time only) Configure the project
If you’re deploying for the first time, configure your project’s
- In the project’s root directory, open
spatialos.json. This file holds your project’s global configuration.
namefield, rename the value to your assigned SpatialOS project name.
You can find your project name in the Console. It’ll be something like
2. Build the project
The first step of running a cloud deployment is uploading all the files that your game uses. This includes executable files for the clients and workers, and the assets your workers use (like models and textures used by the Unity client to visualize the game). We call that set of game files an assembly.
To keep build times down, see this cheat sheet for what to build when (Unity only).
Or you can build the whole project from the command line:
If your project includes a Unity worker, close the Unity Editor (otherwise the build will fail).
In the project’s root directory, run
spatial worker build --target=deployment.
When it finishes successfully, you’ll see
build finishedin your console output.
For more details, see how to build after you made changes.
3. Upload project assembly to the cloud
To upload the assembly you just built from your project, run
spatial cloud upload <assembly name>
where assembly name is a name you choose. It’ll identify the assembly you just built.
When this has run successfully, you’ll see
upload <assembly name> finished in your
NOTE: When you update SpatialOS versions, you must rebuild the assembly and upload it with a different name. You could add a date or a commit hash to the name; for example,
4. Choose the snapshot to start from
All deployments must start from a snapshot. You can:
- download a snapshot from a previous deployment
- choose an existing snapshot you’ve already created
- create a snapshot from scratch
You’ll use this snapshot in step 5.
Alternatively, you can configure your project to load from a specific snapshot.
5. Deploy the project
To deploy the project to the cloud, run
spatial cloud launch <assembly name> <launch configuration file> <deployment name> --snapshot=<snapshot file> [flags]
- assembly name is the name of the assembly you uploaded with
spatial cloud upload.
- launch configuration file is a launch configuration file. It’s
default_launch.jsonin the project’s root directory.
- deployment name is the label for this deployment in the Console. Must be in lowercase.
- snapshot file is the snapshot to start the world from, which you chose in step 4
- flags are optional flags. Run
spatial cloud launch --helpto see the list of available flags.
Note: This command defaults to deploying to an US production cluster (such as
us3-prod). If you’re in Europe, add
--cluster_region=euto to deploy to a European cluster.
spatial cloud launch my_assembly_name_160809 default_launch.json my_deployment_name --snapshot==snapshots/default.snapshot --cluster_region=eu
spatial cloud launch --help for more information.
When this finishes successfully, you’ll see
Successfully created deployment in your console output.
The output will also give you a link to your deployment in
6. (Optional) Launch an Unity client
If your project has a Unity client, you can follow these steps to launch it:
- Open the Console.
- Find your deployment and click on its name. The page that opens will shows an overview of the deployment.
Launch a Unity client:
Click the ▶ Launch button.
Click Launch Your Deployment:
You can now explore your project from the Unity client.
7. Shut down the deployment
Manually stopping a deployment
We recommend manually stopping a deployment after you’ve finished with it, to save on resource usage.
To manually stop a deployment:
Open the Console.
Find your deployment and click on its name.
In the page that opens, click the STOP button:
Automatic deployment shutdown
By default, deployments are shut down 6 hours after they start. You can add tags in the Console to change this behaviour:
- To postpone the shutdown until 5pm UTC on the next weekday, add the tag
- To keep the deployment running indefinitely, add the tag
Was this page helpful?
Thanks for letting us know!
Thanks for your feedback
Need more help? Ask on the forums