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 →

Layout of a SpatialOS project

This page goes through the directory layout of a SpatialOS project. The directory layout described on this page is also referred to as the structured project layout (SPL).

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

The flexible project layout allows you to freely organise your project files using any directory structure and gives you full control over the build process, which makes it easier for you to integrate your preferred tools and build systems.

We’ll eventually deprecate the project layout described here in favour of the flexible project layout.

Examples of all configuration files can be found in the Blank Project repository.


Specifies the basic details of a project, including its name, and the SpatialOS version the project uses.

For more information about this file see project definition specification page.

Example spatialos.json (from Blank Project)


A launch config file. You can have multiple launch config files in a project, and specify which one you want to use when you deploy using spatial local launch or spatial cloud launch.

spatial local launch defaults to using the file with the name default_launch.json. For spatial cloud launch, you need to specify a file to use.

A project needs at least one launch config file.

For more information about these config files, including the file format, see the Launch config file page.

Example default_launch.json (from Blank Project)


If you are using Git, you will have a .gitignore file in the root of your project. For more information about this file, see the GitHub help on ignoring files.


This directory contains your schema, written in schemalang

For details on writing a schema, see the schema documentation.


This directory contains the code for the workers used by your simulated world. Its contents will depend on the types of workers you decide to use in your project.

Worker directories

The code for any worker types you build should be placed in a directory with the same name as the worker type, for example workers/pathfinding_worker/.

This directory must contain a spatialos.<worker_type>.worker.json file, which tells SpatialOS how to build, launch, and interact with the worker. The label you use as the worker_type will be used to identify this worker elsewhere in your project (for example, in the launch configuration file).

For details on the file format, see the Configuring a worker section.


Contains files generated by spatial worker build.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums