Remote Procedure Calls

Introduction

RPCs (Remote Procedure Calls) are ideal for sharing punctual game events; in contrast [Networked] properties are the go-to solutions for sharing state between network clients that are undergoing continuous change.

Creating an RPC

To define an RPC on any NetworkBehaviour on a NetworkObject simply follow these steps:

1. Declare a regular CSharp method of return type void or RpcInvokeInfo (Documented below);
2. Pre- or post-fix the method name with "RPC" (case insensitive);
3. Add the [Rpc] attribute in front of the method declaration; and,
4. Configure the RpcSources and RpcTargets parameters to control where the RPC may be called from and where it gets executed.

C#

[Rpc(sources: RpcSources.InputAuthority, targets: RpcTargets.StateAuthority)]
public void RPC_Configure(string name, Color color){
    playerName = name;
    playerColor = color;
}

Static RPC

Static RPCs follow slightly different rules, they:

• ignore the RpcSources and RpcTargets parameters; and
• require the first parameter of the method to be NetworkRunner.

Because there is no source and target filter, static RPCs can be called from any client and will be sent to all clients. Do note that you can still target the RPC to a specific PlayerRef (See "Targeted RPC") to control who will receive the call.

C#

[Rpc]
public static void Rpc_MyStaticRpc(NetworkRunner runner, int a) { }

RPC Attribute Parameters

Sources and Targets

RpcSources and RpcTargets are filters. The RpcSources define which peers can send the RPC, whereas the RpcTargets define on which it is executed.

• All: can be sent / is executed by all peers in the session (including the client calling the RPC).
• Proxies: can be sent / is executed by a peer who does not have State Authority over the object.
• StateAuthority: can be sent / is executed by the peer with State Authority over the object.

IMPORTANT: RPCs do not have an explicit state. Clients who late-join and clients who disconnect & reconnect will forget it ever happened. It is therefore crucial to ensure an RPC is either:

• truly transient without any state (e.g. a chat message); or,
• has its effect indirectly recorded in a [Networked] property.

C#

public class Player : NetworkBehaviour {
    [Networked] public string playerName { get; set; }
    [Networked] public Color playerColor { get; set; }
    
    [Rpc(RpcSources.InputAuthority, RpcTargets.StateAuthority)]
    public void RPC_Configure(string name, Color color)    {
        playerName = name;
        playerColor = color;
    }
}

Allowed Types

The following types are supported by RPCs

• Primitives: byte, short, int, long, ushort, uint, ulong, float, double, bool
• Unity Types: Vector2, Vector3, Vector4, Quaternion, Vector2Int, Vector3Int, Rect, RectInt Color, Color32
• Fusion Types: NetworkObject, NetworkBehaviour, NetworkString<>, NetworkBool, Angle, NetworkId, PlayerRef, SceneRef, TickTimer
• Strings
• Structs implementing INetworkStruct
• Arrays of supported types. E.g. Int[].

Targeted Rpc

When an RPC is meant to be exclusively executed on a specific player's machine, targeted RPCs are used. Both Instance RPCs and Static RPCs can be turned into targeted RPCs by adding a PlayerRef parameter prefaced by the [RpcTarget] attribute. A typical use-case is team chat where a message is only meant for the specific players on one's own team.