The standard schema library

This page describes the standard schema library. The standard schema library is a set of schema types and components provided alongside SpatialOS.

The standard library components are special in the sense that they are read by SpatialOS at runtime to control built-in behaviour and runtime features, but are otherwise no different from any component defined in a project’s schema. To a worker, they look just like any other component, and can be manipulated in exactly the same way.

Some of these components are required: SpatialOS will refuse to create an entity without the improbable.Position or improbable.EntityAcl components, for example.

The standard schema library is defined in an a file called improbable/standard_library.schema, which can be imported by any other schema file as usual in order to reuse its type definitions. The library is usually provided by the standard_library (previously WorkerSdkSchema) dependency in the project’s spatialos.json.

Each type and component defined by the standard library is explained here. All of them reside in the improbable schema package.

Position (required)

The most important standard library component is improbable.Position. Read about the Position component in the glossary.

It is defined like so:

type Coordinates {
  double x = 1;
  double y = 2;
  double z = 3;
}

component Position {
  id = 54;
  Coordinates coords = 1;
}

EntityAcl (required)

improbable.EntityAcl (ACL here stands for “access control list”.) Read about the EntityAcl component in the glossary.

This component is a bit more complicated. Its definition is as follows:

type WorkerAttributeSet {
  list<string> attribute = 1;
}

type WorkerRequirementSet {
  list<WorkerAttributeSet> attribute_set = 1;
}

component EntityAcl {
  id = 50;

  WorkerRequirementSet read_acl = 1;
  map<uint32, WorkerRequirementSet> component_write_acl = 2;
}

The WorkerRequirementSet type is used twice in this definition. This type filters on worker instances by matching against their worker attributes (mostly defined in the bridge configuration, but some special attributes can be added at runtime by SpatialOS as well).

A WorkerRequirementSet acts like an OR operation: a worker matches a particular requirement set if the worker matches any of the WorkerAttributeSets contained in the requirement set. Conversely, a WorkerAttributeSet acts like an AND operation: a worker matches an attribute set if the worker has all of the attributes in the set.

For a simple example, a WorkerRequirementSet containing a single WorkerAttributeSet with the two strings "visual" and "physics" would match any worker with both the "visual" and "physics" attributes. A WorkerRequirementSet containing two WorkerAttributeSets, each with a single attribute ("visual" and "physics" respectively), would match any worker with either one of the attributes.

One way to create requirement sets is to hard-code them to match the attribute sets specified in the bridge configurations of particular worker types. However, there’s also a way to make sure a requirement set matches only a particular worker instance (for example, a game client). All incoming command requests provide the runtime attribute set of the calling worker, which includes a special attribute unique to that worker instance. Therefore, a requirement set containing just the attribute set provided by a command request is guaranteed to match exactly the worker instance that initiated the command.

Now, the component_write_acl field in the EntityAcl component defines which workers have write access over each component on the entity. The keys of this map are component IDs (as defined in the schema), and the values are requirement sets. SpatialOS will only grant write access to any component on the entity to a worker matching the requirement set associated with its component ID in this map. (Furthermore, if no such worker exists, but there is a launch configuration for a managed worker type that could match the requirement set, it will launch new managed workers based on the launch and load-balancing configurations in an attempt to satisfy the constraint.)

The read_acl field of the EntityAcl component defines which workers have read access to the entity. Assuming the entity is within the interest region of a given worker, the entity will only be sent down to the worker if the worker matches this requirement set. Note that this applies even if the worker has write access to some component on the entity. For this reason, the ACLs should usually be configured such that any worker with write access to some component will also have read access to the entity.

Persistence (optional)

The improbable.Persistence component is extremely simple, with no fields at all:

component Persistence {
  id = 55;
}

Read about the Persistence component in the glossary.

This component is optional, and has a single purpose: to mark entities for persistence. All entities with this component will be saved in simulation snapshots, and all entities without it will not be. Note that, for consistency, the snapshot APIs in the C++, C# and Java SDKs will not allow any entities without the Persistence component to be written out to a snapshot.

It’s a good idea to think about what sort of entities make sense to be saved in a simulation snapshot, and add the component as appropriate, even if the project isn’t making use of snapshots from live deployments yet. Examples of entities that might make sense to exclude from snapshots are entities representing connected clients or players (which will no longer exist if a deployment is restarted from a snapshot), or short-lived entities (perhaps representing things like bullets or explosions in a game).

For managing persistence at the component field level, use transient fields.

Metadata (optional)

The improbable.Metadata component is for storing metadata related to an entity:

component Metadata {
  id = 53;

  string entity_type = 1;
}

The only built-in special behaviour of the entity_type field is that it’s used by the SpatialOS inspector to categorise entities (the type is displayed beside each entity when hovering over it with the mouse, and so on). However, this field can also be used as a general entity type field for other purposes: to associate SpatialOS entities with game assets, for example.

Table of component IDs

Component	ID
Position	54
EntityAcl	50
Persistence	55
Metadata	53