RPCs

Netcode for Entities uses a limited form of RPCs to handle events. A job on the sending side can issue RPCs, and the RPCs then execute on a job on the receiving side. This limits what you can do in an RPC; such as what data you can read and modify, and what calls you are allowed to make from the engine. For more information on the job system, refer to the Unity User Manual documentation on the C# Job System.

To make the system a bit more flexible, you can use the flow of creating an entity that contains specific netcode components such as SendRpcCommandRequest and ReceiveRpcCommandRequest, which this page outlines.

Extend IRpcCommand

To start, create a command by extending the IRpcCommand:

public struct OurRpcCommand : IRpcCommand
{
}


Or, if you need some data in your RPC:

public struct OurRpcCommand : IRpcCommand
{
    public int intData;
    public short shortData;
}


This will generate all the code you need for serialization and deserialization as well as registration of the RPC.

Sending and receiving commands

To complete the example, you need to create some entities to send and receive the commands you created. To send the command you need to create an entity and add the command and the special component SendRpcCommandRequest to it. This component has a member called TargetConnection that refers to the remote connection you want to send this command to.

Note

If TargetConnection is set to Entity.Null you will broadcast the message. On a client you don't have to set this value because you will only send to the server.

The following is an example of a simple send system which sends a command if the user presses the space bar on their keyboard.

[WorldSystemFilter(WorldSystemFilterFlags.ClientSimulation)]
public class ClientRpcSendSystem : SystemBase
{
    protected override void OnCreate()
    {
        RequireForUpdate<NetworkId>();
    }

    protected override void OnUpdate()
    {
        if (Input.GetKey("space"))
        {
            EntityManager.CreateEntity(typeof(OurRpcCommand), typeof(SendRpcCommandRequest));
        }
    }
}


When the RPC is received, an entity that you can filter on is created by a code-generated system. To test if this works, the following example creates a system that receives the OurRpcCommand:

[WorldSystemFilter(WorldSystemFilterFlags.ServerSimulation)]
public class ServerRpcReceiveSystem : SystemBase
{
    protected override void OnUpdate()
    {
        Entities.ForEach((Entity entity, ref OurRpcCommand cmd, ref ReceiveRpcCommandRequest req) =>
        {
            PostUpdateCommands.DestroyEntity(entity);
            Debug.Log("We received a command!");
        }).Run();
    }
}


The RpcSystem automatically finds all of the requests, sends them, and then deletes the send request. On the remote side they show up as entities with the same IRpcCommand and a ReceiveRpcCommandRequestComponent, which you can use to identify which connection the request was received from.

Creating an RPC without generating code

The code generation for RPCs is optional. If you don't want to use it you need to create a component and a serializer. These can be the same struct or two different ones. To create a single struct which is both the component and the serializer you would need to add:

[BurstCompile]
public struct OurRpcCommand : IComponentData, IRpcCommandSerializer<OurRpcCommand>
{
    public int SpawnIndex;
    public void Serialize(ref DataStreamWriter writer, in RpcSerializerState state, in OurRpcCommand data)
    {
        // Example writing the delta against a baseline of zero.
        writer.WritePackedIntDelta(data.SpawnIndex, 2, state.CompressionModel);  
    }

    public void Deserialize(ref DataStreamReader reader, in RpcSerializerState state, ref OurRpcCommand data)
    {
        data.SpawnIndex = reader.ReadPackedIntDelta(2, state.CompressionModel);
    }

    public PortableFunctionPointer<RpcExecutor.ExecuteDelegate> CompileExecute()
    {
    }

    [BurstCompile(DisableDirectCall = true)]
    private static void InvokeExecute(ref RpcExecutor.Parameters parameters)
    {
    }

    static readonly PortableFunctionPointer<RpcExecutor.ExecuteDelegate> InvokeExecuteFunctionPointer = new PortableFunctionPointer<RpcExecutor.ExecuteDelegate>(InvokeExecute);
}


The IRpcCommandSerializer interface has three methods: Serialize, Deserialize, and CompileExecute. Serialize and Deserialize store the data in a packet, while CompileExecute uses Burst to create a FunctionPointer. The function it compiles takes a RpcExecutor.Parameters by ref that contains entries that you're able to use as needed.

Note

Gotcha: Do not read from (or write to) the struct field values themselves (i.e. do not read or write in-place), read from (and write to) the by-ref argument data!

Because the function is static, it needs to use Deserialize to read the struct data before it executes the RPC. The RPC then either uses the command buffer to modify the connection entity, or uses it to create a new request entity for more complex tasks. It then applies the command in a separate system at a later time. This means that you don't need to perform any additional operations to receive an RPC; its Execute method is called on the receiving end automatically.

To create an entity that holds an RPC, use the function ExecuteCreateRequestComponent<T>. To do this, extend the previous InvokeExecute function example with:

