Launch configuration file
A launch configuration file contains the information that spatial local launch
and spatial cloud launch
use
to run a deployment.
Reference format
A launch configuration is a *.json
file with the following sections:
template
- specified the template this launch configuration is based on. The value can be any of the available templates.world
- configuration for the simulated world.chunk_edge_length_meters
- the size of the grid squares that the world is divided into, in “world units” (an arbitrary unit that workers can interpret as they choose. Unity workers interpret one world unit as one meter in the Unity coordinate space)streaming_query_interval
- the time between streaming query updates (in seconds).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.
legacy_flags
- legacy non-worker flag configurations.legacy_javaparams
- legacy JVM configurations.dimensions
- configure the size of your SpatialOS simulation in meters. Note: all values must be divisible by the value specified inchunk_edge_length_meters
.
workers
- worker-specific configuration parameters regarding flags, load balancing, and permissions. Theworker_type
is defined in filename of the worker’sspatialos.<worker_type>.worker.json
file.
{
"template": "small",
"world": {
"chunk_edge_length_meters": 50,
"streaming_query_interval": 4,
"snapshots": {
"snapshot_write_period_seconds": 600
},
"legacy_flags": [
{
"name": "load_snapshot_at_startup",
"value": "false"
}
],
"legacy_javaparams": [
{
"name": "-DCLOUD_LAUNCH_CONFIG",
"value": "your.project.GameSettings"
}
],
"dimensions": {
"x_meters": 1000,
"z_meters": 1000
}
},
"workers": [
{
"worker_type": "my_worker",
"flags": [
{
"name": "a_custom_flag",
"value": "true"
},
{
"name": "another_flag",
"value": "500"
}
],
"load_balancing": {
"auto_hex_grid": {
"num_workers": 16
}
},
"permissions": [{
"entity_creation": {
"allow": true
},
"entity_deletion": {
"allow": true
},
"entity_query": {
"allow": true,
"components": [
"your.project.SomeComponent",
"your.project.OtherComponent"
]
}
}],
}
]
}
For information about creating custom flags for workers to use, see Worker flags.
Example
A minimal launch config:
{
"template": "small",
"world": {
"chunk_edge_length_meters": 50,
"streaming_query_interval": 4,
"dimensions": {
"x_meters": 1000,
"z_meters": 1000
}
}
}
Further examples are available in the Wizards, Pirates, and Blank Project repositories.
Templates
A template defines the compute resources your deployment needs (i.e., its ‘topology’). There are three templates:
Template name | Description | Works for local deployments? |
---|---|---|
small |
The simplest topology. Use this for local development and small cloud tests. | Yes |
medium |
A more complex topology capable of much more than small . Use this as you start to scale up. |
No |
large |
Our biggest topology without going custom. Use this to test at scale. | No |
By default, you only have access to the small
template.
If you want to use one of the bigger templates, or if you need something custom, get in touch with Improbable.
Legacy flags
You can add the following flags to the legacy_flags
section:
Flag | Type | Default value | Description |
---|---|---|---|
bridge_qos_max_timeout |
string |
"10000" |
How long (in ms) SpatialOS waits for a worker to respond before it’s killed. Set to 0 to disable. |
engine_range_limit_prefix |
string |
"" |
Prefix of worker IDs to do range limiting for (by default, every worker can be range limited). |
load_snapshot_at_startup |
bool |
"false" |
If true then SpatialOS will attempt to load a specified snapshot on launch. You shouldn’t use this option, as it’s set on launch to true by the spatial command-line. |
max_players_capacity |
"1000" |
The maximum number of players that the world should support. If more than this number of players try to connect, they’ll be added to a queue. If they connect using ConnectAsync , clients will receive callbacks giving them their place in the queue, and must wait for the Future<Connection> object that ConnectAsync returns before they can connect to the game. |
|
player_engine_type |
string |
"" |
The worker type of the workers that should be treater as players. |
qos_max_unacked_pings_rate |
"0.5d" |
Kill the worker if there are more than MAX_UNACKED_PINGS_RATE Pings without Pongs from maxLatency x 2 ago to maxLatency ago. | |
snapshot_destination_file |
string |
"" |
Local deployments only. Specified as a relative path from the project directory. File to write to when taking snapshots. |
snapshot_read_id |
long |
"0L" |
Cloud deployments only. If set, SpatialOS will load the snapshot with this id on startup. |
snapshot_source_file |
string |
"" |
Local deployments only. Specified as a relative path from the project directory. If set, SpatialOS will load the snapshot from the file on startup. |
snapshot_storage_type |
string |
"remote" |
Either remote or file . Set to remote for cloud deployments and file for local deployments. |
snapshot_tags |
string |
"" |
Cloud deployments only. Specified as a comma-separated list of tags. If set, SpatialOS will load the snapshot with matching the tag(s) on startup. |
worker_start_connection_timeout_ms |
"30000" |
Time (in ms) before starting a worker is assumed to have failed if it doesn’t connect. |