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 in chunk_edge_length_meters.
• workers - worker-specific configuration parameters regarding flags, load balancing, and permissions. The worker_type is defined in filename of the worker’s spatialos.<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.

Search results