Sites

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

Flexible project layout (beta)

The flexible project layout is in beta maturity. It is available for testing and early evaluation but not recommended for public releases. See Maturity stages for more information.

The flexible project layout (FPL) is a new directory layout for describing a SpatialOS project on your computer. It is designed to replace the current project directory layout, referred to as the structured project layout (SPL). Have a look at our example project to see the FPL in action.

The FPL provides the following advantages over the SPL:

  • You can freely place your project files (configuration files, schema files, worker projects, build artifacts) anywhere on your hard drive using a directory structure of your choosing. Your project does not need to adhere to a fixed directory structure (such as having the schema and workers folder inside a shared project folder). This flexibility allows you to store different parts of your project in separate places and manage them with different version control schemes. It also allows you integrate your project with your preferred toolchain and build systems more easily.
  • You have full control over the build process of your project. You can perform all build steps directly, including previously internal ones that the spatial CLI ran under the hood. You can fully build your project assembly without using spatial worker build.
  • Your FPL project does not have a single well-defined SpatialOS SDK version. You can generate different build artifacts (workers, snapshots, schema descriptor) using libraries and tooling from different SDK versions. This allows you to migrate your project to a different SDK version incrementally.

Using the flexible project layout

Setting up your SpatialOS project to use the FPL

We provide you with an example project to help you get started. You can find the example project here.

Running a deployment locally

Ensure that:

Run the following command in the directory containing the project configuration file (spatialos.json) of your project:

$ spatial alpha local launch

The following command flags are available:

  • --main_config: Specify a filepath (absolute or relative to the project configuration file (spatialos.json)) to start your deployment with. Overrides the default project configuration.
  • --launch_config: Specify a filepath (absolute or relative to the launch configuration file) to start your deployment with. Overrides the default launch configuration.
  • --snapshot: Specify a filepath (absolute or relative to the snapshot file) to start your deployment with. Overrides the default snapshot.

As soon as your deployment is running, you can connect client-workers to it by manually starting your built-out client-executable with the approriate command line arguments.

Running a deployment in the cloud

To upload your project assembly to the cloud:
Run the following command in the directory containing the project configuration file (spatialos.json) of your project:

$ spatial alpha cloud upload -a <your-assembly-name>

The following command flags are available:

To start a deployment in the cloud:
Run the following command in the directory containing the project configuration file (spatialos.json) of your project:

$ spatial alpha cloud launch -d <your-deployment-name> -a <your-assembly-name>

The following command flags are available:

  • --main_config: Specify a filepath (absolute or relative to the project configuration file (spatialos.json)) to start your deployment with. Overrides the default project configuration.
  • --launch_config: Specify a filepath (absolute or relative to the launch configuration file) to start your deployment with. Overrides the default launch configuration.
  • --snapshot: Specify a filepath (absolute or relative to the snapshot file) to start your deployment with. Overrides the default snapshot.

FAQ

How do I specify the SpatialOS SDK version of my project?
FPL projects do not have a clearly defined SDK version. You need to keep track of the SDK version(s) that you are using separately. Because you now have full control over which tools and libraries you use when building your project, there is no way for SpatialOS to reliably determine or enforce the SDK version you are using.

Note: It is possible for different workers to use different SDK versions in the same project.

Do you support spatial worker codegen, spatial worker build and spatial worker clean?
We don’t support those commands for FPL projects going forward. The build process of a worker is fully managed by you. For more information, please see Building a worker executable.

Can I use spatial alpha local launch, spatial alpha cloud upload and spatial alpha cloud launch for SPL projects?
spatial alpha local launch, spatial alpha cloud upload and spatial alpha cloud launch are only compatible with FPL projects. Please use spatial local launch, spatial cloud upload and spatial cloud launch for SPL projects.

Is the FPL really in beta? The spatial CLI commands have alpha in their name.
Yes, the FPL is in beta. The alpha namespace is intended to expose beta functionality too.

Do you support spatial local worker launch?
We don’t support spatial local worker launch for FPL projects going forward. Please start and connect your worker programs to a deployment manually.

Do you support spatial project history snapshot convert?
We don’t support spatial project history snapshot convert for FPL projects going forward. Please convert the format of your snapshots manually using the snapshot converter tool. You can refer to convert_snapshot.sh for a code example.

Known issues

  • If you want to use the Platform SDK, you should not convert your launch configuration file into FPL format. The Platform SDK currently only works with SPL format launch configuration files. We will provide an improved workflow in the future. See Starting a deployment using the Platform SDK for instructions on how to convert an FPL format launch configuration file to its SPL equivalent as a temporary work-around.

Upcoming changes

  • [Breaking change] We will remove the snapshot.startDeploymentFromSnapshotFile string field from the launch configuration file, and add a new string field called startDeploymentFromSnapshotFile to the project configuration file. The new startDeploymentFromSnapshotFile field is functionally identical to and will replace the old snapshot.startDeploymentFromSnapshotFile field.

Changelog

This list documents changes made to the FPL feature since its beta release. For a list of changes between the alpha and beta stage, see here.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums