Get SpatialOS

Sites

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

Launch configuration file

We are in the process of releasing a new, flexible project layout (currently in beta).

When it’s stable, we intend the flexible project layout to replace the project layout described on this page.

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

The small, medium, and large game templates are deprecated and we will remove them in a future release. If you’re currently using one of them, you need to start using one of the templates listed in the table of game template sizes and prices instead.

You can still use SpatialOS for free - see Free tier for details of which templates you can use.

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

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums