Get SpatialOS

Sites

Menu

ECS: Authority

This document relates to the ECS workflow.

Authority is how SpatialOS represents which worker instances can write to each specific SpatialOS component.

If you don’t know about authority, you should read Understanding access in the SpatialOS documentation.

Crucially: at runtime, your worker instance may or may not have authority over a given SpatialOS component.

How authority is represented in Unity’s ECS

Authority shared components

For every SpatialOS component attached to a SpatialOS entity, the GDK attaches an ECS shared component (an ECS ISharedComponentData) to the ECS entity. This component is called ComponentName.ComponentAuthority, where ComponentName is the name of the SpatialOS component.

This component contains a single field, HasAuthority, a bool that indicates whether the worker instance has authority over the SpatialOS component.

Note that this component does not contain information about AuthorityLossImminent notifications. For information on how a worker instance gets notified about these, see Authority reactive components below.

Authority reactive components

For every SpatialOS component attached to a SpatialOS entity, the SpatialOS GDK for Unity (GDK) attaches a corresponding ECS component tag (an ECS IComponentData component with no fields) to the ECS entity. We call these “authority tags”.

The authority tags in the GDK are (where T is a SpatialOS component):

  • Whether or not the worker instance has authority:

    • Authoritative<T>: the worker instance has authority over the SpatialOS component
    • NotAuthoritative<T>: the worker instance does not have authority over the SpatialOS component

    For each SpatialOS component, there will only be one of these tags at a time

  • If you’re using AuthorityLossImminent notifications, when there is an Authoritative<T> tag, you could also have:

This is different to the behaviour around AuthorityLossImminent notifications in the SpatialOS SDKs, where Authority can only be in one of three states at a time.

Here’s an example of how to write a system that runs when a worker instance has authority over the Position SpatialOS component:

public class AuthoritativePositionSystem : ComponentSystem
{
    public struct Data
    {
        public readonly int Length;
        // ECS component representing the SpatialOS component Position.
        public ComponentDataArray<Position.Component> Position;
        // ECS component tag representing the worker's authority over the SpatialOS Position component.
        public ComponentDataArray<Authoritative<Position.Component>> PositionAuthority;
    }

    [Inject] Data data;

    protected override void OnUpdate()
    {
        for(var i = 0; i < data.Length; i++)
        {
            // This will only run when the worker instance is authoritative over a Position component.
        }
    }
}

What happens when a SpatialOS entity enters a worker instance’s view

This section is just to tell you how the system works: all of this is handled automatically by the GDK, and you don’t need to do anything to ensure that authority is correctly registered in authority tags.

When a SpatialOS entity enters the worker instance’s view, the GDK:

  • creates an ECS entity to correspond to that SpatialOS entity
  • for each SpatialOS component T on the SpatialOS entity:
    • attaches an ECS component to the ECS entity representing the SpatialOS component T
    • attaches a NotAuthoritative<T> authority tag to represent the worker instance’s authority over the SpatialOS component T

This means entities may initially have NotAuthoritative<T> attached for a tick, even when the worker instance is actually authoritative over T, because the AuthorityChangeOp hasn’t arrived yet.

What happens when a worker instance gains or loses authority over a SpatialOS entity

When authority changes over a SpatialOS component the GDK automatically adds an AuthorityChanges<T> reactive ECS component to the corresponding ECS entity (where T is the component that changed authority).

AuthorityChanges<T> holds a list of all authority changes that have happened to that SpatialOS component since the last tick.

Here’s an example of doing something when a worker instance gets authority over a SpatialOS component:

public class OnPlayerSpawnSystem : ComponentSystem
{
    public struct Data
    {
        public readonly int Length;
        public ComponentDataArray<PlayerInput.Component> PlayerInput;
        public ComponentDataArray<Authoritative<PlayerInput.Component>> PlayerInputAuthority;
        // ECS component tag representing a change of authority over PlayerInput in the last tick.
        public ComponentDataArray<AuthorityChanges<PlayerInput.Component>> PlayerInputAuthorityChange;
    }

    [Inject] Data data;

    protected override void OnUpdate()
    {
        for(var i = 0; i < data.Length; i++)
        {
            // The data being injected is for being authoritative over the
            // SpatialOS component PlayerInput, and for changes to authority.
            // So, write code here that you want to run when the worker instance
            // receives authority over PlayerInput
        }
    }
}

The GDK automatically adds and removes authority tags: see Reactive components for more information.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums