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


This section explains where and how to configure the workers in a SpatialOS project.

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.

Worker directory

Code for workers goes in directories in the workers/ directory of a project, for example workers/MyCSharpWorker.

You’re not limited to one worker type per directory: if workers share code or assets, they can go in the same directory.

Configuration file

Each worker needs a worker configuration file, with the name spatialos.<worker_type>.worker.json: for example, spatialos.MyCSharpWorker.worker.json.

This file tells SpatialOS how to build, launch, and interact with the workers.

Once you’ve chosen a label for the worker type (eg myWorkerType), you MUST use this exact label consistently throughout your project to identify this worker type.

The files have the following structure:

    "build": { ... },
    "bridge": { ... },
    "managed": { ... },
    "external": { ... }
  • The build field (required) describes how to build the worker.
  • The bridge field (required) configures information like what components the worker has interest in.
  • The managed field (optional) tells SpatialOS how to run the worker as a managed worker in the cloud. Using this field makes a worker a managed worker.
  • The external field (optional) specifies how to launch the worker as an external worker locally, using spatial local worker launch. Using this field makes a worker an external worker.

Applying configuration changes

The bridge and managed worker configurations are built into the assembly at the start of building a worker.

To apply changes to these configurations to a local deployment, run:

  1. spatial worker build or spatial worker build <worker_type>.
  2. spatial local launch. (The changes won’t get reloaded into a running deployment.)

To apply changes to these configurations to a cloud deployment, run:

To have them applied when running a cloud deployment, you will need to run:

  1. spatial worker build or spatial worker build <worker_type>.
  2. spatial cloud upload.
  3. spatial cloud launch using the assembly you just uploaded.

Adding a new worker

To add a new worker to a project, create a worker configuration file in a new or existing worker directory.

If you’re using generated build scripts, to generate the build scripts, run spatial worker build <worker_type>

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums