Add invocation order documentation

Author: EmandM

com.unity.netcode.gameobjects/Documentation~/advanced-topics/message-system/rpc.md

@@ -215,6 +215,116 @@ There are a few other parameters that can be passed to either the `Rpc` attribut
 | `Target`         | Runtime override destination for the RPC. (See above for more details.) Populating this value will throw an exception unless either the `SendTo` value for the RPC is `SendTo.SpecifiedInParams`, or `AllowTargetOverride` is `true`.<br /><br />Default: `null` |
 | `LocalDeferMode` | Overrides the `DeferLocal` value. `DeferLocalMode.Defer` causes this particular invocation of this RPC to be deferred until the next frame even if `DeferLocal` is `false`, while `DeferLocalMode.SendImmediate` causes the RPC to be executed immediately on the local machine even if `DeferLocal` is `true`. `DeferLocalMode.Default` does whatever the `DeferLocal` value in the attribute is configured to do.<br /><br />Options: `DeferLocalMode.Default`, `DeferLocalMode.Defer`, `DeferLocalMode.SendImmediate`<br />Default: `DeferLocalMode.Default` |
 
+## Invocation order
+
+Rpc message sent with `RpcDelivery.Reliable` will be sent and invoked on other game clients in the same order as they were called on the local game client.
+
+```csharp
+[Rpc(SendTo.Server)]
+public void OpenDoorRpc(int doorId, RpcParams rpcParams)
+{
+    Debug.Log($"client {rpcParams.Receive.SenderClientId} has opened door {doorId}");
+
+    // Server can handle door opening here
+}
+
+[Rpc(SendTo.Server)]
+void OpenChestRPC(int chestId, RpcParams rpcParams)
+{
+    Debug.Log($"client {rpcParams.Receive.SenderClientId} has opened chest {chestId}");
+
+    // Server can handle door opening here
+}
+
+void Update()
+{
+    if (IsClient && Input.GetKeyDown(KeyCode.O))
+    {
+        OpenDoorRpc(1)
+        OpenDoorRpc(2)
+        OpenChestRpc(5)
+    }
+
+    // Other clients will log:
+    //
+    // "client 1 has opened door 1"
+    // "client 1 has opened door 2"
+    // "client 1 has opened chest 5"
+}
+```
+
+> [!Warning]
+> Invocation order is not guaranteed with nested RPC invocations that include targets that may invoke locally. Invocation order is also not guaranteed when using `RpcDelivery.Unreliable`
+
+### Deferring local invocation
+
+Invoking an RPC from within another RPC introduces the risk that the local RPC may invoke before messages are sent to other game clients. This will result in the RPC message for the inner RPC invocation being sent before the message for the outer RPC.
+
+```csharp
+[Rpc(SendTo.Everyone)]
+public void TryOpenDoorRpc(int doorId, RpcParams rpcParams)
+{
+    Debug.Log($"client {rpcParams.Receive.SenderClientId} is trying to open door {doorId}");
+
+    if (HasAuthority) {
+      // Authority handles opening the door here
+
+      // If the authority is invoking TryOpenDoorRpc locally before the authority has sent TryOpenDoorRpc to other clients, OpenDoorRpc will be sent before TryOpenDoorRpc.
+      OpenDoorRpc(doorId);
+    }
+}
+
+[Rpc(SendTo.Everyone)]
+public void OpenDoorRpc(int doorId, RpcParams rpcParams)
+{
+    Debug.Log($"client {rpcParams.Receive.SenderClientId} marked door {doorId} as open");
+}
+
+void Update()
+{
+    if (Input.GetKeyDown(KeyCode.O))
+    {
+        // Invocation of TryOpenDoorRpc and OpenDoorRpc may be inverted depending on the context in which TryOpenDoorRpc is invoked
+        TryOpenDoorRpc(20);
+    }
+}
+```
+
+Use the RPC `LocalDeferMode` to resolve issue. Configuring the RPC to be deferred when invoked locally will ensure that any outer RPC messages are always sent before the inner function is invoked.
+
+```csharp
+// An RPC can be configured to defer the local invocation in the attribute definition
+[Rpc(SendTo.Everyone, DeferLocal = true)]
+public void TryOpenDoorRpc(int doorId, RpcParams rpcParams = default)
+{
+    Debug.Log($"client {rpcParams.Receive.SenderClientId} is trying to open door {doorId}");
+
+    if (HasAuthority) {
+
+      // Authority handles opening the door here
+
+      // Defer mode can also be passed in at the call site.
+      OpenDoorRpc(doorId, LocalDeferMode.Defer);
+    }
+}
+
+[Rpc(SendTo.Everyone)]
+public void OpenDoorRpc(int doorId, RpcParams rpcParams = default)
+{
+    Debug.Log($"client {rpcParams.Receive.SenderClientId} marked door {doorId} as open");
+}
+
+void Update()
+{
+    if (Input.GetKeyDown(KeyCode.O))
+    {
+        // TryOpenDoorRpc is defined with DeferLocal
+        // DeferLocal ensures that RPC messages are sent to all other targets before the RPC is invoked locally
+        TryOpenDoorRpc(20);
+    }
+}
+```
+
 ## Additional resources
 
 * [RPC parameters](rpc-params.md)

com.unity.netcode.gameobjects/Runtime/Messaging/RpcParams.cs

@@ -9,8 +9,12 @@ namespace Unity.Netcode
     public enum LocalDeferMode
     {
         /// <summary>
-        /// Uses the default behavior for RPC message handling
+        /// Uses the default behavior for RPC message handling.
+        /// The default behavior is <see cref="SendImmediate"/>.
         /// </summary>
+        /// <remarks>
+        /// If <see cref="RpcAttribute.RpcAttributeParams.DeferLocal"/> is enabled, the behavior of this field wil change to <see cref="Defer"/>.
+        /// </remarks>
         Default,
 
         /// <summary>
@@ -25,7 +29,7 @@ public enum LocalDeferMode
     }
 
     /// <summary>
-    /// Generic RPC. Defines parameters for sending Remote Procedure Calls (RPCs) in the network system
+    /// Defines parameters for sending Remote Procedure Calls (RPCs) in the network system
     /// </summary>
     public struct RpcSendParams
     {
@@ -55,31 +59,29 @@ public struct RpcSendParams
     }
 
     /// <summary>
-    /// The receive parameters for server-side remote procedure calls
+    /// The receive parameters for an RPC call
     /// </summary>
     public struct RpcReceiveParams
     {
         /// <summary>
-        /// Server-Side RPC
-        /// The client identifier of the sender
+        /// The sender's client identifier
         /// </summary>
         public ulong SenderClientId;
     }
 
     /// <summary>
-    /// Server-Side RPC
-    /// Can be used with any sever-side remote procedure call
-    /// Note: typically this is use primarily for the <see cref="ServerRpcReceiveParams"/>
+    /// Parameters for an RPC call
+    /// Can be used with any remote procedure call
     /// </summary>
     public struct RpcParams
     {
         /// <summary>
-        /// The server RPC send parameters (currently a place holder)
+        /// The RPC send parameters (currently a place holder)
         /// </summary>
         public RpcSendParams Send;
 
         /// <summary>
-        /// The client RPC receive parameters provides you with the sender's identifier
+        /// The RPC receive parameters provides you with the sender's identifier
         /// </summary>
         public RpcReceiveParams Receive;