Merge branch 'develop-2.0.0' into fix/networkanimator-allow-disabling-or-enabling-parameter-synch

Author: NoelStephensUnity

Tools/scripts/Utils/general_utils.py

@@ -1,4 +1,4 @@
-"""Helper class for common operations."""
+"""Helper class for common operations."""
 #!/usr/bin/env python3
 import json
 import os

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -10,12 +10,16 @@ Additional documentation and release notes are available at [Multiplayer Documen
 
 ### Added
 
+- Added NetworkRigidbody documentation section. (#3664)
 
 ### Changed
 
 - The `NetworkManager` functions `GetTransportIdFromClientId` and `GetClientIdFromTransportId` will now return `ulong.MaxValue` when the clientId or transportId do not exist. (#3707)
-- Improved performance of the NetworkVariable. (#3683)
-- Improved performance around the NetworkBehaviour component. (#3687)
+- Changed NetworkShow to send a message at the end of the frame and force a NetworkVariable synchronization prior to generating the CreateObjectMessage as opposed to waiting until the next network tick to synchronize the show with the update to NetworkVariables. (#3664)
+- Changed NetworkTransform now synchronizes `NetworkTransform.SwitchTransformSpaceWhenParented` when it is updated by the motion model authority. (#3664)
+- Changed when NetworkObjects pending to be shown to clients can now occur on partial network ticks. If any pending NetworkObjects pending to be shown to clients happens to be ready on a new network tick they still are shown after network variable deltas have been processed. (#3664)
+- Changed the default `NetworkDelivery` used by all messages is now reliable fragmented sequenced with the exception of named, unnamed, and any messages sent with a user specified network delivery type. This assures certain order of operations to be preserved when same call-stack changes are applied to a newly spawned, authority side, NetworkObject. (#3664)
+- Changed NetworkTransform documentation to better reflect the Teleport methods intended usage along with updates to NetworkObject and physics areas of the documentation. (#3664)
 - The first session owner no longer sends two synchronization messages to the service. (#3563)
 
 ### Deprecated
@@ -27,8 +31,8 @@ Additional documentation and release notes are available at [Multiplayer Documen
 ### Fixed
 
 - Multiple disconnect events from the same transport will no longer disconnect the host. (#3707)
-- Distributed authority clients no longer send themselves in the `ClientIds` list when sending a `ChangeOwnershipMessage`. (#3687)
-- Made a variety of small performance improvements. (#3683)
+- Fixed NetworkTransform state synchronization issue when `NetworkTransform.SwitchTransformSpaceWhenParented` is enabled and the associated NetworkObject is parented multiple times in a single frame or within a couple of frames. (#3664)
+- Fixed issue when spawning, parenting, and immediately re-parenting when `NetworkTransform.SwitchTransformSpaceWhenParented` is enabled. (#3664)
 - Fixed issue where the disconnect event and provided message was too generic to know why the disconnect occurred. (#3551)
 
 ### Security

com.unity.netcode.gameobjects/Documentation~/TableOfContents.md

@@ -32,8 +32,9 @@
     * [AttachableNode](components/helper/attachablenode.md)
     * [ComponentController](components/helper/componentcontroller.md)
     * [NetworkAnimator](components/helper/networkanimator.md)
+    * [NetworkRigidbody](components/helper/networkrigidbody.md)
     * [NetworkTransform](components/helper/networktransform.md)
-      * [Physics](advanced-topics/physics.md)
+  * [Physics](advanced-topics/physics.md)
 * [Spawning and despawning](spawn-despawn.md)
   * [Object spawning](basics/object-spawning.md)
   * [Network prefab handler](advanced-topics/network-prefab-handler.md)

com.unity.netcode.gameobjects/Documentation~/advanced-topics/physics.md

@@ -66,7 +66,8 @@ Dynamically spawned | In-scene placed (disabled NetworkBehaviour components)
 `OnNetworkSpawn`      | `OnNetworkSpawn`
 `Start`               | `Start` (invoked when disabled NetworkBehaviour components are enabled)
 
-> [!NOTE] Parenting, inactive GameObjects, and NetworkBehaviour components
+> [!NOTE]
+> Parenting, inactive GameObjects, and NetworkBehaviour components<br />
 > If you have child GameObjects that are not active in the hierarchy but are nested under an active GameObject with an attached NetworkObject component, then the inactive child GameObjects will not be included when the NetworkObject is spawned. This applies for the duration of the NetworkObject's spawned lifetime. If you want all child NetworkBehaviour components to be included in the spawn process, then make sure their respective GameObjects are active in the hierarchy before spawning the NetworkObject. Alternatively, you can just disable the NetworkBehaviour component(s) individually while leaving their associated GameObject active.
 > It's recommended to disable a NetworkBehaviour component rather than the GameObject itself.
 
@@ -165,7 +166,8 @@ Each NetworkBehaviour has a virtual `OnDestroy` method that you can override to
         }
 ```
 
-> [!NOTE] Destroying the GameObject
+> [!NOTE]
+> Destroying the GameObject<br />
 > When destroying a NetworkObject from within an associated NetworkBehaviour component script, you should always destroy the `NetworkObject.gameObject` and not the `NetworkBehaviour.gameObject` in case the NetworkBehaviour is located on a child GameObject nested under the NetworkObject's GameObject.
 
 ### Despawn process and invocation order

com.unity.netcode.gameobjects/Documentation~/components/core/networkbehaviour.md

@@ -41,11 +41,14 @@ The default `NetworkObject.Spawn` method assumes server-side ownership:
 GetComponent<NetworkObject>().Spawn();
 ```
 
-To spawn NetworkObjects with ownership use the following:
+To spawn a `NetworkObject` that is [owned](../../terms-concepts/ownership.md) by a different game client than the one doing the spawning, use the following:
 
 ```csharp
 GetComponent<NetworkObject>().SpawnWithOwnership(clientId);
 ```
+> [!NOTE]
+> The `SpawnWithOwnership` method allows a game client to spawn an object that it doesn't own. This means any owner-specific checks during the spawn sequence will not be invoked on the spawn authority side. Using `SpawnWithOwnership` can result in unexpected behavior if the spawn authority makes any additional post-spawn adjustments within the same frame.
+> To avoid potential issues, it's recommended to use `Spawn` if the spawn authority needs to make any adjustments post-spawn. After adjusting, the spawn authority can immediately follow with a call to `ChangeOwnership`.
 
 To change ownership, use the `ChangeOwnership` method:
 
@@ -58,6 +61,9 @@ To give ownership back to the server use the `RemoveOwnership` method:
 ```csharp
 GetComponent<NetworkObject>().RemoveOwnership();
 ```
+> [!NOTE]
+> `RemoveOwnership` isn't supported when using a [distributed authority network topology](../../terms-concepts/distributed-authority.md).
+
 
 To see if the local client is the owner of a NetworkObject, you can check the [`NetworkBehaviour.IsOwner`](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.NetworkBehaviour.IsOwner.html) property.
 

com.unity.netcode.gameobjects/Documentation~/components/core/networkobject.md

@@ -8,5 +8,6 @@ Understand the helper components available to use in your Netcode for GameObject
 | **[AttachableNode](attachablenode.md)**| Use an AttachableNode component to provide an attachment point for an [AttachableBehaviour](attachablebehaviour.md) component. |
 | **[ComponentController](componentcontroller.md)**| Use a [ComponentController](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.ComponentController.html) component to enable or disable one or more components depending on the authority state of the ComponentController and have those changes synchronized with non-authority instances. |
 | **[NetworkAnimator](networkanimator.md)**| The NetworkAnimator component provides you with a fundamental example of how to synchronize animations during a network session. Animation states are synchronized with players joining an existing network session and any client already connected before the animation state changing. |
+| **[NetworkRigidbody](networkrigidbody.md)**| NetworkRigidbody is a component that sets the Rigidbody of the GameObject into kinematic mode on all non-authoritative instances. |
 | **[NetworkTransform](networktransform.md)**| [NetworkTransform](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.Components.NetworkTransform.html) is a concrete class that inherits from [NetworkBehaviour](../core/networkbehaviour.md) and synchronizes [Transform](https://docs.unity3d.com/Manual/class-Transform.html) properties across the network, ensuring that the position, rotation, and scale of a [GameObject](https://docs.unity3d.com/Manual/working-with-gameobjects.html) are replicated to other clients. |
 | **[Physics](../../advanced-topics/physics.md)**| Netcode for GameObjects has a built in approach which allows for server-authoritative physics where the physics simulation only runs on the server. |

com.unity.netcode.gameobjects/Documentation~/components/helper/helpercomponents.md

@@ -121,5 +121,6 @@ public void SetPlayerJumping(bool isJumping)
 }
 ```
 
-> [!NOTE] Changing meshes
+> [!NOTE]
+> Changing meshes<br/>
 > When swapping a skinned mesh with another reparented skinned mesh, you can invoke the `Rebind ` method on the `Animator` components: `Animator.Rebind()`.

com.unity.netcode.gameobjects/Documentation~/components/helper/networkanimator.md

@@ -0,0 +1,42 @@
+# NetworkRigidbody
+
+NetworkRigidbody is a component that sets the Rigidbody of the GameObject into kinematic mode on all non-authoritative instances. Authority is determined by the [NetworkTransform component](networktransform.md) (required) attached to the same GameObject as the NetworkRigidbody. Whether the NetworkTransform is server authoritative (default) or owner authoritative, the NetworkRigidBody authority model will mirror it. That way, the physics simulation runs on the authoritative instance, and the resulting positions synchronize on the non-authoritative instances, each with their RigidBody being kinematic, without any interference.
+
+## Configure NetworkRigidbody
+
+![image](../../images/networktransform/NetworkRigidbody-fields.png)
+
+When looking at a NetworkRigidbody in the Inspector view, there are three exposed values:
+
+- __Use Rigid Body for Motion__
+  - When enabled and using a [NetworkTransform](networktransform.md), the NetworkTransform uses the PhysX position and rotation to synchronize changes during the `FixedUpdate` loop update stage.
+- __Auto Update Kinematic State__
+  - When enabled, NetworkRigidbody automatically determines whether the current instance should be kinematic or non-kinematic.
+  - For custom solutions, you can opt to disable this field or derive from [NetworkRigidbodyBase](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@2.5/api/Unity.Netcode.Components.NetworkRigidbodyBase.html) and design your own custom networked Rigidbody handler.
+- __Auto Set Kinematic On Despawn__
+  - When enabled, this option makes the rigid body kinematic when despawned (which can be useful for [object pools](../../advanced-topics/object-pooling.md)).
+
+Some collision events aren't fired when using NetworkRigidBody:
+
+- On the server, all collision and trigger events (such as `OnCollisionEnter`) fire as expected and you can access (and change) values of the `Rigidbody` (such as velocity).
+- On clients, Rigidbody is kinematic. Trigger events still fire but collision events won't fire when colliding with other networked Rigidbody instances if your project's physics settings is set to the default contact pairs.
+![image](../../images/networktransform/ProjectPhysicsSettings.png)
+
+- You can adjust the __Contact Pairs Mode__ to use kinematic and non-kinematic by setting it to __Enable All Contact Pairs__.![image](../../images/networktransform/ProjectPhysicsSettings2.png)
+
+> [!NOTE]
+> If there's a need for a gameplay event to happen on a collision, you can listen to the `OnCollisionEnter` function on the server and synchronize the event via `Rpc(SendTo.Everyone)` to all clients. If you plan on handling many collisions, then it's recommended to use the [RigidbodyContactEventManager component](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/api/Unity.Netcode.Components.RigidbodyContactEventManager.html) to handle collision checking during a job (`OnCollisionenter` can become expensive from a processing perspective if you have enough instances colliding).
+
+### NetworkRigidbody2D
+
+NetworkRigidbody2D works in the same way as NetworkRigidbody but for 2D physics (Rigidbody2D) instead.
+
+## Rigidbody interpolation example
+
+While NetworkTransform offers [interpolation](../../learn/clientside-interpolation.md) as a way to smooth between delta state updates, it doesn't get applied to the authoritative instance. You can use `Rigidbody.interpolation` for your authoritative instance while maintaining a strict server-authoritative motion model.
+
+To have a client control their owned objects, you can use either [RPCs](../../advanced-topics/message-system/rpc.md) or [NetworkVariables](../../basics/networkvariable.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 (such as 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 [refer to 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](https://docs.unity3d.com/Packages/com.unity.multiplayer.tools@latest?subfolder=/manual/network-simulator) to spot issues with latency.