The schema is a set of data definitions which represent your game's objects and the commands and events to interface with them in SpatialOS. The schema is defined in
.schema files and written in the SpatialOS language “schemalang”.
You do not have to write or edit schema files manually: the GDK generates schema files and their contents based on the Actors you have set up for schema generation. (To set up Actors for schema generation, add the native Unreal tag
Replicated or add the class specifier spatial-type to them.)
For classes with replicated properties or RPCs, the GDK stores schema in your project's
SchemaDatabase file (see glossary for further information). If a class does not have replicated properties or RPCs, then the GDK does not generate schema for it.
To generate schema:
- for local or cloud deployments, select Schema on the GDK toolbar.
Image: The GDK toolbar, showing the Schema button
Image: The GDK toolbar, showing the Generate Schema option in the Cloud Deployment Configuration dialog box
When you select Schema on the GDK toolbar, the GDK automatically generates the schema via either:
- a full scan - the GDK reads all the relevant Unreal project files and generates a completely new set of schema.
- an incremental scan - the GDK reads all the relevant Unreal project file changes since the last schema generation and generates additional schema based on the changes, adding them to an existing schema file.
The GDK generates the schema appropriately for you, however, you do have the option to force a full scan. To do this: open the Schema drop-down menu from the GDK toolbar and select Schema (Full Scan).
Image: the GDK toolbar Schema drop-down menu showing the option to force a full scan
You can generate the schema via the command line using an Unreal commandlet. This method uses a full scan. It's useful as part of an automated build system.
To generate the schema via the command line, run the following command:
<Path to UE4Editor.exe> <Path to your game's .uproject file> -run=GenerateSchemaAndSnapshots -MapPaths=<MapName1;MapName2;MapName3>
This command generates the schema using a full scan for all classes that have replicated properties or RPCs, and generates individual snapshots (
<MapName>.snapshot) for each map. Any specified map paths that end in
/ are interpreted as a directory, and snapshots are generated for each
.umap found under these paths.
CookAndGenerateSchemaCommandlet command generates the schema needed by your game, and does so during the cooking process, so it is like running the full scan described above, but is faster. It will ultimately replace the command line schema generation described above, but is currently experimental.
CookAndGenerateSchemaCommandlet is a subclass of the native
CookCommandlet. When it runs, it triggers an Unreal-native cook and supplies it with the necessary arguments. During the cook, it keeps track of all classes loaded that require a schema. After the cook, the schema is generated for those supported classes.
You run the commandlet in the same way you would run the Unreal-native
Cook commandlet, with the appropriate arguments, by invoking
-run=CookAndGenerateSchema instead of
<Path to UE4Editor-Cmd.exe> <Path to your game's .uproject file> -run=CookAndGenerateSchema -TargetPlatform=WindowsNoEditor -fileopenlog -unversioned -stdout -CrashForUAT -unattended -NoLogTimes -UTF8Output
CookAndGenerateSchema commandlets output the schema descriptor by default. You can generate additional compiled schema formats by using the
-AdditionalSchemaCompilerArguments="..." command-line switch.
For example, the following command invokes the
CookandGenerateSchema commandlet, and generates a binary schema bundle and a JSON schema bundle:
<Path to UE4Editor-Cmd.exe> <Path to your game's .uproject file> -run=CookAndGenerateSchema -TargetPlatform=WindowsNoEditor -fileopenlog -unversioned -stdout -AdditionalSchemaCompilerArgs="--bundle_out="improbable/bundle_dir/my_bundle.sb" --bundle_json_out="improbable/bundle_dir/my_bundle.sb.json""
See the Schema compiler CLI reference for a full list of arguments you can use with this switch.
When you generate the schema, the GDK verifies that any classes referenced in the
SchemaDatabase still exist. If you delete a class, the GDK removes it from the
SchemaDatabase the next time you generate the schema.
You can delete the
SchemaDatabase to ensure that it is fully regenerated when you next generate the schema.
To delete the
SchemaDatabase, open the Schema drop-down menu from the GDK toolbar and select Delete schema database.
Image: In the GDK toolbar in the Unreal Editor, select Delete schema database
To exclude directories from schema generation, add them to
Directories to never cook. This can be done within the Unreal Editor under Project Settings > Project Packaging > Packaging > Directories to never cook.
Note that you will not be able to use assets without generated schema in a Spatial deployment, so make sure to exclude only those directories that do not store assets that you are using in your game.
If you are using the built-in Unreal source control system Unreal locks this file on checkout, meaning other users are unable to write to it. To prevent this, mark the
SchemaDatabase as writable locally on each machine, and only check out the file when you are ready to commit any changes made to it.
Whenever you generate schema, the GDK checks the
SchemaDatabase and all the in-memory classes in your project and removes any classes referenced in the
SchemaDatabase that no longer exist.
This means that if you have a class that only exists on one user's machine (for example, a newly created class, or a class used for local testing) then these classes are automatically removed from the
SchemaDatabase whenever another user generates schema.
To prevent this, commit newly created or modified classes to source control alongside the
2020-09-18 Page updated with editorial review: added additional schema compiler arguments command-line switch
2020-06-29 Page updated with editorial review: added 0.10 UI and automated scan type
2020-04-09 Page updated with editorial review: added path for commandlet
2020-01-08 Page updated with editorial review: added commandlet
Updated about a year ago