[BurstCompile(DisableDirectCall = true)]
private static void InvokeExecute(ref RpcExecutor.Parameters parameters)
{
    RpcExecutor.ExecuteCreateRequestComponent<OurRpcCommand, OurRpcCommand>(ref parameters);
}


This creates an entity with a ReceiveRpcCommandRequest and OurRpcCommand components.

Note

You don't need to create a receiving RPC entity here, if you don't need one. For example: For an RPC denoting new chat messages, it may be simpler to append your chat message to a buffer on the NetworkConnection entity, then consume said buffer directly via a system.

Once you create an IRpcCommandSerializer, you need to make sure that the RpcCommandRequest system picks it up. To do this, you can create a system that invokes the RpcCommandRequest, as follows:

[UpdateInGroup(typeof(RpcCommandRequestSystemGroup))]
[CreateAfter(typeof(RpcSystem))]
[BurstCompile]
partial struct OurRpcCommandRequestSystem : ISystem
{
    RpcCommandRequest<OurRpcCommand, OurRpcCommand> m_Request;
    [BurstCompile]
    struct SendRpc : IJobChunk
    {
        public RpcCommandRequest<OurRpcCommand, OurRpcCommand>.SendRpcData data;
        public void Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
        {
            Assert.IsFalse(useEnabledMask);
            data.Execute(chunk, unfilteredChunkIndex);
        }
    }
        public void OnCreate(ref SystemState state)
        {
            m_Request.OnCreate(ref state);
        }
        [BurstCompile]
        public void OnUpdate(ref SystemState state)
        {
            var sendJob = new SendRpc{data = m_Request.InitJobData(ref state)};
            state.Dependency = sendJob.Schedule(m_Request.Query, state.Dependency);
        }
}


The RpcCommandRequest system uses an RpcQueue internally to schedule outgoing RPCs.

A note about serialization

You might have data that you want to attach to the RpcCommand. To do this, you need to add the data as a member of your command and then use the Serialize and Deserialize functions to decide what data should be serialized. See the following code for an example of this:

[BurstCompile]
public struct OurDataRpcCommand : IComponentData, IRpcCommandSerializer<OurDataRpcCommand>
{
    public int intData;
    public short shortData;

    public void Serialize(ref DataStreamWriter writer, in OurDataRpcCommand data)
    {
        writer.WriteInt(data.intData);
        writer.WriteShort(data.shortData);
    }

    public void Deserialize(ref DataStreamReader reader, ref OurDataRpcCommand data)
    {
        data.intData = reader.ReadInt();
        data.shortData = reader.ReadShort();
    }

    public PortableFunctionPointer<RpcExecutor.ExecuteDelegate> CompileExecute()
    {
    }

    [BurstCompile(DisableDirectCall = true)]
    private static void InvokeExecute(ref RpcExecutor.Parameters parameters)
    {
        RpcExecutor.ExecuteCreateRequestComponent<OurDataRpcCommand, OurDataRpcCommand>(ref parameters);
    }

    static readonly PortableFunctionPointer<RpcExecutor.ExecuteDelegate> InvokeExecuteFunctionPointer = new PortableFunctionPointer<RpcExecutor.ExecuteDelegate>(InvokeExecute);
}


Note

To avoid problems, make sure the Serialize and Deserialize calls are symmetric. The example above writes an int then a short, so your code needs to read an int then a short in that order. If you omit reading a value, forget to write a value, or change the order of the way the code reads and writes, you might encounter problems.

RpcQueue

The RpcQueue is used internally to schedule outgoing RPCs. However, you can manually create your own queue and use it to schedule RPCs.

To do this, call GetSingleton<RpcCollection>().GetRpcQueue<OurRpcCommand>();. You can either call it in OnUpdate or call it in OnCreate and cache the value through the lifetime of your application. If you do call it in OnCreate, you must make sure that the system calling it is created after RpcSystem.

When you have the queue, get the OutgoingRpcDataStreamBuffer from an entity to schedule events in the queue and then call rpcQueue.Schedule(rpcBuffer, new OurRpcCommand);, as follows. This example sends an RPC using the RpcQueue when the user presses the space bar on their keyboard.

[WorldSystemFilter(WorldSystemFilterFlags.ClientSimulation)]
public class ClientQueueRpcSendSystem : ComponentSystem
{
    protected override void OnCreate()
    {
        RequireForUpdate<NetworkId>();
    }

    protected override void OnUpdate()
    {
        if (Input.GetKey("space"))
        {
            var rpcQueue = GetSingleton<RpcCollection>().GetRpcQueue<OurRpcCommand, OurRpcCommand>();
            Entities.ForEach((Entity entity, ref NetworkStreamConnection connection) =>
            {
            	var rpcFromEntity = GetBufferLookup<OutgoingRpcDataStreamBuffer>();
                if (rpcFromEntity.Exists(entity))
                {
                    var buffer = rpcFromEntity[entity];
                    rpcQueue.Schedule(buffer, new OurRpcCommand());
                }
            });
        }
    }
}
