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
- specifies the game template this launch configuration is based on. The value can be any of the available game 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.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 (10 minutes). The minimum is 600 seconds (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
.
load_balancing
- specify the name, load balancing strategy, and number of workers for each layer.workers
- worker-specific configuration parameters regarding flags, permissions, and connection limits.worker_type
is defined in the filename of the worker’sspatialos.<worker_type>.worker.json
file.
{
"template": "w2_r0500_e5",
"world": {
"chunk_edge_length_meters": 50,
"streaming_query_interval": 4,
"snapshots": {
"snapshot_write_period_seconds": 1200
},
"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
}
},
"load_balancing": {
"layer_configurations": [
{
"layer": "my_worker_attribute",
"hex_grid": {
"num_workers": 4
}
}
]
},
"workers": [
{
"worker_type": "my_worker",
"flags": [
{
"name": "a_custom_flag",
"value": "true"
},
{
"name": "another_flag",
"value": "500"
}
],
"permissions": [{
"entity_creation": {
"allow": true
},
"entity_deletion": {
"allow": true
},
"entity_query": {
"allow": true,
"components": [
"your.project.SomeComponent",
"your.project.OtherComponent"
]
}
}],
"connection_capacity_limit": {
"max_capacity": 500
},
"login_rate_limit": {
"duration": "1s",
"requests_per_duration": 10
}
}
]
}
For information about creating custom flags for workers to use, see Worker flags.
Example
A minimal launch config:
{
"template": "w2_r0500_e5",
"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.
Game templates
A game template defines the compute resources your deployment needs (its “topology”). See the table of game template sizes and prices for a list of all the templates and what they provide.
For local deployments, we only guarantee that you can use the w2_r0500_e5
template. Note that local deployments ignore the specified topology and run on your machine instead.
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. |
load_snapshot_at_startup |
bool |
"false" |
Cloud deployments only. If true then the deployment will be started from an uploaded snapshot. You should only use this option if you want to load from a snapshot in the deployment history. |
max_players_capacity |
int |
"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 treated as players. |
qos_max_unacked_pings_rate |
double |
"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_read_id |
long |
"0L" |
Cloud deployments only. If set, the deployment will be started from the snapshot with this ID. |
snapshot_tags |
string |
"" |
Cloud deployments only. Specified as a comma-separated list of tags. If set, the deployment will be started from the latest snapshot in the deployment history matching the tag(s). |
worker_start_connection_timeout_ms |
long |
"30000" |
Time (in ms) before starting a worker is assumed to have failed if it doesn’t connect. |
worker_command_max_timeout_ms |
long |
"5000" |
Maximum runtime timeout threshold (in ms) for commands sent by workers. |