The standard schema library
This page describes the standard schema library. The standard schema library is a set of
schema type
s and
component
s 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 WorkerAttributeSet
s 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 WorkerAttributeSet
s, 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 |