Get SpatialOS

Sites

Menu
These are the docs for 13.0, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 13.3 is the newest →

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.
    • 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.
  • 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": 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
        }
    },
    "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:

All of these values need to be surrounded by quotes.

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" 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 "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_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 "30000" Time (in ms) before starting a worker is assumed to have failed if it doesn’t connect.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums