Get SpatialOS



The Java worker SDK is currently experimental. We're very open to feedback --- don't hesitate to get in touch on the forums.


The default build for the Java worker sets up a project that should get you started quickly, lets you customize the build, and is upgradeable between SpatialOS versions. However, if you need to customize it further, you can turn off the automatic build script generation.

IDE support

After setting up a project (see Setting up a Java worker) and running spatial worker build for the first time, your project structure should be the following:

+-- workers/<your-directory-name>
    +-- worker-sdk          // Auto-generated worker SDK project and schema-generated code.
    |   \-- build.gradle
    |-- worker              // Your worker project.
    |   |-- src/main/java   // Default root source directory for your worker.
    |   \-- build.gradle    // Your project's build configuration.   
    |-- build.gradle        // Auto-generated main project build file
    |-- settings.gradle     // Gradle settings file
    \-- spatialos.<your_worker_type>.worker.json

You can load the workers/<your-directory-name>/build.gradle with any IDE that supports Gradle. Note that, by default, the auto-generated files and directories will be overwritten every time a build is run. You can still fully customize the workers/<your-directory-name>/worker/build.gradle and workers/<your-directory-name>/settings.gradle files, which will not be overwritten.

If you wish to further customize the project to make it compatible with your build system, please follow Specifying worker’s build on how to turn off automatic build scripts generation.

Project setup

There are two Gradle subprojects defined in the settings.gradle:

  • worker-sdk - generated by spatial, contains and builds all the SDK-generated code.
  • worker - can be customized freely and will generally depend on the worker-sdk subproject.

The worker-sdk subproject includes the generated code and native SDK libraries, one for each platform. When you run spatial worker build, the required code will be generated for your schema. This is then compiled by the worker-sdk subproject and can be used by your worker subproject as a dependency.

Once your worker subproject is built, the top-level build.gradle script makes sure that all the dependencies are packed into a self-contained, executable jar with Java main class specified in the manifest file according to the settings.gradle file. The final jar file is portable, since it contains binaries for all supported platforms.

After the jar file is created, the build scripts will invoke spatial command line tool to create an assembly for each platform. You can change this behaviour by disabling automatic build scripts generation and editing the file.

Source control setup

We recommend to add some files and directories to the list of ignored items in your source control system. You might want to add build/ and spatial.log. If you are using the default build scripts, you might also want to add, /build.gradle, spatialos_worker_packages.json and worker-sdk/.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums