doc: update

Adjusting based on the PR's recent updates.
Refactoring the physics section.
Moved the NetworkRigidbody content out of physics and into a new NetworkRigidbody section under componetns.
Moved physics up to the components layer.
Did a large update to the physics documentation and provided an additional walk through of  how to "parent" physics bodies using attachables.

Author: NoelStephensUnity

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

@@ -31,8 +31,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)      
 * [Ownership and authority](ownership-authority.md)
   * [Understanding ownership and authority](basics/ownership.md)
   * [Ownership race conditions](basics/race-conditions.md)

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

@@ -0,0 +1,43 @@
+# NetworkRigidbody
+
+__NetworkRigidbody__ is a component that sets the Rigidbody of the GameObject into kinematic mode on all non-authoritative instances (except the instance that has authority). Authority is determined by the NetworkTransform component (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.
+
+## Configuring NetworkRigidbody
+
+![image](../../images/networktransform/NetworkRigidbody-fields.png)
+
+When looking at a __NetworkRigidbody__ within the inspector view, you have three exposed values:
+
+- __Use Rigid Body for Motion__
+  - When enabled and using a [NetworkTransform](./networktransform.md), the __NetworkTransform__ will use the PhysX position and rotation to synchronize changes during the __FixedUpdate__ loop update stage.
+- __Auto Update Kinematic State__
+  - When enabled, __NetworkRigidbody__ will automatically determine if the current instance should be non-kinematic or kinematic.
+  - For custom solutions, you can opt to disable this field or derive from [NetworkRigidbodyBase](https://docs.unity3d.com/Packages/[email protected]/api/Unity.Netcode.Components.NetworkRigidbodyBase.html) and design your own custom network rigid body handler.
+- __Auto Set Kinematic On Despawn__
+  - This does exactly what it sounds like. When despawned, it will make the rigid body kinematic (_can be useful for object pools_).
+
+
+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 the `clients`, the `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 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 `OnCollisionEnter` function on the server and synchronize the event via `Rpc(SendTo.Everyone)` to all clients. If you plan on handling a bunch of collisions, then it is recommended to use the [RigidbodyContactEventManager](https://docs.unity3d.com/Packages/[email protected]/api/Unity.Netcode.Components.RigidbodyContactEventManager.html) in order 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 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](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 (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](https://docs.unity3d.com/Packages/com.unity.multiplayer.tools@latest?subfolder=/manual/network-simulator) to spot issues with latency.

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

@@ -147,7 +147,7 @@ Sometimes network conditions are poor, with packets experiencing latency and pot
 Of course, you might wonder what would happen if 5% of the end of a jumping motion were dropped and how NetworkTransform might recover since each state update sent is only based on axial deltas defined by each axis threshold setting. The answer is that there is a small bandwidth penalty for sending standard delta state updates unreliably,  full axial frame synchronization, which assures that in the event there is loss each NetworkTransform will be "auto-corrected" once per second.
 
 > [!NOTE]
-> When using a NetworkRigidbody or NetworkRigidbody2D component with the __Use Rigidbody for Motion__ property enabled, you should avoid using the __UseUnreliableDeltas____ NetworkTransform property because it can impact the overall interpolation result when you have multiple Rigidbody-based objects that need to keep relatively synchronized with each other.
+> When using a NetworkRigidbody or NetworkRigidbody2D component with the __Use Rigidbody for Motion__ property enabled, you should avoid using the __UseUnreliableDeltas____ NetworkTransform property because it can impact the overall interpolation result when you have multiple Rigidbody-based objects that need to keep relatively synchronized with each other. 
 
 #### Unreliable State Updates
 
@@ -175,19 +175,13 @@ When changing from world space to local space and vice versa, NetworkTransform c
 
 This means that non-authority instances could still have state updates pending to be processed when a NetworkObject is parented (or de-parented) and those buffered state values are still expressed as world (or local) space values. Since parenting is not network tick synchronized, the non-authority instances could still have the previous (world or local space) state updates remaining to be processed. This can create a visual "popping" result on the non-authority instance because it has been placed in a different Transform space while processing the previous Transform space state updates.
 
-To resolve this issue, you can enable the __Switch Transform Space When Parented__ configuration property and the NetworkTransform will automatically detect when its associated NetworkObject has changed its parented status, automatically switch to local or world space (parented or not parented), and convert the pending interpolator(s) states within each respective axis's `BufferedLinearInterpolator` to the appropriate Transform space values. The end result yields a seamless transition between world and local (and vice versa) space when parenting.
+To resolve this issue, you can enable the __Switch Transform Space When Parented__ configuration property and let NetworkTransform automatically detect when its associated NetworkObject has changed its parented status, automatically switch to local or world space (parented or not parented), and convert the pending interpolator(s) states within each respective axis's `BufferedLinearInterpolator` to the appropriate Transform space values. The end result yields a seamless transition between world and local (and vice versa) space when parenting. This is the recommended way to handle smooth transitions between world and local space when parenting.
 
 Things to consider when using __Switch Transform Space When Parented__:
 
-- This property isn't synchronized by the authority instance. If you disable it on the authority instance but the default setting in your network prefab is for it to be enabled, non-authority instances will remain enabled.
-  - You can opt to synchronize this setting via custom script or enabling and disabling it under other certain logical conditions in script (such as having it based on a condition and not synchronized by the authority).
-    - If you disable __Switch Transform Space When Parented__ and the associated NetworkObject gets parented and you manually switch from world to local space, then you will get the original parenting behavior where the interpolator is not updated when the switch occurs.
-    - You can opt to disable it while spawning and then make the default to enable it once finished spawning (within `OnNetworkPostSpawn` would be one way to handle this, for example).
-- While you can still change  __In Local Space__ directly via script while  __Switch Transform Space When Parented__ is enabled, this could impact the end results if you then proceed to parent the NetworkObject.
+- This property is synchronized by the authority instance. If you disable it on the authority instance then it will synchronize this adjustment on all non-authority instances.
 - When using __Switch Transform Space When Parented__, it's best to not make adjustments to the __NetworkTransform.InLocalSpace__ field and let the NetworkTransform handle this for you.
-
-> [!NOTE]
-> This feature's intended use is handling smooth transitions between world and local space after the NetworkObject has been spawned and is moving around. It's not intended to solve any issues you might run across if parenting in the middle of the spawn process.
+  - While you can still change __In Local Space__ directly via script while __Switch Transform Space When Parented__ is enabled, this could impact the end results. It is recommended to not adjust __In Local Space__ when __Switch Transform Space When Parented__ is enabled.
 
 ### Parenting
 
@@ -196,12 +190,15 @@ NetworkObject parenting can become complex when:
 - You are parenting a NetworkObject while it's [in motion](#in-motion).
 - You are parenting a NetworkObject [while spawning](#when-spawning) (depending upon network topology and the desired authority motion model).
 
-#### In motion
+#### Spawning or in motion
+
+The __Switch Transform Space When Parented__ field is intended to smooth the transition between world and local spaces. This setting is specifically designed to handle converting all of the non-authority instance's currently queued `NetworkTransformState`s to the appropriate transform space. When parenting, the transform space is automatically switched to local (transform) space on the authority instance that will then send this change in the transform space on the next network tick. This feature can also handle multiple parenting actions that occur on the same frame or over a few frames that are all within the normal network tick update period.
+
+When __Switch Transform Space When Parented__ is enabled, each parenting action will generate a unique transform message that is immediately added to the outbound message queued to preserve the order of operations. This means for each parenting event that occurs, a transform message will be generated. As such, it is recommended to not parent the same object dozens of times within the same frame to keep message traffic minimalized.
 
-The __Switch Transform Space When Parented__ field is intended to smooth the transition between world and local spaces. This setting is specifically designed to handle converting all of the non-authority instance's currently queued `NetworkTransformState`s to the appropriate transform space. When parenting, the transform space is automatically switched to local (transform) space on the authority instance that will then send this change in the transform space on the next network tick.
 
 > [!NOTE]
-> __Switch Transform Space When Parented__ is designed to work with the Unity transform's world and local space capabilities. However, when using a Rigidbody component and setting the NetworkRigidbody to use the Rigidbody for motion, the position and rotation values being synchronized are based on the Rigidbody's position and rotation values and not the Unity transform values. The Rigidbody position and rotation values are separate PhysX values that are adjusted during the `FixedUpdate` update loop stage. Because PhysX has no concept of local space, it's not recommended to enable this field when the authority is synchronizing the Rigidbody's position and rotation values.
+> __Switch Transform Space When Parented__ is designed to work with the Unity transform's world and local space capabilities. However, when using a Rigidbody component and setting the NetworkRigidbody to use the Rigidbody for motion, the position and rotation values being synchronized are based on the Rigidbody's position and rotation values and not the Unity transform values. The Rigidbody position and rotation values are separate PhysX values that are adjusted during the `FixedUpdate` update loop stage. Because PhysX has no concept of local space, it's not recommended to enable this field when the authority is synchronizing the Rigidbody's position and rotation values. [You can read more about parenting rigid bodies here](../../advanced-topics//physics.md).
 
 #### When spawning