Sites

Menu
These are the docs for 14.4, an old version of SpatialOS. 14.5 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 - 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": "worker_command_max_timeout_ms",
            "value": "3000"
          }
        ],
        "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:

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.
interest_queries_components_are_
filtered_by_component_delivery
bool "true" If you’re using only QBI (not CBI), you should set this to false, so that the Runtime doesn’t use checkoutAllInitially or checkout_initially as a whitelist.
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.


————
2019-11-15 Page updated with editorial review: Added interest_queries_components_are_filtered_by_component_delivery.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums