GDK for Unreal

If you are using the GDK for Unreal, you don't need to set up schema for your project. The GDK for Unreal deals with schema automatically for you. You only need to set up schema if you are using either the Worker SDK or GDK for Unity to use SpatialOS with your project.

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:

.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).

Argument Description
--schema_path=<path_to_directory> Root path where the schema files you want to compile are stored. This flag can be specified more than once to provide multiple directories. Note, the directory must be set to the root of import paths for schema imports to resolve correctly. For example, if you have the statement import "example/player.schema", you must pass a schema path to the location of example for it to be resolved correctly.
--load_all_schema_on_schema_path Loads all schema files in the path and contained in any provided bundles as if each .schema file in the schema_path and the provided bundles were passed in individually. If there are some files on the schema path that you don't want to compile, you might want to avoid this - for example, if your build system supports caching and you want to generate only one file per invocation of the schema compiler.
--print_components Prints the components in your schema on the standard output as they are generated
--dependency_out=<path_to_file> Dumps the dependencies to a file
--ast_json_out=<path_to_directory> Note: We have deprecated support for --ast_json_out and will remove it in version 15.0.0.

Dumps the AST in JSON format in a directory
--ast_proto_out=<path_to_directory> Note: We have deprecated support for --ast_proto_out and will remove it in version 15.0.0.
--proto_out=<path_to_directory> Note: We have deprecated support for --proto_out and will remove it in version 15.0.0.

Generates a .proto file underneath the specified directory for each schema file.
--bundle_out=<path_to_file> Generates a binary schema bundle in the specified file
--bundle_json_out=<path_to_file> Generates a JSON schema bundle in the specified file
--cpp_out=<path_to_directory> Generates C++ code from the schema to a directory
--csharp_out=<path_to_directory> Generates C# code from the schema to a directory
--java_out=<path_to_directory> Generates Java code from the schema to a directory
--descriptor_set_out=<path_to_file> Note: We have deprecated support for --descriptor_set_out and will remove it in version 15.0.0.

Generates a protobuf descriptor file, used internally by the Runtime.
--cpp_source_extension=<extension> Generated C++ source files have this extension. Default is *.cc
--cpp_bundle_out=<dir> Generates both a C and a C++ header and source file containing schema bundle helper types and functions.
--cpp_bundle_file_name=<name> Files generated with the --cpp_bundle_out parameter have this filename. Default is cpp_bundle.
--cpp_bundle_name=<name> Name of the schema bundle. Used as a fragment in type and function names. This must be a valid C++ identifier. Default is Schema. Used with --cpp_bundle_out.
--verbose Prints additional information to stderr on what the compiler is doing.
--help Prints usage options to stdout.

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:

Updated 5 days ago


Schema


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.