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 in chunk_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’s spatialos.<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.

Search results