Your project's .schema file is where you define all the components that entities in your SpatialOS world can have.

To do this, you set up a .schema file for your project and then you instruct SpatialOS to use the schema file to generate code to use with the Worker SDK. The code is in various languages (C, C#, C++, and Java). You use this generated code in your worker code to interact with the entities in the world.

Notes:

• For information about how to design what goes into components, see Designing components.
• We also recommend seeing the guide to Component best practices.

.schema file set up

Define components in .schema files, written in schemalang. Schema files are stored in the schema/ directory.

For information how to set up schema files, see the schemalang reference page.

Generate code from schema

You instruct SpatialOS to use the schema to generate code for you to use with the Worker SDK. You use this generated code in your worker code to interact with the entities in the world.

There are two ways to generate code: use

• the CLI, or
• the schema compiler directly (only available if you are using the flexible project layout (currently in beta).

Generate code with the CLI

To generate code, you can use the command spatial worker codegen. This executes the build steps specified in your worker build configuration file.

Generate code with the schema compiler directly

If you are using the flexible project layout, you can use the schema compiler. You invoke this via the CLI.

Build dependencies

To use the schema compiler, you need the following installed:

1. Schema compiler
   This is a binary which you invoke via CLI.
   To get this, follow the steps described in Build a worker executable: Download the schema compiler.

2. Standard schema library
   This is set of .schema files that define the standard schema library types and components, such as the improbable.Coordinates type or the improbable.Position component.
   To get this, follow the steps described in Build a worker executable: Download the standard schema library. You can put the standard schema library in any directory.

The flexible project layout (FPL) and structured project layout (SPL)

In the structured project layout, you had to:

• specify parameters for the schema compiler in your build.json file, as an element of the tasks list, with the name Codegen.
• put your .schema files in a directory called schema at the root of your project.

For example, given .schema files defined in the schema directory, to generate C# code into the improbable/generated directory, you would define:

{
  "name": "Codegen",
  "steps": [
    {
      "name": "Dependencies",
      "arguments": [
        "worker_package",
        "unpack"
      ]
    },
    {
      "name": "C#",
      "arguments": [
        "process_schema",
        "generate",
        "--cachePath=.spatialos/schema_codegen_cache",
        "--output=improbable/generated",
        "--language=csharp"
      ]
    }
  ]
}

When you use the schema compiler directly, .schema files can exist in any directory in your project, as long as you specify it using --schema_path.
To perform the same operation as above when invoking the schema compiler directly, you run the following command in the CLI:

./schema_compiler --schema_path=./schema --load_all_schema_on_schema_path --csharp_out=improbable/generated

Generate code for multiple Worker SDK languages

You can generate code for more than one Worker SDK language at one time by specifying an output directory using the --<lang>_out argument for each language you want to generate.
For example, to generate C++ and Java code in addition to C# code for your schema, in the CLI run:

./schema_compiler --schema_path=./schema --load_all_schema_on_schema_path --csharp_out=improbable/generated --java_out=improbable/generated --cpp_out=improbable/generated

Specify schema import dependencies

You can depend on .schema files from more than one directory by specifying more than one --schema_path.

For example, if your schema is defined in the directory schema and you have downloaded the standard schema library in a directory called stl, in the CLI run:

`./schema_compiler --schema_path=./schema --schema_path=./stl/ --load_all_schema_on_schema_path --csharp_out=improbable/generated`

Use schema bundles as input to the schema compiler

You can use schema files contained within schema bundles (.sb or .sb.json) as input to the schema compiler by providing the path to the bundle and the name of the .schema files you would like to compile from the bundle.

For example, given a bundle file bundle_dir/my_bundle.sb which contains a schema file my_schema.schema, you can generate the C++ code for my_schema.schema with the following command:

./schema_compiler --cpp_out=improbable/generated bundle_dir/my_bundle.sb my_schema.schema

You can generate code for .schema files located in bundles and on a schema path simultaneously. To extend the previous example, you can generate code for a file schema/path/other.schema on your schema path as well as the file my_schema.schema located in the bundle bundle_dir/my_bundle.sb with the following command:

./schema_compiler --cpp_out=improbable/generated --schema_path=schema/path bundle_dir/my_bundle.sb my_schema.schema schema/path/other.schema

Merge schema bundles

You can merge schema bundles by using them as input to the schema compiler. For example, given two schema bundles a/bundle.sb and b/bundle.sb, you can create ab/bundle.sb which contains all of the files from both bundles. You could list all of the files in both bundles manually, or load all the files in the provided bundles using the --load_all_schema_files_on_schema_path flag:

./schema_compiler --bundle_out=ab/bundle.sb --load_all_schema_on_schema_path a/bundle.sb b/bundle.sb

Note: This operation will fail if there are two or more files .schema files with the same name but different contents in the provided bundles or schema paths.

Cache previously generated code

Note: The schema compiler does not use the flag --cachePath from the structured project layout (SPL), so you can ignore it.

We recommend generating code for each .schema file individually. In other words, you should invoke the schema_compiler for each file individually instead of using the flag - load_all_schema_on_schema_path. This lets you take advantage of any caching mechanism used by your build system, as code only needs to be regenerated for .schema files that have changed.

For example, to generate C# code for the file my_schema.schema located in the schema directory, in the CLI run:

./schema_compiler --schema_path=./schema  --csharp_out=improbable/generated ./schema/my_schema.schema

Schema compiler CLI reference

You can call the schema compiler with these arguments:

./schema_compiler --schema_path=... [arguments] bundles input_files

where bundles is an optional list of the bundle files (.sb or .sb.json) containing schema files you would like to compile and input_files is the list of one or more .schema files that you would like to compile. You need not provide input_files if you provide the --load_all_schema_on_schema_path flag.

Note: When compiling with the schema standard library, ensure the schema_path is set to the directory containing the 'improbable' directory (where the 'improbable' directory contains the standard library schema).

How to use the generated code

For details on how to use the generated code to send and receive component updates, see the guides for the Worker SDK you are using:

• C++
• C#
• C# bindings
• Java