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
files are where you define all the components in your game’s SpatialOS world.
You set up .schema
files for your project and use the SpatialOS CLI or schema compiler to generate Worker SDK code from the files. (It generates code in C++, C#, and Java.) You use this generated code in your worker code so that worker instances can interact with the entities in your game’s SpatialOS 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:
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.Standard schema library
This is set of.schema
files that define the standard schema library types and components, such as theimprobable.Coordinates
type or theimprobable.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 thetasks
list, with the nameCodegen
. - put your
.schema
files in a directory calledschema
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 --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 4 months ago