Schema

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

Schema files
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.

How to generate the schema

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

You should request the GDK to generate the schema whenever you add or change any replicated properties (Unreal documentation) or RPCs (Unreal documentation).

Full scan or incremental schema generation

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.
    or
  • 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

Generate the schema via the command line

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.
-MapPaths=/Game/Content/Maps

Generate the schema during the cooking process

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

How it works

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.

Run the command

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 -run=Cook:

<Path to UE4Editor-Cmd.exe> <Path to your game's .uproject file> -run=CookAndGenerateSchema -TargetPlatform=WindowsNoEditor -fileopenlog -unversioned -stdout -CrashForUAT -unattended -NoLogTimes  -UTF8Output

The GenerateSchema, GenerateSchemaAndSnapshots, and 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.

How to delete schema

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

How to exclude directories from schema

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.

Schema and source control

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.

Schema for unique local classes

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


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


Schema


Suggested Edits are limited on API Reference Pages

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