The standard schema library

This page describes the standard schema library. The standard schema library is a set of
schematypes 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.

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.

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:

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

Metadata (optional)

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

component Metadata {
id = 53;
string entity_type = 1;
}

This component is optional, but it’s required if you’re using the Unity SDK.

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: by default, this field is used by the Unity and Unreal
integrations to associate SpatialOS entities with game assets, for example.