Get SpatialOS

Sites

Menu
You are viewing the docs for 11.0, an old version of SpatialOS. 12.0 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.

On this page:

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 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.
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.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums