This page is a work in progress and could be pending updates.

Remote Procedure Calls

Introduction

Remote Procedure Calls, simply referred to as RPCs, are ideal for sharing punctual game events; in contrast the Input Struct and [Networked] properties are the go-to solutions for sharing state between network clients that are undergoing continuous change.

For example when a player wants to perform a rare complex interaction with an object that it does not have Input Authority over such as using a specific key from their inventory inventory to open a locked door. Although the actions can technically be achieved by including additional fields as part of the input, it would clutter the Input Struct and make it unwieldy. Furthermore, Input Struct are sent as unreliable messages, i.e. packets may be lost. This is rarely noticeable for things requiring continuous input (e.g. character movement), but will be harmful to player experience when this affects single one-time actions which players expect to be guaranteed. In this situation a Remote Procedure Call is the best practice.

Back To Top

Setup

Fusion has a simple yet powerful syntax for RPCs. There are genereally speaking 3 types of RPCs:

  1. Instance RPCs;
  2. Static RPCs; and,
  3. Targeted RPCs.

Each one of these types will be presented in the following sections.

Back To Top

Instance 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;
  2. Add the [Rpc] attribute in front of the method declaration; and,
  3. Configure the RpcSources and RpcTargets parameters to control where the RPC may be called from and where it gets executed.
[Rpc(source: RpcSources.InputAuthority, target: RpcTargets.StateAuthority)]
public void RPC_Configure(string name, Color color){
    playerName = name;
    playerColor = color;
}

A RPC can take any parameter which respects the type constraints outlined in Network Object > NetworkBehaviour > Networked State > Constraints entry.

Note: The use of the RPC_ prefix on the method is a convention to facilitate searching and identifying RPCs in the codebase.

Back To Top

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.
[Rpc(InvokeLocal = true)] 
public static void Rpc_MyStaticRpc(NetworkRunner runner, int a) { }

Back To Top

RPC Attribute Parameters

Sources And Targets

RpcSources and RpcTargets are filters. The RpcSources define which peer 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 server).
  • Proxies: can be sent / is executed by a peer who does not have either Input Authority or State Authority over the object.
  • InputAuthority: can be sent / is executed by the peer with Input 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. Setting RpcTargets.All will NOT transmit the information to clients who late-join and clients who disconnect & reconnect will forget it ever happened. It is therefore crucial to ensure a RPC is either:

  • truly transient without any state (e.g. a chat message); or,
  • has its effect indirectly recorded in a [Networked] property.
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;
    }
}

Back To Top

Optional RPC Attribute Parameters

In addition to the mandatory RpcSources and RpcTargets properties, the [Rpc] attribute offers several optional parameters.

  • Channel (default Reliable): Set to Unreliable if the RPC can be lost in transmission.
  • InvokeLocal (default true): Set to false if the RPC is not to be invoked on the local client.
  • InvokeResim (default false): Set to true if the RPC is not to be invoked during re-simulations.
[Rpc (RpcSources.All, RpcTargets.All, InvokeLocal = true, InvokeResim = true )]
void RpcStartBoost(){
    m_BoostAnim.StartBoostAnimation();
}

Back To Top

RPC Method Parameters

RpcInfo

RPC method declarations can take a optional parameter of type RpcInfo. This allows to read out additional information about the RPC.

  • Tick: at which tick was it sent.
  • Source: which player (PlayerRef) sent it.
  • Channel: was it sent as an Unreliable or Reliable RPC.
  • IsInvokeLocal: was it the local player who originally invoked this RPC.
[Rpc(source: RpcSources.InputAuthority, target: RpcTargets.StateAuthority)]
public void RPC_Configure(string name, Color color, RpcInfo info = default){
    playerName = name;
    playerColor = color;
}

The parameter is always declared as RpcInfo info = default.

Back To Top

Targeted Rpc

When a RPC is meant to be exclusively executed on a specific player's machine, so called 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 usecase is team chat where a message is only meant for the specific players on one's own team.

[Rpc(source: RpcSources.InputAuthority, target: RpcTargets.StateAuthority)]
public void Rpc_TargetedInstanceMessage([RpcTarget] PlayerRef player, string message){}

[Rpc(InvokeLocal = true)]
public static void Rpc_MyTargetedStaticMessage(NetworkRunner runner, [RpcTarget] PlayerRef player, string message) { };

IMPORTANT: The [RpcTarget] attribute used within the method the declaration is DIFFERENT from the RpcTargets parameter inside the [Rpc] attribute placed in front of the method declaration.

To Document Top