Develop into main (#1264)

Author: jabbacakes

docs/advanced-topics/connection-events.md

@@ -1,11 +1,12 @@
 ---
 id: connection-events
 title: Connection events
-sidebar_label: Connection events
 
 ---
 
-When you need to react to connection or disconnection events for yourself and other clients, you can use `NetworkManager.OnConnectionEvent` as a unified source of information about changes to the network topology. `OnConnectionEvent` will receive a `ConnectionEventData` struct detailing the relevant information about the connection state change:
+When you need to react to connection or disconnection events for yourself or other clients, you can use `NetworkManager.OnConnectionEvent` as a unified source of information about changes in the network. Connection events are session-mode agnostic and work in both [client-server](../terms-concepts/client-server.md) and [distributed authority](../terms-concepts/distributed-authority.md) contexts.
+
+`OnConnectionEvent` receives a `ConnectionEventData` struct detailing the relevant information about the connection state change:
 
 ```csharp
 public enum ConnectionEvent

docs/advanced-topics/message-system/rpc.md

@@ -1,77 +1,70 @@
 ---
 id: messaging-system
 title: Sending events with RPCs
-description: An introduction to the messaging system in Unity MLAPI, including RPC's and Custom Messages.
 ---
 import ImageSwitcher from '@site/src/ImageSwitcher.js';
 
-Netcode for GameObjects (Netcode) has two parts to its messaging system: RPCs and [Custom Messages](message-system/custom-messages.md). Both types have sub-types that change their behaviour, functionality, and performance. This page will focus on RPCs.
+Netcode for GameObjects has two parts to its messaging system: [remote procedure calls (RPCs)](message-system/rpc.md) and [custom messages](message-system/custom-messages.md). Both types have sub-types that change their behavior, functionality, and performance. RPCs as implemented in Netcode for GameObjects are session-mode agnostic, and work in both [client-server](../terms-concepts/client-server.md) and [distributed authority](../terms-concepts/distributed-authority.md) contexts.
 
-## RPC: Remote Procedure Call
+This page provides an introduction to RPCs. For more details, refer to the pages listed in the [RPCs in Netcode for GameObjects section](#rpcs-in-netcode-for-gameobjects)
 
-The concept of an `RPC` is common not only in video games but in the software industry in general. They're ways to call methods on objects that aren't in the same executable.
+## Remote procedure calls (RPCs)
+
+RPCs are a standard software industry concept. They're a way to call methods on objects that aren't in the same executable.
 
 <figure>
 <ImageSwitcher
 lightImageSrc="/sequence_diagrams/RPCs/ServerRPCs.png?text=LightMode"
 darkImageSrc="/sequence_diagrams/RPCs/ServerRPCs_Dark.png?text=DarkMode"/>
-  <figcaption>Client can invoke a server RPC on a Network Object. The RPC will be placed in the local queue and then sent to the server, where it will be executed on the server version of the same Network Object.</figcaption>
+  <figcaption>Client can invoke a server RPC on a NetworkObject. The RPC is placed in the local queue and then sent to the server, where it's executed on the server version of the same NetworkObject.</figcaption>
 </figure>
 
-At a high level, when calling an `RPC` client side, the SDK will take a note of the object, component, method and any parameters for that `RPC` and send that information over the network. The server will receive that information, find the specified object, find the specified method and call it on the specified object with the received parameters.
-
-When calling an `RPC`, you call a method remotely on an object that can be anywhere in the world. They're "events" you can trigger when needed.
+When calling an RPC from a client, the SDK takes note of the object, component, method, and any parameters for that RPC and sends that information over the network. The server or distributed authority service receives that information, finds the specified object, finds the specified method, and calls it on the specified object with the received parameters.
 
-If you call an `RPC` method on your side, it will execute on a different machine.
-
-Netcode includes multiple RPC variations that you can use to execute logic with various remote targets. To learn more about RPCs, refer to[`Rpc`](message-system/rpc.md).
+Netcode for GameObjects includes multiple RPC variations that you can use to execute logic with various remote targets.
 
 <figure>
 <ImageSwitcher
 lightImageSrc="/sequence_diagrams/RPCs/ClientRPCs.png?text=LightMode"
 darkImageSrc="/sequence_diagrams/RPCs/ClientRPCs_Dark.png?text=DarkMode"/>
- <figcaption>Server can invoke a client RPC on a Network Object. The RPC will be placed in the local queue and then sent to a selection of clients (by default this selection is "all clients"). When received by a client, RPC will be executed on the client's version of the same Network Object.</figcaption>
+ <figcaption>Server can invoke a client RPC on a NetworkObject. The RPC is placed in the local queue and then sent to a selection of clients (by default this selection is all clients). When received by a client, RPCs are executed on the client's version of the same NetworkObject.</figcaption>
 </figure>
 
+### RPCs in Netcode for GameObjects
 
-:::info
-For more information see the wikipedia entry on [Remote Procedure Call's](https://en.wikipedia.org/wiki/Remote_procedure_call).
-:::
-
-### Netcode's RPCs
-
-See the following pages for more information:
+Refer to the following pages for more information about how RPCs are implemented in Netcode for GameObjects.
 
-- [Rpc](message-system/rpc.md)
+- [Remote procedure calls (RPCs)](message-system/rpc.md)
 - [Reliability](message-system/reliabilty.md)
-- [Execution Table](message-system/execution-table.md)
-- [RPC Params](message-system/rpc-params.md)
-  - [Serialization Types and RPCs](message-system/../serialization/serialization-intro.md)
+- [RPC parameters](message-system/rpc-params.md)
+  - [Serialization types and RPCs](message-system/../serialization/serialization-intro.md)
 
-There is also some additional design advice on RPC's and some usage examples on the following pages:
+There's also some additional design advice on RPCs and some usage examples on the following pages:
 
 - [RPC vs NetworkVariable](../learn/rpcvnetvar.md)
 - [RPC vs NetworkVariables Examples](../learn/rpcnetvarexamples.md)
 
-:::note Migration and Compatibility
-See [RPC Migration and Compatibility](message-system/rpc-compatibility.md) for more information on updates, cross-compatibility, and deprecated methods for Unity RPC.
+:::note Migration and compatibility
+Refer to [RPC migration and compatibility](message-system/rpc-compatibility.md) for more information on updates, cross-compatibility, and deprecated methods for Unity RPC.
 :::
 
 ## RPC method calls
 
 A typical SDK user (Unity developer) can declare multiple RPCs under a `NetworkBehaviour` and inbound/outbound RPC calls will be replicated as a part of its replication in a network frame.
 
-A method turned into an RPC is no longer a regular method, it will have its own implications on direct calls and in the network pipeline. See [Execution Table](message-system/execution-table.md).
+A method turned into an RPC is no longer a regular method; it will have its own implications on direct calls and in the network pipeline.
+
+### RPC usage checklist
+
+To use RPCs, make sure:
 
-### RPC usage checklist:
-To use RPCs, make sure
--  ```[Rpc]``` attributes are on your method
-- Your method name ends with ```Rpc``` (ex: ```DoSomethingRpc()```)
-- your method is declared in a class that inherits from NetworkBehaviour
-  - your GameObject has a NetworkObject component attached
+-  `[Rpc]` attributes are on your method
+- Your method name ends with `Rpc` (for example, `DoSomethingRpc()`)
+- Your method is declared in a class that inherits from `NetworkBehaviour`
+  - Your GameObject has a NetworkObject component attached
 
-## Serialization Types and RPCs
+## Serialization types and RPCs
 
-Instances of Serializable Types are passed into an RPC as parameters and are serialized and replicated to the remote side.
+Instances of serializable types are passed into an RPC as parameters and are serialized and replicated to the remote side.
 
-See [Serialization](serialization/serialization-intro.md) for more information.
+Refer to the [serialization page](serialization/serialization-intro.md) for more information.

docs/advanced-topics/messaging-system.md

@@ -66,3 +66,5 @@ While `NetworkTransform` offers interpolation as a way to smooth between delta s
 To have a client control their owned objects, you can use either [RPCs](message-system/rpc.md) or [NetworkVariables](../basics/networkvariables.md) on the client-side. However, this often results in the host-client's updates working as expected, but with slight jitter when a client sends updates. You might be scanning for key or device input during the `Update` to `LateUpdate` stages. Any input from the host player is applied after the `FixedUpdate` stage (i.e. physics simulation for the frame has already run), but input from client players is sent via a message and processed, with a half RTT delay, on the host side (or processed 1 network tick + half RTT if using NetworkVariables). Because of when messages are processed, client input updates run the risk of being processed during the `EarlyUpdate` stage which occurs just before the current frame's `FixedUpdate` stage.
 
 To avoid this kind of scenario, it's recommended that you apply any changes received via messages to a Rigidbody _after_ the FixedUpdate has run for the current frame. If you [look at how `NetworkTransform` handles its changes to transform state](https://github.com/Unity-Technologies/com.unity.netcode.gameobjects/blob/a2c6f7da5be5af077427eef9c1598fa741585b82/com.unity.netcode.gameobjects/Components/NetworkTransform.cs#L3028), you can see that state updates are applied during the `Update` stage, but are received during the `EarlyUpdate` stage. Following this kind of pattern when synchronizing changes to a Rigidbody via messages will help you to avoid unexpected results in your Netcode for GameObjects project.
+
+The best way to address the issue of physics latency is to create a custom `NetworkTransform` with a custom physics-based interpolator. You can also use the [Network Simulator tool](../../tools/network-simulator.md) to spot issues with latency.

docs/advanced-topics/physics.md

@@ -69,7 +69,6 @@ To serialize a `NativeArray` container, use `serializer.SerializeValue(ref Array
 ### `NativeList<T>`
 
 To serialize a `NativeList` container, you must:
-
 1. Ensure your assemblies reference `Collections`.
 2. You must add `UNITY_NETCODE_NATIVE_COLLECTION_SUPPORT` to your **Scriptiong Define Symbols** list.
    1. From the Unity Editor top bar menu, go to **Edit** > **Project Settings...** > **Player**.

docs/advanced-topics/serialization/serialization-arrays.md

@@ -3,41 +3,46 @@ id: ways-synchronize
 title: Synchronizing states and events
 ---
 
-## Introduction
-Netcode for GameObjects (Netcode) includes three options for synchronizing game states and/or events:
-- Messaging System
-    - Remote Procedure Calls (RPCs)
-    - Custom Messages
-- NetworkVariables
-    - Handled by the "internal" messaging system and [categorized under "Networking".](../basics/networkvariable.md)
+Netcode for GameObjects has three options for synchronizing game states and events:
 
-While each of the above options can be used for the same thing, synchronizing states or events, they all have specific use cases and limitations.
+- Messaging system
+    - [Remote procedure calls (RPCs)](message-system/rpc.md)
+    - [Custom messages](message-system/custom-messages.md)
+- [NetworkVariables](../basics/networkvariable.md)
+    - Handled by the internal messaging system
 
-## Messaging System
-The Netcode messaging system provides you with the ability to handle sending and receiving messages or events.  The entire messaging system supports the serialization of most primitive value `type`s as well as any classes and/or structures that implement the `INetworkSerializable` interface.
+While each of these options can be used to synchronize states or events, they all have specific use cases and limitations.
 
-### Remote Procedure Calls
-RPCs can be viewed as a way to send an event notification as well as a way to handle direct communication between a server and a client (or vice versa).  This is sometimes useful when the ownership scope of the `NetworkBehavior`, that the remote procedure call is declared within, belongs to the server but you still want one or more clients to be able to communicate with the associated `NetworkObject`.  
-**Some Usage Examples:**
-- An Rpc with `SendTo.Server` can be used by a client to notify the server that the player is trying to use a world object (that is, a door, a vehicle, etc.)
-- A second Rpc with `SendTo.SpecifiedInParams` can be used by a server to notify a specific client of a special reconnection key or some other player specific information that doesn't require its state to be synchronized with all current and any future late joining client(s).
+## Messaging system
 
-**The are several types of RPC methods,** but most are circumstantial. The ones you are most likely to use are:
+The Netcode for GameObjects messaging system allows you to send and receive messages or events. The system supports the serialization of most primitive value `type`s as well as any classes and/or structures that implement the `INetworkSerializable` interface.
 
-- **Rpc(SendTo.Server):** A remote procedure call received by and executed on the server-side.
-- **Rpc(SendTo.NotServer):** A remote procedure call received by and executed on the client side. Note that this does NOT execute on the host, as the host is also the server.
-- **Rpc(SendTo.ClientsAndHost):** A remote procedure call received by and executed on the client side. If the server is running in host mode, this RPC will also be executed on the server (the host client).
-- **Rpc(SendTo.SpecifiedInParams):** A remote procedure call that will be sent to a list of client IDs provided as parameters at runtime. (By default, other `SendTo` values cannot have any client IDs passed to them to change where they are being sent, but this can also be changed by passing `AllowTargetOverride = true` to the `Rpc` attribute.
+### Remote procedure calls (RPCs)
 
-RPCs have no limitations on who can send them - the server can invoke an RPC with `SendTo.Server`, a client can invoke an RPC with `SendTo.NotServer`, etc. If an RPC is invoked in a way that would cause it to be received by the same process that invoked it, it will be executed immediately in that process by default. Passing `DeferOverride = true` to the `Rpc` attribute will change this behavior and the RPC will be invoked at the start of the next frame.
+RPCs are a way of sending an event notification as well as a way of handling direct communication between a server and a client, or between clients and the [distributed authority service](../terms-concepts/distributed-authority.md). This is sometimes useful when the ownership scope of the `NetworkBehavior`, that the remote procedure call is declared within, belongs to the server but you still want one or more clients to be able to communicate with the associated `NetworkObject`.  
 
-[Read More About Rpcs](../advanced-topics/message-system/rpc.md)
+Usage examples:
 
-### Custom Messages
-Custom messages provide you with the ability to create your own "netcode message type" to handle scenarios where you might just need to create your own custom message.
-[Read More About Custom Messages](../advanced-topics/message-system/custom-messages.md)
+- An RPC with `SendTo.Server` can be used by a client to notify the server that the player is trying to use a world object (such as a door or vehicle).
+- An RPC with `SendTo.SpecifiedInParams` can be used by a server to notify a specific client of a special reconnection key or some other player-specific information that doesn't require its state to be synchronized with all current and any future late-joining client(s).
 
-## NetworkVariable System
-A NetworkVariable is most commonly used to synchronize state between both connected and late joining clients. The `NetworkVariable` system only supports non-nullable value `type`s, but also provides support for `INetworkSerializable` implementations as well you can create your own `NetworkVariable` class by deriving from the `NetworkVariableBase` abstract class. If you want something to always be synchronized with current and late-joining clients, then it's likely a good `NetworkVariable` candidate.
+There are many RPC methods, as outlined on the [RPC page](message-system/rpc.md#rpc-targets). The most commonly used are:
 
-[Read More About NetworkVariable](../basics/networkvariable.md)
+- `Rpc(SendTo.Server)`: A remote procedure call received by and executed on the server side.
+- `Rpc(SendTo.NotServer)`: A remote procedure call received by and executed on the client side. Note that this does NOT execute on the host, as the host is also the server.
+- `Rpc(SendTo.ClientsAndHost)`: A remote procedure call received by and executed on the client side. If the server is running in host mode, this RPC will also be executed on the server (the host client).
+- `Rpc(SendTo.SpecifiedInParams)`: A remote procedure call that will be sent to a list of client IDs provided as parameters at runtime. By default, other `SendTo` values cannot have any client IDs passed to them to change where they are being sent, but this can also be changed by passing `AllowTargetOverride = true` to the `Rpc` attribute.
+
+RPCs have no limitations on who can send them: the server can invoke an RPC with `SendTo.Server`, a client can invoke an RPC with `SendTo.NotServer`, and so on. If an RPC is invoked in a way that would cause it to be received by the same process that invoked it, it will be executed immediately in that process by default. Passing `DeferOverride = true` to the `Rpc` attribute will change this behavior and the RPC will be invoked at the start of the next frame.
+
+Refer to the [RPC page](../advanced-topics/message-system/rpc.md) for more details.
+
+### Custom messages
+
+Custom messages provide you with the ability to create your own message type. Refer to the [custom messages page](../advanced-topics/message-system/custom-messages.md) for more details.
+
+## NetworkVariables
+
+A NetworkVariable is most commonly used to synchronize state between both connected and late-joining clients. The `NetworkVariable` system only supports non-nullable value `type`s, but also provides support for `INetworkSerializable` implementations as well. You can create your own `NetworkVariable` class by deriving from the `NetworkVariableBase` abstract class. If you want something to always be synchronized with current and late-joining clients, then it's likely a good `NetworkVariable` candidate.
+
+Refer to the [NetworkVariable page](../basics/networkvariable.md) for more details.