Develop into main to publish NGO 2.3.0 (#1464)

Author: jabbacakes

docs/advanced-topics/networkobject-parenting.md

@@ -25,6 +25,37 @@ If you aren't completely familiar with transform parenting in Unity, then it's h
   - When `OnNetworkObjectParentChanged` is invoked, on the server side, adjust the child's transform values within the overridden method.
   - Netcode for GameObjects will then synchronize all clients with the child's parenting and transform changes.
 
+### Parenting, distributed authority, and NetworkObject redistribution
+
+Parenting within a [distributed authority](../terms-concepts/distributed-authority.md) network topology follows the same rules as outlined above, with the exception that you can change any references to the server with references to authority.
+ 
+#### Rule adjustments
+
+  - Whichever client has authority over a NetworkObject can control its parenting. 
+  - You can parent under mixed authority. This means that Client-B can parent a NetworkObject it has authority over under another NetworkObject that Client-A has authority over.
+
+#### Distributable permissions and child hierarchies
+
+- **When a client disconnects:**
+  - Any root parent with [distributable permission](../basics/ownership.md#ownership-permission-settings) set that was owned by the disconnected client is redistributed.
+    - If the root parent was locked when the client disconnected, then it's unlocked prior to redistributing.
+    - Children of the root parent change ownership with the root parent only if:
+      - The child was owned by the client that disconnected.
+      - The child has either the distributable or transferable permission set.
+    - If a child's ownership permission is locked, it's unlocked prior to redistributing.
+    - Any child of the root parent that's owned by a different client won't get redistributed.
+- **When a client connects:**
+  - Any root parent with [distributable permission](../basics/ownership.md#ownership-permission-settings) set that doesn't have ownership locked is considered for redistribution.
+    - If a root parent is redistributed to a newly connecting client then:
+      - Any child under the root parent that has the same owner as the root parent changes ownership with the root parent.
+        - Unless the child has ownership locked.
+    - Any child under the root parent that has the distributable or transferrable permission set can be redistributed as well.
+      - Unless the child has ownership locked.
+
+#### Distributable permissions and in-scene placed `NetworkObject` instances:
+By default, any root in-scnee placed `NetworkObject` instance will have the `Distributable` permissions flag unless it already has the `SessionOwner` permission flag set. This assures in-scene placed `NetworkObject` instances will always distributed amongst clients or a newly promoted session owner.
+
+
 :::tip
 When a NetworkObject is parented, Netcode for GameObjects synchronizes both the parenting information along with the child's transform values. Netcode for GameObjects uses the `WorldPositionStays` setting to decide whether to synchronize the local or world space transform values of the child NetworkObject component. This means that a NetworkObject component doesn't require you to include a NetworkTransform component if it never moves around, rotates, or changes its scale when it isn't parented. This can be beneficial for world items a player might pickup (parent the item under the player) and the item in question needs to adjustment relative to the player when it's parented or the parent is removed (dropped). This helps to reduce the item's over-all bandwidth and processing resources consumption.
 :::

docs/advanced-topics/transports.md

@@ -20,7 +20,7 @@ A transport layer can provide:
 
 ## Unity Transport package
 
-Netcode's default transport Unity Transport is an entire transport layer that you can use to add multiplayer and network features to your project with or without Netcode. See the Transport [documentation](../../../transport/current/about) for more information and how to [install](../../../transport/current/install).
+Netcode's default transport Unity Transport is an entire transport layer that you can use to add multiplayer and network features to your project with or without Netcode. Refer to the [Transport documentation](https://docs-multiplayer.unity3d.com/transport/current/about/) for more information and how to [install the Transport package](https://docs-multiplayer.unity3d.com/transport/current/install/).
 
 ## Unity's UNet Transport Layer API
 

docs/basics/networkvariable.md

@@ -5,14 +5,15 @@ title: NetworkVariables
 
 `NetworkVariable`s are a way of synchronizing properties between servers and clients in a persistent manner, unlike [RPCs](../advanced-topics/message-system/rpc.md) and [custom messages](../advanced-topics/message-system/custom-messages.md), which are one-off, point-in-time communications that aren't shared with any clients not connected at the time of sending. `NetworkVariable`s are session-mode agnostic and can be used with either a [client-server](../terms-concepts/client-server.md) or [distributed authority](../terms-concepts/distributed-authority.md) network topology.
 
-`NetworkVariable` is a wrapper of the stored value of type `T`, so you need to use the `NetworkVariable.Value` property to access the actual value being synchronized. A `NetworkVariable` is synchronized with:
+`NetworkVariable` is a wrapper of the stored value of type `T`, so you need to use the `NetworkVariable.Value` property to access the actual value being synchronized. A `NetworkVariable` handles value synchronization for:
 
 * New clients joining the game (also referred to as late-joining clients)
-    * When the associated NetworkObject of a `NetworkBehaviour` with `NetworkVariable` properties is spawned, any `NetworkVariable`'s current state (`Value`) is automatically synchronized on the client side.
-* Connected clients
-    * When a `NetworkVariable` value changes, all connected clients that subscribed to the `NetworkVariable.OnValueChanged` event (prior to the value being changed) are notified of the change. Two parameters are passed to any `NetworkVariable.OnValueChanged` subscribed callback method:
-        - First parameter (Previous): The previous value before the value was changed
-        - Second parameter (Current): The newly changed `NetworkVariable.Value`
+* All connected clients during the game
+
+When using a [distributed authority](../terms-concepts/distributed-authority.md) network topology, A `NetworkVariable` ensures value synchronization is handled during:
+
+* Ownership changes of the associated NetworkObject
+* Object redistribution during client connection or disconnection
 
 You can use `NetworkVariable` [permissions](#permissions) to control read and write access to `NetworkVariable`s. You can also create [custom `NetworkVariable`s](custom-networkvariables.md).
 
@@ -25,13 +26,16 @@ You can use `NetworkVariable` [permissions](#permissions) to control read and wr
 - A `NetworkVariable`'s value can only be set:
     - When initializing the property (either when it's declared or within the Awake method).
     - While the associated NetworkObject is spawned (upon being spawned or any time while it's still spawned).
+- A `NetworkVariable` can't be defined with the `static` keyword. Variables defined with the static keyword have a lifetime that lasts for the entire runtime of an application, rather than the much shorter lifetime of a `GameObject`. This results in incorrect and invalid state management where `NetworkVariable`s don't behave as expected.
 
-###  Initializing a NetworkVariable
+### Initializing a NetworkVariable
 
-When a client first connects, it's synchronized with the current value of the `NetworkVariable`. Typically, clients should register for `NetworkVariable.OnValueChanged` within the `OnNetworkSpawn` method. A `NetworkBehaviour`'s `Start` and `OnNetworkSpawn` methods are invoked based on the type of NetworkObject the `NetworkBehaviour` is associated with:   
+When a NetworkObject with an associated `NetworkBehaviour` with `NetworkVariable` properties is spawned, the `NetworkVariable` is initialized and associated with its relevant `NetworkBehaviour`. When any new client connects, it's synchronized with the current value of the `NetworkVariable` before the `NetworkBehaviour.OnNetworkSpawn` is invoked.
+
+`NetworkVariable`s are initialized during the associated `NetworkBehaviour` initialization. The [Start](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/MonoBehaviour.Start.html) and `OnNetworkSpawn` methods are invoked based on the type of NetworkObject the `NetworkBehaviour` is associated with:
 
 - In-scene placed: Since the instantiation occurs via the scene loading mechanism(s), the `Start` method is invoked before `OnNetworkSpawn`.
-- Dynamically spawned: Since `OnNetworkSpawn` is invoked immediately (that is, within the same relative call-stack) after instantiation, the `Start` method is invoked after `OnNetworkSpawn`.  
+- Dynamically spawned: Since `OnNetworkSpawn` is invoked immediately (that is, within the same relative call-stack) after instantiation, the `Start` method is invoked after `OnNetworkSpawn`.
 
 Typically, these methods are invoked at least one frame after the NetworkObject and associated `NetworkBehaviour` components are instantiated. The table below lists the event order for dynamically spawned and in-scene placed objects respectively.
 
@@ -43,8 +47,17 @@ Start               | OnNetworkSpawn
 
 You should only set the value of a `NetworkVariable` when first initializing it or if it's spawned. It isn't recommended to set a `NetworkVariable` when the associated NetworkObject isn't spawned.
 
+### Using a NetworkVariable
+
+After initialization, subscribing to the `NetworkVariable.OnValueChanged` event notifies connected clients of value changes. Clients must be subscribed to this event prior to the value being changed. Typically, clients should register for `NetworkVariable.OnValueChanged` within the `OnNetworkSpawn` method.
+
+Two parameters are passed to any `NetworkVariable.OnValueChanged` subscribed callback method:
+
+- First parameter (Previous): The previous value before the value was changed
+- Second parameter (Current): The newly changed `NetworkVariable.Value`
+
 :::tip
-If you need to initialize other components or objects based on a `NetworkVariable`'s initial synchronized state, then you can use a common method that's invoked on the client side within the `NetworkVariable.OnValueChanged` callback (if assigned) and `NetworkBehaviour.OnNetworkSpawn` method.
+If you need to update other components or objects based on the state of a `NetworkVariable`, then you can use a common method that's invoked within the  `NetworkBehaviour.OnNetworkSpawn` method and the `NetworkVariable.OnValueChanged` callback.
 :::
 
 ## Supported types
@@ -141,8 +154,8 @@ public class TestNetworkVariableSynchronization : NetworkBehaviour
  ```
 
 If you attach the above script to an in-scene placed NetworkObject, make a standalone build, run the standalone build as a host, and then connect to that host by entering Play Mode in the Editor, you can see (in the console output):
-- The client side `NetworkVariable` value is the same as the server when `NetworkBehaviour.OnNetworkSpawn` is invoked.  
-- The client detects any changes made to the `NetworkVariable` after the in-scene placed NetworkObject is spawned.  
+- The client side `NetworkVariable` value is the same as the server when `NetworkBehaviour.OnNetworkSpawn` is invoked.
+- The client detects any changes made to the `NetworkVariable` after the in-scene placed NetworkObject is spawned.
 
 This works the same way with dynamically spawned NetworkObjects.
 
@@ -152,6 +165,8 @@ The [synchronization and notification example](#synchronization-and-notification
 
 The `OnValueChanged` example shows a simple server-authoritative `NetworkVariable` being used to track the state of a door (that is, open or closed) using a non-ownership-based server RPC. With `RequireOwnership = false` any client can notify the server that it's performing an action on the door. Each time the door is used by a client, the `Door.ToggleServerRpc` is invoked and the server-side toggles the state of the door. When the `Door.State.Value` changes, all connected clients are synchronized to the (new) current `Value` and the `OnStateChanged` method is invoked locally on each client.
 
+It's important to note how [RPCs](../advanced-topics/message-system/rpc.md) can be used in tandem with `NetworkVariable` state. When an `RPC` call is used in tandem with a `NetworkVariable`, the `RPC` handles instantaneous notification of state, while the `NetworkVariable` handles synchronization across clients of that state.
+
 ```csharp
 public class Door : NetworkBehaviour
 {
@@ -599,7 +614,7 @@ public class TestFixedString : NetworkBehaviour
 
     public override void OnNetworkDespawn()
     {
-        m_TextString.OnValueChanged -= OnTextStringChanged;        
+        m_TextString.OnValueChanged -= OnTextStringChanged;
     }
 
     private void OnTextStringChanged(FixedString128Bytes previous, FixedString128Bytes current)
@@ -628,5 +643,5 @@ public class TestFixedString : NetworkBehaviour
 
 
 :::note
-The above example uses a pre-set list of strings to cycle through for example purposes only.  If you have a predefined set of text strings as part of your actual design then you would not want to use a FixedString to handle synchronizing the changes to `m_TextString`.  Instead, you would want to use a `uint` for the type `T` where the `uint` was the index of the string message to apply to `m_TextString`.  
+The above example uses a pre-set list of strings to cycle through for example purposes only.  If you have a predefined set of text strings as part of your actual design then you would not want to use a FixedString to handle synchronizing the changes to `m_TextString`.  Instead, you would want to use a `uint` for the type `T` where the `uint` was the index of the string message to apply to `m_TextString`.
 :::

docs/installation/installation.md

@@ -11,7 +11,7 @@ Follow the instructions on this page to set up Netcode for GameObjects in your U
 Before you begin, you need the following:
 
 - An active Unity account with a valid license.
-- A supported version of Unity. Check [Netcode for GameObjects' requirements](#netcode-installation-requirements) for the specific version details.
+- A supported version of Unity.
 - An existing Unity project. If you're new to Unity, you can refer to the [get started](../tutorials/get-started-with-ngo.md) section for guidance.
 
 ### Compatibility

docs/learn/bitesize/bitesize-usecases.md

@@ -17,6 +17,17 @@ Each scene includes a tutorial to help you locate the scripts and GameObjects it
 
 The tutorials that open with each scene use the [Tutorial Framework package](https://docs.unity3d.com/Packages/[email protected]/manual/index.html). You can open each tutorial at any time from the **Tutorials** menu.
 
+## The Anticipation scene
+
+The Anticipation scene demonstrates the Client Anticipation feature of Netcode for GameObjects in the following use cases: 
+- [`AnticipatedNetworkVariable`](https://docs.unity3d.com/Packages/[email protected]/api/Unity.Netcode.AnticipatedNetworkVariable-1.html):
+  - Anticipate server actions based on player interaction to change NetworkVariables responsively. 
+  - Compensate for latency that the server causes when it changes a value.
+  - Handle incorrect anticipation.
+- [`AnticipatedNetworkTransform`](https://docs.unity3d.com/Packages/[email protected]/api/Unity.Netcode.Components.AnticipatedNetworkTransform.html):
+  - Responsive server-authoritative player movement.
+  - Smooth player movement across clients.
+
 ## The NetvarVsRpc scene
 
 The NetvarVsRpc scene explains why to use NetworkVariables instead of Remote Procedure Calls (RPCs) to perform state synchronization.